内容
# 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
MCP 市场