# 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