documcp

--- id: 006-mcp-tools-api-design title: "ADR-006: MCP Tools API Design and Interface Specification" sidebar_label: "ADR-006: MCP Tools API Design" sidebar_position: 6 --- # ADR-006: MCP Tools API Design and Interface Specification ## Status Accepted ## Context DocuMCP must expose its functionality through a carefully designed set of MCP tools that provide comprehensive coverage of the documentation deployment workflow while maintaining clear separation of concerns, appropriate granularity, and excellent developer experience for MCP-enabled clients. The MCP Tools API serves as the primary interface between DocuMCP's intelligence and client applications like GitHub Copilot, Claude Desktop, and other MCP-enabled development environments. This API must balance several competing concerns: **Functional Requirements:** - Comprehensive repository analysis capabilities - Intelligent SSG recommendation with detailed justifications - Automated configuration generation for multiple SSGs - Diataxis-compliant documentation structure creation - GitHub Pages deployment workflow generation - Git integration for seamless deployment **Usability Requirements:** - Intuitive tool names and parameter structures - Comprehensive input validation with clear error messages - Consistent response formats across all tools - Rich metadata for client presentation and user guidance - Progressive disclosure of complexity (simple to advanced use cases) **Technical Requirements:** - Full MCP specification compliance - Robust error handling and recovery - Efficient parameter validation and sanitization - Scalable architecture supporting complex multi-step workflows - Extensible design for future functionality additions ## Decision We will implement a comprehensive MCP Tools API consisting of six core tools that cover the complete documentation deployment workflow, with additional utility tools for advanced scenarios and troubleshooting. ### Core MCP Tools Architecture: #### 1. Repository Analysis Tool (`analyzeRepository`) **Purpose**: Comprehensive repository analysis and project characterization **Scope**: Deep analysis of project structure, language ecosystems, existing documentation, and complexity assessment #### 2. SSG Recommendation Tool (`recommendSSG`) **Purpose**: Intelligent static site generator recommendation with detailed justifications **Scope**: Multi-criteria decision analysis with confidence scoring and alternative options #### 3. Configuration Generation Tool (`generateConfiguration`) **Purpose**: Create customized SSG configuration files and directory structures **Scope**: Template-based generation with project-specific customizations and validation #### 4. Diataxis Structure Tool (`createDiataxisStructure`) **Purpose**: Generate comprehensive Diataxis-compliant documentation frameworks **Scope**: Information architecture generation with content planning and navigation design #### 5. Deployment Workflow Tool (`generateWorkflow`) **Purpose**: Create optimized GitHub Actions workflows for automated deployment **Scope**: SSG-specific workflow generation with security best practices and performance optimization #### 6. Git Integration Tool (`generateGitCommands`) **Purpose**: Provide ready-to-execute Git commands for deployment and maintenance **Scope**: Context-aware command generation with branch management and deployment verification ### Supporting Tools: - `validateConfiguration`: Validate generated configurations and identify issues - `troubleshootDeployment`: Analyze deployment failures and provide remediation guidance - `optimizePerformance`: Analyze and optimize existing documentation site performance - `migrateDocumentation`: Assist with migration between different SSGs or frameworks ## Alternatives Considered ### Monolithic Single Tool Approach - **Pros**: Simpler API surface, single entry point, easier client integration - **Cons**: Complex parameter structures, poor separation of concerns, difficult error handling - **Decision**: Rejected due to poor usability and maintainability ### Micro-Tool Architecture (15+ Small Tools) - **Pros**: Maximum granularity, precise control, composable workflows - **Cons**: Complex orchestration, cognitive overhead, fragmented user experience - **Decision**: Rejected due to complexity and poor user experience ### Stateful Session-Based API - **Pros**: Could maintain context across tool calls, simplified parameter passing - **Cons**: Session management complexity, state synchronization issues, harder client integration - **Decision**: Rejected to maintain MCP stateless principles ### External API Integration (REST/GraphQL) - **Pros**: Standard web technologies, extensive tooling ecosystem - **Cons**: Not MCP-compliant, additional infrastructure requirements, authentication complexity - **Decision**: Rejected due to MCP specification requirements ## Consequences ### Positive - **Clear Separation of Concerns**: Each tool has well-defined responsibility and scope - **Progressive Complexity**: Users can start simple and add sophistication as needed - **Excellent Error Handling**: Tool-specific validation and error reporting - **Client-Friendly**: Rich metadata and consistent response formats enhance client UX - **Extensible Architecture**: Easy to add new tools without breaking existing functionality ### Negative - **API Surface Complexity**: Six core tools plus supporting tools require comprehensive documentation - **Inter-Tool Coordination**: Some workflows require multiple tool calls with parameter passing - **Validation Overhead**: Each tool requires comprehensive input validation and error handling ### Risks and Mitigations - **API Complexity**: Provide comprehensive documentation and usage examples - **Parameter Evolution**: Use versioned schemas with backward compatibility - **Client Integration**: Offer reference implementations and integration guides ## Implementation Details ### Tool Parameter Schemas ```typescript // Core tool parameter interfaces interface AnalyzeRepositoryParams { repositoryPath: string; analysisDepth?: "basic" | "comprehensive" | "deep"; focusAreas?: ("structure" | "languages" | "documentation" | "complexity")[]; excludePatterns?: string[]; } interface RecommendSSGParams { projectAnalysis: ProjectAnalysis; teamCapabilities?: TeamCapabilities; performanceRequirements?: PerformanceRequirements; customizationNeeds?: CustomizationNeeds; existingConstraints?: ProjectConstraints; } interface GenerateConfigurationParams { selectedSSG: SSGType; projectAnalysis: ProjectAnalysis; customizations?: SSGCustomizations; deploymentTarget?: DeploymentTarget; advancedOptions?: AdvancedConfigOptions; } interface CreateDiataxisStructureParams { selectedSSG: SSGType; projectType: ProjectType; existingContent?: ExistingContentAnalysis; contentComplexity?: "minimal" | "standard" | "comprehensive"; navigationPreferences?: NavigationPreferences; } interface GenerateWorkflowParams { ssgType: SSGType; deploymentStrategy: "github-actions" | "branch-based" | "hybrid"; securityRequirements?: SecurityRequirements; performanceOptimizations?: PerformanceOptions; environmentConfiguration?: EnvironmentConfig; } interface GenerateGitCommandsParams { deploymentStrategy: DeploymentStrategy; repositoryState: RepositoryState; branchConfiguration: BranchConfiguration; commitPreferences?: CommitPreferences; } ``` ### Response Format Standardization ```typescript // Standardized response structure for all tools interface MCPToolResponse<T> { success: boolean; data?: T; error?: ErrorDetails; metadata: ResponseMetadata; recommendations?: Recommendation[]; nextSteps?: NextStep[]; } interface ResponseMetadata { toolVersion: string; executionTime: number; confidenceScore?: number; analysisDepth: string; timestamp: string; correlationId: string; } interface ErrorDetails { code: string; message: string; details: string; resolution?: string; documentation?: string; } interface Recommendation { type: "optimization" | "alternative" | "enhancement"; priority: "low" | "medium" | "high"; description: string; implementation?: string; resources?: string[]; } interface NextStep { action: string; description: string; toolRequired?: string; parameters?: Record<string, any>; estimated_time?: string; } ``` ### analyzeRepository Tool Implementation ```typescript const analyzeRepositoryTool: MCPTool = { name: "analyzeRepository", description: "Comprehensive repository analysis for documentation planning", inputSchema: { type: "object", properties: { repositoryPath: { type: "string", description: "Path to the repository to analyze", }, analysisDepth: { type: "string", enum: ["basic", "comprehensive", "deep"], default: "comprehensive", description: "Depth of analysis to perform", }, focusAreas: { type: "array", items: { type: "string", enum: ["structure", "languages", "documentation", "complexity"], }, description: "Specific areas to focus analysis on", }, excludePatterns: { type: "array", items: { type: "string" }, description: "File patterns to exclude from analysis", }, }, required: ["repositoryPath"], }, }; async function handleAnalyzeRepository( params: AnalyzeRepositoryParams, ): Promise<MCPToolResponse<RepositoryAnalysis>> { try { const analysis = await repositoryAnalyzer.analyze(params); return { success: true, data: analysis, metadata: { toolVersion: "1.0.0", executionTime: analysis.executionTime, analysisDepth: params.analysisDepth || "comprehensive", timestamp: new Date().toISOString(), correlationId: generateCorrelationId(), }, recommendations: generateAnalysisRecommendations(analysis), nextSteps: [ { action: "Get SSG Recommendation", description: "Use analysis results to get intelligent SSG recommendations", toolRequired: "recommendSSG", parameters: { projectAnalysis: analysis }, estimated_time: "< 1 minute", }, ], }; } catch (error) { return { success: false, error: { code: "ANALYSIS_FAILED", message: "Repository analysis failed", details: error.message, resolution: "Verify repository path and permissions", documentation: "https://documcp.dev/troubleshooting#analysis-errors", }, metadata: { toolVersion: "1.0.0", executionTime: 0, analysisDepth: params.analysisDepth || "comprehensive", timestamp: new Date().toISOString(), correlationId: generateCorrelationId(), }, }; } } ``` ### recommendSSG Tool Implementation ```typescript const recommendSSGTool: MCPTool = { name: "recommendSSG", description: "Intelligent static site generator recommendation with detailed justifications", inputSchema: { type: "object", properties: { projectAnalysis: { type: "object", description: "Repository analysis results from analyzeRepository tool", }, teamCapabilities: { type: "object", properties: { technicalSkills: { type: "array", items: { type: "string" } }, maintenanceCapacity: { type: "string", enum: ["minimal", "moderate", "extensive"], }, learningAppetite: { type: "string", enum: ["low", "medium", "high"] }, }, }, performanceRequirements: { type: "object", properties: { buildTimeImportance: { type: "string", enum: ["low", "medium", "high"], }, siteSpeedPriority: { type: "string", enum: ["standard", "fast", "ultra-fast"], }, scalabilityNeeds: { type: "string", enum: ["small", "medium", "large", "enterprise"], }, }, }, }, required: ["projectAnalysis"], }, }; async function handleRecommendSSG( params: RecommendSSGParams, ): Promise<MCPToolResponse<SSGRecommendation>> { const recommendation = await ssgRecommendationEngine.analyze(params); return { success: true, data: recommendation, metadata: { toolVersion: "1.0.0", executionTime: recommendation.analysisTime, confidenceScore: recommendation.confidence, analysisDepth: "comprehensive", timestamp: new Date().toISOString(), correlationId: generateCorrelationId(), }, recommendations: [ { type: "optimization", priority: "medium", description: "Consider performance optimization strategies", implementation: "Review build caching and incremental build options", }, ], nextSteps: [ { action: "Generate Configuration", description: "Create customized configuration for recommended SSG", toolRequired: "generateConfiguration", parameters: { selectedSSG: recommendation.primaryRecommendation.ssg, projectAnalysis: params.projectAnalysis, }, estimated_time: "2-3 minutes", }, ], }; } ``` ### Input Validation System ```typescript interface ValidationRule { field: string; validator: (value: any) => ValidationResult; required: boolean; errorMessage: string; } class MCPToolValidator { validateParameters<T>(params: T, schema: JSONSchema): ValidationResult { const results = this.runSchemaValidation(params, schema); const semanticResults = this.runSemanticValidation(params); return this.combineValidationResults(results, semanticResults); } private runSemanticValidation(params: any): ValidationResult { const issues: ValidationIssue[] = []; // Repository path validation if ( params.repositoryPath && !this.isValidRepositoryPath(params.repositoryPath) ) { issues.push({ field: "repositoryPath", message: "Repository path does not exist or is not accessible", severity: "error", resolution: "Verify the path exists and you have read permissions", }); } // Cross-parameter validation if (params.analysisDepth === "deep" && params.focusAreas?.length > 2) { issues.push({ field: "analysisDepth", message: "Deep analysis with multiple focus areas may be slow", severity: "warning", resolution: "Consider using comprehensive analysis or fewer focus areas", }); } return { valid: issues.length === 0, issues }; } } ``` ## Tool Orchestration Patterns ### Sequential Workflow Pattern ```typescript // Common workflow: Analysis → Recommendation → Configuration → Deployment class DocumentationWorkflow { async executeCompleteWorkflow( repositoryPath: string, ): Promise<WorkflowResult> { try { // Step 1: Analyze repository const analysisResult = await this.callTool("analyzeRepository", { repositoryPath, }); if (!analysisResult.success) { throw new Error(`Analysis failed: ${analysisResult.error?.message}`); } // Step 2: Get SSG recommendation const recommendationResult = await this.callTool("recommendSSG", { projectAnalysis: analysisResult.data, }); if (!recommendationResult.success) { throw new Error( `Recommendation failed: ${recommendationResult.error?.message}`, ); } // Step 3: Generate configuration const configResult = await this.callTool("generateConfiguration", { selectedSSG: recommendationResult.data.primaryRecommendation.ssg, projectAnalysis: analysisResult.data, }); if (!configResult.success) { throw new Error( `Configuration generation failed: ${configResult.error?.message}`, ); } // Step 4: Create Diataxis structure const structureResult = await this.callTool("createDiataxisStructure", { selectedSSG: recommendationResult.data.primaryRecommendation.ssg, projectType: analysisResult.data.projectType, }); if (!structureResult.success) { console.warn( `Diataxis structure creation failed: ${structureResult.error?.message}`, ); } // Step 5: Generate deployment workflow const workflowResult = await this.callTool("generateWorkflow", { ssgType: recommendationResult.data.primaryRecommendation.ssg, deploymentStrategy: "github-actions", }); if (!workflowResult.success) { console.warn( `Workflow generation failed: ${workflowResult.error?.message}`, ); } return this.combineResults([ analysisResult, recommendationResult, configResult, structureResult, workflowResult, ]); } catch (error) { throw new Error(`Complete workflow failed: ${error.message}`); } } } ``` ## Error Handling and Recovery ### Comprehensive Error Classification ```typescript enum ErrorCategory { VALIDATION = "validation", FILESYSTEM = "filesystem", ANALYSIS = "analysis", GENERATION = "generation", CONFIGURATION = "configuration", DEPLOYMENT = "deployment", NETWORK = "network", PERMISSION = "permission", } interface ErrorContext { tool: string; operation: string; parameters: Record<string, any>; environment: EnvironmentInfo; } class MCPErrorHandler { handleError(error: Error, context: ErrorContext): MCPToolResponse<null> { const classification = this.classifyError(error); const resolution = this.generateResolution(classification, context); return { success: false, error: { code: this.generateErrorCode(classification), message: this.formatUserMessage(error, classification), details: error.message, resolution: resolution.guidance, documentation: resolution.documentationUrl, }, metadata: this.generateErrorMetadata(context), nextSteps: resolution.suggestedActions, }; } private generateResolution( classification: ErrorClassification, context: ErrorContext, ): ErrorResolution { switch (classification.category) { case ErrorCategory.FILESYSTEM: return { guidance: "Verify file paths and permissions", documentationUrl: "https://documcp.dev/troubleshooting#filesystem-errors", suggestedActions: [ { action: "Check file exists", description: `Verify ${context.parameters.repositoryPath} exists`, }, { action: "Check permissions", description: "Ensure read access to repository directory", }, ], }; // ... other error categories } } } ``` ## Performance Optimization ### Response Caching Strategy ```typescript interface CacheConfiguration { analyzeRepository: { ttl: 300; keyFields: ["repositoryPath", "analysisDepth"]; }; recommendSSG: { ttl: 3600; keyFields: ["projectAnalysis.signature"] }; generateConfiguration: { ttl: 1800; keyFields: ["selectedSSG", "projectAnalysis.signature"]; }; } class MCPToolCache { async getCachedResponse<T>( toolName: string, parameters: any, ): Promise<MCPToolResponse<T> | null> { const cacheKey = this.generateCacheKey(toolName, parameters); const cached = await this.cache.get(cacheKey); if (cached && !this.isExpired(cached)) { return { ...cached, metadata: { ...cached.metadata, fromCache: true, cacheAge: Date.now() - cached.metadata.timestamp, }, }; } return null; } } ``` ## Testing Strategy ### Tool Testing Framework ```typescript describe("MCP Tools API", () => { describe("analyzeRepository", () => { it("should analyze JavaScript project correctly"); it("should handle missing repository gracefully"); it("should respect analysis depth parameters"); it("should exclude specified patterns"); }); describe("recommendSSG", () => { it("should recommend Hugo for large documentation sites"); it("should recommend Jekyll for GitHub Pages simple sites"); it("should provide confidence scores for all recommendations"); it("should handle incomplete project analysis"); }); describe("Tool Integration", () => { it("should support complete workflow from analysis to deployment"); it("should maintain parameter consistency across tool calls"); it("should provide appropriate next steps guidance"); }); }); ``` ### Integration Testing ```typescript class MCPToolIntegrationTests { async testCompleteWorkflow(): Promise<void> { const testRepo = await this.createTestRepository(); // Test full workflow const analysis = await this.callTool("analyzeRepository", { repositoryPath: testRepo, }); expect(analysis.success).toBe(true); const recommendation = await this.callTool("recommendSSG", { projectAnalysis: analysis.data, }); expect(recommendation.success).toBe(true); expect(recommendation.data.primaryRecommendation).toBeDefined(); const config = await this.callTool("generateConfiguration", { selectedSSG: recommendation.data.primaryRecommendation.ssg, projectAnalysis: analysis.data, }); expect(config.success).toBe(true); // Validate generated configuration await this.validateGeneratedFiles(config.data.files); } } ``` ## Documentation and Examples ### Tool Usage Examples ```typescript // Example: Complete documentation setup workflow const examples = { basicSetup: { description: "Basic documentation setup for a JavaScript project", steps: [ { tool: "analyzeRepository", parameters: { repositoryPath: "./my-project" }, expectedResult: "Project analysis with language ecosystem detection", }, { tool: "recommendSSG", parameters: { projectAnalysis: "${analysis_result}" }, expectedResult: "SSG recommendation with justification", }, ], }, advancedSetup: { description: "Advanced setup with custom requirements", steps: [ // ... detailed workflow steps ], }, }; ``` ## Future Enhancements ### Planned Tool Additions - `analyzeExistingDocs`: Deep analysis of existing documentation quality and structure - `generateMigrationPlan`: Create migration plans between different documentation systems - `optimizeContent`: AI-powered content optimization and gap analysis - `validateAccessibility`: Comprehensive accessibility testing and recommendations ### API Evolution Strategy - Versioned tool schemas with backward compatibility - Deprecation notices and migration guidance - Feature flags for experimental functionality - Community feedback integration for API improvements ## References - [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/) - [JSON Schema Validation](https://json-schema.org/) - [API Design Best Practices](https://swagger.io/resources/articles/best-practices-in-api-design/)