agentleFS
julianoczkowskijulianoczkowski/mcp-modus/CLAUDE.md

mcp-modus

CLAUDE.md4 starsChanged 14 months agoMITView on GitHub

MCP Modus is a Model Context Protocol (MCP) server that provides AI assistants with access to Modus Web Components documentation. It runs as a standalone Node.js process that communicates via stdio using JSON-RPC, serving documentation from pre-bundled files. The codebase implements a single-file MCP server with three main responsibilities: The server never writes files or makes network calls at runtime. All documentation is pre-bundled during the build/publish process. The server tries multiple paths to find documentation directories: 1. dist/../docs -…

  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search tools use case-insensitive string matching across content

    line 50
  2. Distinctive:

    All tools follow this pattern:

    line 81
  3. Distinctive:

    Search/filter the in-memory documentation arrays

    line 84
  4. Distinctive:

    Search returns no results: provides search suggestions

    line 91
  5. Distinctive:

    Create git tag: git tag v2.0.1

    line 99
  6. Distinctive:

    Read-only: Only reads bundled documentation files

    line 132
  7. Distinctive:

    No writes: Never modifies files

    line 134
  8. Distinctive:

    Pre-bundled: All documentation included in NPM package

    line 135
  9. Very specific:

    Add tool definition to ListToolsRequestSchema handler (src/index.ts:163-297)

    line 142
  10. Very specific:

    Add case to switch statement in CallToolRequestSchema handler (src/index.ts:303-340)

    line 143

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP Modus is a Model Context Protocol (MCP) server that provides AI assistants with access to Modus Web Components documentation. It runs as a standalone Node.js process that communicates via stdio using JSON-RPC, serving documentation from pre-bundled files.

Development Commands

Build & Development

# Build TypeScript to JavaScript (required before testing/running)
npm run build

# Watch mode for development (auto-rebuild on changes)
npm run watch

# Test the server (runs the built server via dist/index.js)
npm test

# Update documentation from GitHub (downloads latest docs)
npm run update-docs

Testing During Development

# After making changes to src/index.ts:
npm run build && npm test

Architecture

Core Structure

The codebase implements a single-file MCP server with three main responsibilities:

  1. Documentation Loading (src/index.ts:89-160)
    • Loads markdown files from docs/ (49 components), rules/ (6 design rules), and setup/ (5 guides)
    • Parses filenames to extract component names and categories
    • Stores in-memory arrays: this.docs, this.rules, this.setup
    • Path resolution handles both development (dist/../docs) and production (dist/docs) layouts
  2. MCP Tool Registration (src/index.ts:162-350)
    • Registers 10 MCP tools via ListToolsRequestSchema handler
    • Handles tool invocations via CallToolRequestSchema handler
    • Tools are categorized: 4 component tools, 3 design rule tools, 3 setup tools
  3. Tool Implementations (src/index.ts:352-757)
    • Search tools use case-insensitive string matching across content
    • Get tools use direct lookups with normalized names
    • List tools organize data by categories extracted from markdown frontmatter

Communication Flow

IDE/Claude Desktop → stdio (JSON-RPC) → MCP Server (Node.js) → in-memory docs → stdio (JSON-RPC) → IDE/Claude Desktop

The server never writes files or makes network calls at runtime. All documentation is pre-bundled during the build/publish process.

Documentation Pipeline

GitHub (QAUI-Modus-Web-Components repo) → download-docs.js → local docs/rules/setup dirs → bundled in NPM package → loaded at server startup

Key Implementation Details

Path Resolution Strategy

The server tries multiple paths to find documentation directories:

  1. dist/../docs - Development mode (when running from built files in dist/)
  2. dist/docs - Production mode (when docs are copied into dist/)
  3. process.cwd()/docs - Fallback to current working directory

This pattern is repeated for docs/, rules/, and setup/ directories.

Tool Implementation Patterns

All tools follow this pattern:

  • Accept string parameters (query, component name, category)
  • Normalize input (lowercase, remove prefixes like "modus-wc-")
  • Search/filter the in-memory documentation arrays
  • Return MCP-formatted responses with content: [{ type: "text", text: "..." }]

Error Handling

Tools return helpful error messages when:

  • Documentation not found: suggests available options
  • Search returns no results: provides search suggestions
  • Directories missing: instructs to run node download-docs.js

Publishing Workflow

The project uses automated publishing via GitHub Actions with NPM OIDC authentication (no stored tokens):

  1. Update package.json version
  2. Create git tag: git tag v2.0.1
  3. Push tag: git push origin v2.0.1
  4. GitHub Actions workflow automatically:
    • Downloads documentation
    • Builds TypeScript
    • Verifies at least 40 doc files exist
    • Publishes to NPM with OIDC auth
    • Creates GitHub release with changelog

IMPORTANT: The server version in src/index.ts:48 is hardcoded to "1.0.0" and should remain static. The actual package version is in package.json.

File Structure

src/index.ts           # Single-file MCP server implementation (~768 lines)
download-docs.js       # Documentation downloader (runs during build/CI)
docs/                  # 49 component markdown files (downloaded, not in git)
rules/                 # 6 design rule markdown files (downloaded, not in git)
setup/                 # 5 setup guide markdown files (downloaded, not in git)
dist/                  # Compiled JavaScript output (generated by tsc)

TypeScript Configuration

  • Target: ES2022
  • Module system: Node16 (ESM with .js extensions in imports)
  • Strict mode enabled
  • Generates declaration files (.d.ts) with source maps
  • Output directory: dist/

Security Model

The server is designed for security and offline operation:

  • Read-only: Only reads bundled documentation files
  • No network: Zero network calls at runtime
  • No writes: Never modifies files
  • Pre-bundled: All documentation included in NPM package
  • OIDC auth: Publishes via OpenID Connect (no stored tokens)

Common Development Tasks

Adding a New Tool

  1. Add tool definition to ListToolsRequestSchema handler (src/index.ts:163-297)
  2. Add case to switch statement in CallToolRequestSchema handler (src/index.ts:303-340)
  3. Implement private async method following the pattern of existing tools (src/index.ts:352-757)
  4. Return MCP-formatted response: { content: [{ type: "text", text: "..." }] }

Updating Documentation

Documentation is fetched from the QAUI-Modus-Web-Components GitHub repository:

npm run update-docs  # Downloads latest from GitHub

The download script (download-docs.js) fetches from three directories:

  • components_LLM_docs/ → docs/
  • rules_LLM_docs/ → rules/
  • setup_LLM_docs/ → setup/

Testing Locally

The server uses stdio transport, so testing requires simulating MCP client communication. The npm test command simply runs the server to verify it starts without errors.

For real testing, configure the server in an MCP client (Claude Desktop, Cursor, or VS Code with Continue) using:

{
  "mcpServers": {
    "modus-docs-dev": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-modus/dist/index.js"]
    }
  }
}

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.