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
- Parsing: Uses tree-sitter to parse source code into Abstract Syntax Trees (AST)
- Extraction: Identifies code elements (functions, classes, etc.) from the AST
- Documentation Detection: Checks for JSDoc, docstrings, and inline comments
- Analysis: Calculates coverage and detects missing documentation
- 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 implementationtree-sitter: Code parsing enginetree-sitter-typescript: TypeScript/JavaScript grammartree-sitter-python: Python grammarzod: 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