Smart Docs MCP Server

# 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 ```bash 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` ```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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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 ```bash # 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