Smart Docs MCP Server

A production-ready Model Context Protocol (MCP) server that intelligently analyzes codebases and generates comprehensive documentation. Built with TypeScript and tree-sitter for accurate code parsing.

Features

• Multi-Language Support: Analyze TypeScript, JavaScript, and Python codebases
• Smart Analysis: Extract functions, classes, methods, interfaces, types, and variables
• Documentation Coverage: Calculate documentation coverage metrics
• Missing Doc Detection: Identify undocumented code with severity levels (critical, medium, low)
• AI-Powered Suggestions: Generate documentation templates and improvement recommendations
• Markdown Output: Professional documentation in markdown format

Installation

npm install
npm run build

Usage

As an MCP Server

Add to your MCP client configuration (Claude Desktop):

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "smart-docs": {
      "command": "node",
      "args": ["C:\\ProjectFolder\\dist\\index.js"]
    }
  }
}

Then restart Claude Desktop.

Available Tools

1. analyze_codebase

Analyze a codebase or file to extract code elements and calculate documentation coverage.

Input:

{
  "path": "/path/to/your/codebase"
}

Output:

• Total files analyzed
• Total code elements found
• Documentation coverage percentage
• Detailed breakdown by file and element

2. generate_documentation

Generate comprehensive markdown documentation for a codebase.

Input:

{
  "path": "/path/to/your/codebase",
  "format": "markdown"
}

Output:

• Complete markdown documentation
• Summary statistics
• Organized by file and element type

3. detect_missing_docs

Detect code elements missing documentation with severity classification.

Input:

{
  "path": "/path/to/your/codebase",
  "minSeverity": "critical"
}

Severity Levels:

• Critical: Public classes, interfaces, and exported functions
• Medium: Type aliases and exported types
• Low: Private methods and internal variables

Output:

• List of missing documentation by severity
• Summary statistics by severity and type
• Detailed element information

4. suggest_improvements

Analyze existing documentation and suggest improvements.

Input:

{
  "path": "/path/to/your/codebase",
  "limit": 20
}

Output:

• Documentation templates for missing docs
• Suggestions for incomplete documentation
• Parameter and return value documentation hints

Project Structure

smart-docs-mcp/
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── types/
│   │   └── index.ts               # TypeScript types and interfaces
│   ├── parsers/
│   │   ├── base-parser.ts         # Abstract parser base class
│   │   ├── typescript-parser.ts   # TypeScript/JavaScript parser
│   │   └── python-parser.ts       # Python parser
│   ├── analyzers/
│   │   ├── codebase-analyzer.ts   # Main analysis engine
│   │   └── doc-detector.ts        # Missing documentation detector
│   ├── generators/
│   │   ├── markdown-generator.ts  # Markdown doc generator
│   │   └── improvement-suggester.ts # Improvement suggestions
│   ├── tools/
│   │   ├── analyze-codebase.ts
│   │   ├── generate-documentation.ts
│   │   ├── detect-missing-docs.ts
│   │   └── suggest-improvements.ts
│   └── utils/
│       └── file-utils.ts          # File system utilities
├── package.json
├── tsconfig.json
└── README.md

How It Works

1. Parsing: Uses tree-sitter to parse source code into Abstract Syntax Trees (AST)
2. Extraction: Identifies code elements (functions, classes, etc.) from the AST
3. Documentation Detection: Checks for JSDoc, docstrings, and inline comments
4. Analysis: Calculates coverage and detects missing documentation
5. Generation: Creates markdown documentation and improvement suggestions

Severity Classification

The server uses intelligent severity classification:

• Public APIs (classes, interfaces, exported functions) → Critical
• Type definitions and complex types → Medium
• Private methods and internal variables → Low

Error Handling

All tools include comprehensive error handling:

• Invalid paths return descriptive error messages
• Unsupported file types are gracefully skipped
• Parse errors include file location and context

Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run watch

# Run the server
npm start

Requirements

• Node.js >= 18.0.0
• TypeScript 5.3+

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• tree-sitter: Code parsing engine
• tree-sitter-typescript: TypeScript/JavaScript grammar
• tree-sitter-python: Python grammar
• zod: Schema validation

Testing

A test project is included in the test-project/ directory with sample files demonstrating various documentation scenarios.

License

MIT

Contributing

Contributions are welcome! Please ensure:

• Code follows TypeScript best practices
• All new features include error handling
• Documentation is updated according