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
- Distinctive: line 50
Search tools use case-insensitive string matching across content
- Distinctive: line 81
All tools follow this pattern:
- Distinctive: line 84
Search/filter the in-memory documentation arrays
- Distinctive: line 91
Search returns no results: provides search suggestions
- Distinctive: line 99
Create git tag: git tag v2.0.1
- Distinctive: line 132
Read-only: Only reads bundled documentation files
- Distinctive: line 134
No writes: Never modifies files
- Distinctive: line 135
Pre-bundled: All documentation included in NPM package
- Very specific: line 142
Add tool definition to ListToolsRequestSchema handler (src/index.ts:163-297)
- Very specific: line 143
Add case to switch statement in CallToolRequestSchema handler (src/index.ts:303-340)
≈ “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.
Files
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-docsTesting During Development
# After making changes to src/index.ts:
npm run build && npm testArchitecture
Core Structure
The codebase implements a single-file MCP server with three main responsibilities:
- Documentation Loading (
src/index.ts:89-160)- Loads markdown files from
docs/(49 components),rules/(6 design rules), andsetup/(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
- Loads markdown files from
- MCP Tool Registration (
src/index.ts:162-350)- Registers 10 MCP tools via
ListToolsRequestSchemahandler - Handles tool invocations via
CallToolRequestSchemahandler - Tools are categorized: 4 component tools, 3 design rule tools, 3 setup tools
- Registers 10 MCP tools via
- 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 DesktopThe 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 startupKey Implementation Details
Path Resolution Strategy
The server tries multiple paths to find documentation directories:
dist/../docs- Development mode (when running from built files in dist/)dist/docs- Production mode (when docs are copied into dist/)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):
- Update
package.jsonversion - Create git tag:
git tag v2.0.1 - Push tag:
git push origin v2.0.1 - 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
- Add tool definition to
ListToolsRequestSchemahandler (src/index.ts:163-297) - Add case to switch statement in
CallToolRequestSchemahandler (src/index.ts:303-340) - Implement private async method following the pattern of existing tools (src/index.ts:352-757)
- 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 GitHubThe 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"]
}
}
}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
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.

