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

// 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

// 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

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

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

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

// 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

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

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

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

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

// 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
• JSON Schema Validation
• API Design Best Practices