documcp

# DocuMCP AI Coding Agent Instructions DocuMCP is an intelligent MCP server for GitHub Pages documentation deployment with 45+ tools, Knowledge Graph memory system, and AST-based code analysis. ## Architecture Essentials ### MCP Server Design (src/index.ts) - **Stateless operation**: Each tool analyzes current state; no persistent session data - **Resource storage**: Temporary session context in `resourceStore` Map with URIs like `documcp://analysis/{id}` - **Response format**: ALL tools MUST use `formatMCPResponse()` from `src/types/api.ts` returning `MCPToolResponse` - **Memory integration**: Tools auto-store results in JSONL (`.documcp/memory/`) and query historical data ### Tool Implementation Pattern Every tool follows this structure: 1. Zod schema for input validation (e.g., `inputSchema.parse()`) 2. Business logic with error handling 3. Return via `formatMCPResponse({ success, data, metadata, recommendations?, nextSteps? })` 4. Store result as resource: `storeResourceFromToolResult(result, 'analysis', analysis.id)` **Example** (see `src/tools/analyze-repository.ts`): ```typescript const inputSchema = z.object({ path: z.string(), depth: z.enum(["quick", "standard", "deep"]).optional(), }); export async function analyzeRepository( args: unknown, ): Promise<MCPToolResponse> { const input = inputSchema.parse(args); // ... logic ... return formatMCPResponse({ success: true, data: analysis, metadata: { toolVersion, executionTime, timestamp }, }); } ``` ### Knowledge Graph Memory (src/memory/) - **Entities**: Project, User, Configuration, Technology, CodeFile, DocumentationSection (see `src/memory/schemas.ts`) - **Relationships**: `project_uses_technology`, `project_deployed_with`, `similar_to`, `documents`, etc. - **Storage**: `.documcp/memory/knowledge-graph-entities.jsonl` and `knowledge-graph-relationships.jsonl` - **Integration**: Use `createOrUpdateProject()`, `getProjectContext()`, `trackDeployment()` from `src/memory/kg-integration.ts` **analyze_repository enhancement**: Retrieves project history before analysis, shows previous analysis count, similar projects ## Development Workflows ### Essential Commands ```bash npm run build # Compile TypeScript → dist/ npm run dev # Development watch mode with tsx npm test # Run Jest test suite npm run test:coverage # Coverage report (80% threshold) npm run build:inspect # Launch MCP Inspector for interactive testing npm run ci # Full CI pipeline: typecheck + lint + test + build make qa # Quality assurance: lint + types + test + coverage ``` ### Testing Strategy - **Location**: `tests/` mirroring `src/` structure - **Coverage**: 80% global (branches/functions/lines), 60% for `recommend-ssg.ts` (complex logic) - **Excluded**: Experimental memory features, `src/index.ts` entry point - **Pattern**: Use `formatMCPResponse()` for consistent response validation - **Integration**: Multi-tool workflow tests in `tests/integration/` ### MCP Inspector Workflow 1. `npm run build:inspect` opens browser at `http://localhost:5173` 2. Click "Connect" to attach to server 3. Test tools with custom parameters interactively 4. Verify resources/prompts without full integration ## Project-Specific Conventions ### ESM Module Requirements - **ALL imports** must end with `.js` (even for `.ts` files): `import { foo } from './utils.js'` - Use `import type` for type-only imports: `import type { MyType } from './types.js'` - File URLs: `fileURLToPath(import.meta.url)` and `dirname()` ### Path & Permission Handling - **Security**: Use `isPathAllowed(path, allowedRoots)` from `src/utils/permission-checker.ts` before file operations - **Async FS**: Always use `fs.promises` API, never sync methods - **Cross-platform**: Use `path` module for joining/resolving ### Git Integration - Use `simple-git` library for repository operations - Handle missing `.git` directories gracefully (check `hasGit` flag) - Always validate repo state before analysis ### Diataxis Framework Documentation structured as: - **Tutorials**: Learning-oriented (getting started) - **How-To Guides**: Problem-solving (specific tasks) - **Reference**: Information-oriented (API docs) - **Explanation**: Understanding-oriented (architecture, concepts) Tools like `setup-structure` and `populate-content` enforce this structure. ## Critical Implementation Details ### Phase 3: AST-Based Code Analysis - **AST Parser** (`src/utils/ast-analyzer.ts`): Multi-language support via Tree-sitter (TypeScript, Python, Go, Rust, Java, Ruby, Bash) - **Drift Detection** (`src/utils/drift-detector.ts`): Snapshot-based comparison, categorizes changes (breaking/major/minor/patch) - **Sync Tool** (`src/tools/sync-code-to-docs.ts`): Modes: detect/preview/apply/auto, confidence threshold (default 0.8) - **Content Generator** (`src/tools/generate-contextual-content.ts`): Creates Diataxis-compliant docs from actual code structure **Example drift detection**: ```typescript // Detects function signature changes, new/removed classes, breaking changes const drift = await detectDrift({ projectPath, docsPath, snapshotDir }); drift.affectedFiles.forEach((f) => console.log(f.driftType, f.severity)); ``` ### Error Handling Pattern ```typescript try { // tool logic return formatMCPResponse({ success: true, data: result, metadata }); } catch (error) { return formatMCPResponse({ success: false, error: { code: "TOOL_ERROR", message: error.message, resolution: "Check inputs and try again", }, metadata, }); } ``` ### Adding New Tools Checklist 1. Create `src/tools/my-tool.ts` with Zod schema and logic 2. Export tool function returning `MCPToolResponse` 3. Add to `TOOLS` array in `src/index.ts` with name, description, inputSchema 4. Add handler in `CallToolRequestSchema` switch case 5. Store result: `storeResourceFromToolResult(result, 'type', id)` 6. Create tests: `tests/tools/my-tool.test.ts` 7. Run `npm run ci` to validate ## Key Integration Points ### Memory Query Patterns ```typescript // Query similar projects by analysis results const similar = await getSimilarProjects(analysisResult, limit); // Get project insights with historical context const insights = await getProjectInsights(projectPath); // Export/import memory for backup await exportMemories({ outputPath: "./backup.json" }); await importMemories({ inputPath: "./backup.json" }); ``` ### Resource Storage Pattern ```typescript // Tools create resources for cross-tool reference resourceStore.set(`documcp://analysis/${id}`, { uri: `documcp://analysis/${id}`, name: `Repository Analysis ${id}`, mimeType: "application/json", text: JSON.stringify(result, null, 2), }); ``` ### ADR References - **ADR-001**: TypeScript MCP SDK chosen over Python/Go for ecosystem maturity - **ADR-002**: Multi-layered repository analysis (structure + dependencies + documentation) - **ADR-003**: Algorithmic SSG recommendation with confidence scoring - **ADR-006**: Consistent tool API design with Zod validation - **ADR-010**: Resource pattern redesign for session-based storage Full ADRs: `docs/adrs/` ## Common Pitfalls - ❌ Forgetting `.js` extension in imports → Module resolution fails - ❌ Using `formatMCPResponse()` incorrectly → Response validation errors - ❌ Missing Zod schema validation → Runtime type errors - ❌ Synchronous file operations → Blocking operations - ❌ Not checking path permissions → Security vulnerabilities - ❌ Returning raw objects instead of `MCPToolResponse` → Protocol violations ## Quick Reference **Node.js**: ≥20.0.0 | **Module**: ESM | **Test Framework**: Jest (ts-jest) | **Storage**: `.documcp/memory/` (JSONL) **MCP Inspector**: `npm run build:inspect` | **Full test suite**: `npm run ci` | **Docs**: `docs/` (Docusaurus)