Smart Docs MCP Server

Instructions

Implementation Reference

• src/tools/detect-missing-docs.ts:12-61 (handler)

  The primary handler function for the 'detect_missing_docs' tool. Analyzes the specified path using CodebaseAnalyzer, detects missing documentation with DocDetector, applies severity filtering, generates a summary, and returns structured results with success status and details.

  export async function detectMissingDocs(input: DetectMissingDocsInput) {
    try {
      const analyzer = new CodebaseAnalyzer();
      const results = await analyzer.analyzePath(input.path);
  
      if (results.length === 0) {
        return {
          success: false,
          error: 'No supported source files found in the specified path'
        };
      }
  
      const detector = new DocDetector();
      const allMissing = detector.detectMissingDocs(results);
      
      // Filter by severity
      const severityOrder = { critical: 3, medium: 2, low: 1 };
      const minLevel = severityOrder[input.minSeverity as keyof typeof severityOrder];
      
      const filtered = allMissing.filter(m => 
        severityOrder[m.severity as keyof typeof severityOrder] >= minLevel
      );
  
      const summary = detector.getSummary(allMissing);
  
      return {
        success: true,
        summary: {
          total: allMissing.length,
          filtered: filtered.length,
          bySeverity: summary.bySeverity,
          byType: summary.byType
        },
        missing: filtered.map(m => ({
          file: m.element.filePath,
          line: m.element.line,
          type: m.element.type,
          name: m.element.name,
          severity: m.severity,
          reason: m.reason,
          signature: m.element.signature
        }))
      };
    } catch (error) {
      return {
        success: false,
        error: (error as Error).message
      };
    }
  }

• src/tools/detect-missing-docs.ts:5-8 (schema)

  Zod schema defining the input for the 'detect_missing_docs' tool: path to analyze and optional minimum severity threshold.

  export const DetectMissingDocsSchema = z.object({
    path: z.string().describe('Path to file or directory to analyze'),
    minSeverity: z.enum(['critical', 'medium', 'low']).default('low').describe('Minimum severity level to report')
  });

• src/index.ts:58-61 (registration)

  Tool registration in the TOOLS array used for listing available tools, specifying name, description, and input schema.

    name: 'detect_missing_docs',
    description: 'Detect code elements that are missing documentation and categorize them by severity (critical, medium, low).',
    inputSchema: DetectMissingDocsSchema
  },

• src/index.ts:121-132 (registration)

  Dispatch handler in the CallToolRequest switch statement that validates input, calls the detectMissingDocs function, and formats the response.

  case 'detect_missing_docs': {
    const validated = DetectMissingDocsSchema.parse(args);
    const result = await detectMissingDocs(validated);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  }

• src/analyzers/doc-detector.ts:4-20 (helper)

  Core helper method in DocDetector class that scans analysis results for undocumented code elements, assigns severity and reasons, and sorts by priority.

  detectMissingDocs(results: AnalysisResult[]): MissingDocumentation[] {
    const missing: MissingDocumentation[] = [];
  
    for (const result of results) {
      for (const element of result.elements) {
        if (!element.hasDocumentation) {
          missing.push({
            element,
            severity: this.determineSeverity(element),
            reason: this.getReason(element)
          });
        }
      }
    }
  
    return missing.sort((a, b) => this.severityWeight(b.severity) - this.severityWeight(a.severity));
  }