documcp copilot-instructions.md

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):

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