API.md•23.4 kB
# CodeCompass MCP API Reference
This document provides comprehensive documentation for all 18 tools available in the CodeCompass MCP server.
## Response Format
All tools return responses in this standardized format:
```json
{
"success": true,
"data": { /* tool-specific data */ },
"metadata": {
"processing_time": 1234,
"rate_limit_remaining": 4999,
"cache_hit": false,
"truncated": false, // Present when response is truncated
"truncationReason": "Response size exceeded maximum token limit",
"maxTokens": 25000,
"estimatedTokens": 18500,
"suggestion": "Use max_response_tokens and max_file_content_length options to control response size"
},
"error": { // Only present if success: false
"code": "ERROR_CODE",
"message": "Error description",
"details": { /* additional error info */ }
}
}
```
### Response Size Management
The server offers two approaches to handle large repository responses:
#### 1. **Truncation Mode (Default)**
Automatically truncates responses when they exceed token limits:
- **Default limit**: 25,000 tokens (approximately 100KB of JSON)
- **Token estimation**: 1 token ≈ 4 characters in JSON format
- **Truncation order**: File contents → File tree depth → Metadata
#### 2. **Chunking Mode (Recommended for Large Repos)**
Splits large responses into multiple manageable chunks:
- **No data loss**: Access all repository content across multiple requests
- **Chunk sizes**: "small" (~10k tokens), "medium" (~20k tokens), "large" (~40k tokens)
- **Pagination**: Use `chunk_index` to navigate through chunks
**Control options**:
- `max_response_tokens`: Set custom token limit (1,000 - 100,000)
- `max_file_content_length`: Limit individual file content length (100 - 10,000 chars)
- `chunk_mode`: Enable chunked responses (true/false)
- `chunk_index`: Specify which chunk to retrieve (0-based)
- `chunk_size`: Choose chunk size ("small", "medium", "large")
When truncation occurs, the response includes truncation metadata. When chunking is enabled, the response includes chunk navigation information.
## Core Data Tools
### 1. `fetch_repository_data`
**Description**: Comprehensive repository analysis and metadata retrieval.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"options": {
"include_structure": true,
"include_dependencies": true,
"include_key_files": true,
"max_files": 50,
"file_extensions": [".js", ".ts"],
"max_response_tokens": 25000,
"max_file_content_length": 1000
}
}
```
**Option Details**:
- `include_structure` (boolean): Include file tree structure (default: true)
- `include_dependencies` (boolean): Include dependency analysis (default: true)
- `include_key_files` (boolean): Include key file contents (README, package.json, etc.) (default: true)
- `max_files` (number): Maximum number of files to analyze (default: 50)
- `file_extensions` (array): File extensions to focus on (e.g., [".js", ".ts"])
- `max_response_tokens` (number): Maximum response size in tokens (default: 25000, range: 1000-100000)
- `max_file_content_length` (number): Maximum content length per file (default: 1000, range: 100-10000)
- `chunk_mode` (boolean): Enable chunked responses for large repositories (default: false)
- `chunk_index` (number): Chunk index to retrieve (0-based, use with chunk_mode) (default: 0)
- `chunk_size` (string): Chunk size - "small", "medium", or "large" (default: "medium")
**Response**:
```json
{
"success": true,
"data": {
"info": {
"name": "repository-name",
"description": "Repository description",
"language": "JavaScript",
"owner": "owner-name",
"stars": 1234,
"forks": 567,
"created_at": "2024-01-01T00:00:00Z"
},
"structure": {
"fileCount": 150,
"lineCount": 10000,
"fileTree": { /* file structure */ },
"keyFiles": { /* key file contents */ }
},
"dependencies": { /* dependency analysis */ },
"architecture": { /* architecture analysis */ }
}
}
```
### 2. `search_repository`
**Description**: Advanced search within repositories with filtering and context.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"query": "search pattern",
"search_type": "text|regex|function|class|variable|import",
"options": {
"case_sensitive": false,
"file_extensions": [".js", ".ts"],
"exclude_paths": ["node_modules", "dist"],
"max_results": 100,
"include_context": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"results": [
{
"file": "path/to/file.js",
"line": 42,
"match": "matched code",
"context": "surrounding code context"
}
],
"total_matches": 15,
"files_searched": 100
}
}
```
### 3. `get_file_content`
**Description**: Advanced batch file retrieval with smart truncation, security validation, and rich metadata extraction.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"file_paths": ["README.md", "package.json", "src/index.js"],
"options": {
"max_size": 100000,
"include_metadata": true,
"truncate_large_files": true,
"format": "raw|parsed|summary"
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"README.md": {
"content": "file content",
"size": 1234,
"truncated": false
},
"package.json": {
"content": "{ \"name\": \"example\" }",
"size": 567,
"truncated": false
}
}
}
```
### 4. `analyze_code_structure`
**Description**: Technical code structure analysis with complexity metrics.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"file_paths": ["src/index.js"], // optional
"options": {
"include_functions": true,
"include_classes": true,
"include_imports": true,
"include_complexity": true,
"languages": ["javascript", "typescript"]
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"functions": [
{
"name": "functionName",
"file": "src/index.js",
"line": 10,
"complexity": 5,
"parameters": ["param1", "param2"]
}
],
"classes": [
{
"name": "ClassName",
"file": "src/class.js",
"line": 1,
"methods": ["method1", "method2"]
}
],
"imports": [
{
"module": "react",
"type": "default",
"file": "src/component.js"
}
],
"complexity": {
"cyclomatic": 25,
"cognitive": 30,
"overall": "medium"
}
}
}
```
### 5. `analyze_dependencies`
**Description**: Dependency analysis and security scanning.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"options": {
"include_dev_dependencies": true,
"include_security_scan": true,
"include_version_analysis": true,
"check_outdated": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"dependencies": {
"production": [
{
"name": "react",
"version": "^18.0.0",
"type": "runtime"
}
],
"development": [
{
"name": "jest",
"version": "^29.0.0",
"type": "testing"
}
]
},
"security": {
"vulnerabilities": [
{
"package": "package-name",
"severity": "high",
"description": "Vulnerability description"
}
]
},
"outdated": [
{
"package": "package-name",
"current": "1.0.0",
"latest": "2.0.0"
}
]
}
}
```
### 6. `calculate_metrics`
**Description**: Quantitative code quality metrics and technical debt analysis.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"options": {
"metrics": ["complexity", "maintainability", "duplication", "security"],
"include_file_level": true,
"include_trend_analysis": false
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"overall": {
"complexity": 6.5,
"maintainability": 75,
"duplication": 15,
"security": 85,
"technical_debt": "medium"
},
"file_level": {
"src/index.js": {
"complexity": 8.2,
"maintainability": 70,
"lines": 150
}
},
"recommendations": [
"Reduce complexity in src/index.js",
"Address code duplication in utils/"
]
}
}
```
## Code Transformation Tools
### 7. `transform_code`
**Description**: Syntax modernization and language conversion.
**Parameters**:
```json
{
"code": "var x = 5; function test() { return x + 1; }",
"transformations": [
{
"type": "modernize|framework|performance|security",
"options": { /* transformation-specific options */ }
}
],
"language": "javascript",
"target_language": "typescript", // optional
"options": {
"preserve_comments": true,
"include_instructions": true,
"validate_syntax": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"transformed_code": "const x = 5; const test = () => x + 1;",
"transformations_applied": [
{
"type": "modernize",
"description": "Converted var to const, function to arrow function"
}
],
"syntax_valid": true,
"instructions": "Code has been modernized to use ES6+ features"
}
}
```
### 8. `extract_components`
**Description**: Component extraction with reusability scoring.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"extraction_types": ["components", "functions", "utilities", "hooks", "types"],
"options": {
"min_reusability_score": 60,
"include_dependencies": true,
"include_examples": true,
"framework": "react"
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"components": [
{
"name": "Button",
"file": "src/components/Button.js",
"reusability_score": 85,
"dependencies": ["react"],
"props": ["onClick", "children", "variant"],
"example_usage": "<Button onClick={handleClick}>Click me</Button>"
}
],
"functions": [
{
"name": "formatDate",
"file": "src/utils/date.js",
"reusability_score": 90,
"parameters": ["date", "format"],
"return_type": "string"
}
]
}
}
```
### 9. `adapt_code_structure`
**Description**: Framework migration and architectural restructuring.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"target_structure": {
"framework": "react|vue|angular|express",
"pattern": "mvc|mvvm|clean",
"folder_structure": { /* custom structure */ }
},
"options": {
"preserve_logic": true,
"update_imports": true,
"generate_config": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"migration_plan": {
"steps": [
{
"action": "move",
"from": "src/components/",
"to": "components/",
"reason": "Framework convention"
}
],
"estimated_effort": "medium",
"breaking_changes": ["Import paths", "Config structure"]
},
"file_mappings": {
"src/index.js": "src/main.js",
"src/App.js": "src/App.vue"
},
"config_files": {
"package.json": "{ \"scripts\": { \"dev\": \"vite\" } }",
"vite.config.js": "export default { /* config */ }"
}
}
}
```
### 10. `generate_project_template`
**Description**: Template generation from analysis.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"template_type": "starter|library|microservice|fullstack|component-library",
"options": {
"project_name": "my-new-project",
"framework": "react",
"language": "typescript",
"include_tests": true,
"include_docs": true,
"include_ci": true,
"package_manager": "npm|yarn|pnpm|bun"
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"template": {
"name": "my-new-project",
"structure": {
"src/": "Source code directory",
"tests/": "Test files",
"docs/": "Documentation"
},
"files": {
"package.json": "{ \"name\": \"my-new-project\" }",
"README.md": "# My New Project",
"tsconfig.json": "{ \"compilerOptions\": {} }"
}
},
"setup_instructions": [
"npm install",
"npm run build",
"npm test"
]
}
}
```
## Analysis Tools
### 11. `analyze_architecture`
**Description**: Design patterns, layering, and scalability analysis.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"options": {
"pattern_types": ["mvc", "mvvm", "clean", "hexagonal"],
"include_frameworks": true,
"include_conventions": true,
"confidence_threshold": 0.7
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"patterns": [
{
"type": "mvc",
"confidence": 0.85,
"evidence": ["Controllers found", "Models directory", "View components"],
"implementation": "Well-structured MVC with clear separation"
}
],
"frameworks": [
{
"name": "React",
"version": "18.x",
"usage": "Frontend framework"
}
],
"scalability": {
"score": 75,
"strengths": ["Modular architecture", "Good separation of concerns"],
"concerns": ["Monolithic structure", "Tight coupling in utils"]
}
}
}
```
### 12. `compare_implementations`
**Description**: Multi-repository comparison and benchmarking.
**Parameters**:
```json
{
"implementations": [
{
"name": "Implementation A",
"url": "https://github.com/owner/repo-a",
"focus_areas": ["performance", "security"]
},
{
"name": "Implementation B",
"url": "https://github.com/owner/repo-b"
}
],
"comparison_criteria": ["performance", "maintainability", "security", "complexity"],
"options": {
"include_metrics": true,
"include_recommendations": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"comparison": {
"performance": {
"Implementation A": 85,
"Implementation B": 70,
"winner": "Implementation A"
},
"maintainability": {
"Implementation A": 75,
"Implementation B": 90,
"winner": "Implementation B"
}
},
"recommendations": [
"Implementation A has better performance optimizations",
"Implementation B follows better coding practices"
],
"summary": "Implementation A is better for performance-critical applications"
}
}
```
### 13. `validate_code_quality`
**Description**: Rule-based validation and standards compliance.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"validation_types": ["security", "performance", "best-practices", "accessibility"],
"options": {
"severity_level": "low|medium|high|critical",
"include_fixes": true,
"framework_specific": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"validation_results": {
"security": {
"score": 85,
"issues": [
{
"type": "XSS vulnerability",
"severity": "high",
"file": "src/component.js",
"line": 42,
"fix": "Use proper sanitization"
}
]
},
"performance": {
"score": 70,
"issues": [
{
"type": "Large bundle size",
"severity": "medium",
"suggestion": "Implement code splitting"
}
]
}
},
"overall_score": 78,
"certification": "Good"
}
}
```
## Utility Tools
### 14. `batch_process`
**Description**: Parallel execution of multiple operations.
**Parameters**:
```json
{
"operations": [
{
"id": "op1",
"tool": "health_check",
"params": {},
"priority": 5
},
{
"id": "op2",
"tool": "fetch_repository_data",
"params": {
"url": "https://github.com/owner/repo"
},
"priority": 8
}
],
"options": {
"max_concurrent": 3,
"fail_fast": false,
"include_progress": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"operations": [
{
"type": "health_check",
"id": "op1"
}
],
"results": [
{
"id": "op1",
"success": true,
"data": { /* operation result */ },
"processingTime": 1200
}
],
"totalTime": 5000,
"successCount": 2,
"failureCount": 0
}
}
```
### 15. `health_check`
**Description**: Server health, API limits, and system monitoring.
**Parameters**:
```json
{
"checks": ["api-limits", "cache-status", "system-health", "dependencies"],
"options": {
"include_metrics": true,
"include_diagnostics": false
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"status": "healthy",
"timestamp": "2024-01-17T23:41:31.079Z",
"checks": {
"api-limits": {
"github": {
"remaining": 4950,
"limit": 5000,
"reset": "2024-01-17T24:00:00Z"
},
"openrouter": {
"status": "healthy"
}
},
"system-health": {
"status": "healthy",
"memory": {
"used": 128,
"total": 512
},
"uptime": 3600
}
},
"metrics": {
"uptime": 3600,
"memory": {
"rss": 50331648,
"heapTotal": 20971520,
"heapUsed": 15728640
},
"version": "1.0.0"
}
}
}
```
## AI-Enhanced Tools
### 16. `ai_code_review`
**Description**: AI-powered code review with intelligent insights.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"file_paths": ["src/index.js"], // optional
"review_focus": ["security", "performance", "maintainability", "best-practices"],
"options": {
"ai_model": "auto|anthropic/claude-3.5-sonnet|openai/gpt-4o",
"severity_threshold": "low|medium|high",
"include_examples": true,
"language_specific": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"repository": {
"name": "repo-name",
"description": "Repository description",
"language": "JavaScript",
"owner": "owner-name"
},
"review": {
"files_reviewed": ["src/index.js"],
"focus_areas": ["security", "performance"],
"ai_model_used": "anthropic/claude-3.5-sonnet",
"ai_model_requested": "auto",
"analysis": "Comprehensive AI-generated review content...",
"severity_threshold": "medium",
"timestamp": "2024-01-17T23:41:31.079Z",
"model_warning": null
},
"recommendations": {
"priority_fixes": [
"Fix XSS vulnerability in line 42",
"Optimize database queries in user service"
],
"suggestions": [
"Consider implementing caching",
"Add input validation"
],
"best_practices": [
"Use TypeScript for better type safety",
"Add comprehensive tests"
]
}
}
}
```
### 17. `ai_explain_code`
**Description**: AI-generated explanations and documentation.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"file_paths": ["src/index.js"], // optional
"explanation_type": "overview|detailed|architecture|tutorial|integration",
"options": {
"ai_model": "auto|anthropic/claude-3.5-sonnet|openai/gpt-4o",
"target_audience": "beginner|intermediate|advanced",
"include_examples": true,
"include_diagrams": true,
"focus_on_patterns": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"repository": {
"name": "repo-name",
"description": "Repository description",
"language": "JavaScript",
"owner": "owner-name"
},
"explanation": {
"type": "overview",
"files_analyzed": ["src/index.js"],
"ai_model_used": "openai/gpt-4o",
"ai_model_requested": "auto",
"target_audience": "intermediate",
"content": "Detailed AI-generated explanation...",
"timestamp": "2024-01-17T23:41:31.079Z",
"model_warning": null
},
"metadata": {
"file_count": 5,
"total_lines": 1200
}
}
}
```
### 18. `ai_refactor_suggestions`
**Description**: AI-powered refactoring strategies and recommendations.
**Parameters**:
```json
{
"url": "https://github.com/owner/repo",
"file_paths": ["src/index.js"], // optional
"refactoring_goals": ["modernize", "performance", "maintainability", "security"],
"target_framework": "react|vue|angular", // optional
"options": {
"ai_model": "auto|anthropic/claude-3.5-sonnet|openai/gpt-4o",
"include_code_examples": true,
"priority_level": "low|medium|high",
"estimate_effort": true
}
}
```
**Response**:
```json
{
"success": true,
"data": {
"repository": {
"name": "repo-name",
"description": "Repository description",
"language": "JavaScript",
"owner": "owner-name"
},
"refactoring": {
"goals": ["modernize", "performance"],
"target_framework": "react",
"files_analyzed": ["src/index.js"],
"ai_model_used": "anthropic/claude-3.5-sonnet",
"ai_model_requested": "auto",
"suggestions": "Detailed AI-generated refactoring plan...",
"priority_level": "medium",
"timestamp": "2024-01-17T23:41:31.079Z",
"model_warning": null
},
"metadata": {
"file_count": 5,
"total_lines": 1200,
"estimated_effort": "2-3 days for experienced developer"
}
}
}
```
## Error Handling
### Error Codes
- `INVALID_URL`: Invalid GitHub repository URL
- `REPOSITORY_NOT_FOUND`: Repository does not exist or is private
- `RATE_LIMIT_EXCEEDED`: API rate limit exceeded
- `PROCESSING_ERROR`: General processing error
- `VALIDATION_ERROR`: Input validation failed
- `OPENROUTER_ERROR`: OpenRouter API error
- `NETWORK_ERROR`: Network connectivity issue
### Error Response Format
```json
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "GitHub API rate limit exceeded",
"details": {
"limit": 5000,
"remaining": 0,
"reset": "2024-01-17T24:00:00Z"
}
},
"metadata": {
"processing_time": 1234
}
}
```
## Rate Limiting
### GitHub API
- **Unauthenticated**: 60 requests/hour
- **With token**: 5,000 requests/hour
- **GraphQL**: 5,000 points/hour
### OpenRouter API
- Varies by model and subscription plan
- Check OpenRouter documentation for specific limits
### Best Practices
- Use GitHub token for better rate limits
- Implement exponential backoff
- Monitor rate limits with `health_check`
- Cache responses when possible
## Model Selection Guide
### Auto Selection Logic
- **Code Review**: `anthropic/claude-3.5-sonnet`
- **Explanation**: `openai/gpt-4o`
- **Refactoring**: `anthropic/claude-3.5-sonnet`
- **Batch Jobs**: `openai/gpt-4o-mini`
### Model Characteristics
- **Speed**: `fastest` → `slowest`
- **Cost**: `low` → `highest`
- **Quality**: `good` → `highest`
- **Recommended**: Production-ready models
### Model Transparency
All AI responses include:
- `ai_model_used`: Actual model used
- `ai_model_requested`: Requested model
- `model_warning`: Performance/cost warnings
This comprehensive API reference covers all 18 tools with detailed parameters, responses, and usage examples.