# 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
```bash
# 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
```bash
# 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:
```bash
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:
```json
{
"mcpServers": {
"modus-docs-dev": {
"command": "node",
"args": ["/absolute/path/to/mcp-modus/dist/index.js"]
}
}
}
```
