CodeCompass MCP

# Contributing to CodeCompass MCP Thank you for your interest in contributing to CodeCompass MCP! This document provides guidelines and information for contributors. ## 🤝 How to Contribute ### Reporting Issues 1. **Search existing issues** to avoid duplicates 2. **Use the issue template** when creating new issues 3. **Provide detailed information**: - Steps to reproduce - Expected vs actual behavior - Environment details (Node.js version, OS, etc.) - Error messages and logs ### Suggesting Features 1. **Check existing feature requests** in issues 2. **Describe the use case** and problem being solved 3. **Provide examples** of how the feature would be used 4. **Consider implementation complexity** and maintenance burden ### Pull Requests 1. **Fork the repository** and create a feature branch 2. **Follow the development setup** instructions below 3. **Make your changes** with appropriate tests 4. **Update documentation** if needed 5. **Submit a pull request** with a clear description ## 🛠️ Development Setup ### Prerequisites - Node.js 18+ - npm or yarn - Git ### Installation ```bash # Clone your fork git clone https://github.com/yourusername/codecompass-mcp.git cd codecompass-mcp # Install dependencies npm install # Build the project npm run build # Run tests npm test ``` ### Development Workflow ```bash # Start development server npm run dev # Start development server with auto-restart npm run dev:watch # Run TypeScript type checking npm run typecheck # Run type checking in watch mode npm run typecheck:watch # Build for development (faster) npm run build:dev # Build with file watching npm run build:watch # Build for production npm run build # Run tests in watch mode npm run test:watch # Run linting npm run lint # Run linting with auto-fix npm run lint:fix # Format code npm run format # Check code formatting npm run format:check ``` ## 📁 Project Structure ``` codecompass-mcp/ ├── src/ │ ├── index.ts # Main server entry point │ ├── services/ # Core services │ │ ├── github.ts # GitHub API integration │ │ ├── openai.ts # OpenRouter/AI integration │ │ └── refactor.ts # Code transformation │ ├── tools/ # MCP tool definitions │ │ └── consolidated.ts # All 18 tools │ ├── types/ # TypeScript type definitions │ │ ├── index.ts # Core types │ │ └── responses.ts # Response types │ └── utils/ # Utility functions ├── tests/ # Test suites │ ├── integration/ # Integration tests │ └── unit/ # Unit tests ├── docs/ # Documentation └── examples/ # Usage examples ``` ## 🔧 Adding New Tools ### Tool Implementation 1. **Add tool definition** in `src/tools/consolidated.ts`: ```typescript { name: 'new_tool', description: 'Description of what the tool does', inputSchema: { type: 'object', properties: { // Define input parameters }, required: ['required_param'] } } ``` 2. **Add tool handler** in `src/index.ts`: ```typescript case 'new_tool': return await handleNewTool(args); ``` 3. **Implement handler function**: ```typescript async function handleNewTool(args: any) { try { // Implementation logic const result = await processNewTool(args); const response = createResponse(result); return formatToolResponse(response); } catch (error) { const response = createResponse(null, error); return formatToolResponse(response); } } ``` ### Tool Guidelines - **Follow naming convention**: Use snake_case for tool names - **Provide clear descriptions**: Help users understand the tool's purpose - **Include comprehensive schemas**: Define all parameters and options - **Handle errors gracefully**: Use standardized error responses - **Add tests**: Include unit and integration tests - **Update documentation**: Add to API reference ## 🧪 Testing ### Test Structure ```bash tests/ ├── unit/ # Unit tests │ ├── services/ # Service tests │ └── tools/ # Tool tests └── integration/ # Integration tests ├── test-all-tools.js # All tools test └── test-ai-tools.js # AI tools test ``` ### Writing Tests ```typescript // Unit test example describe('GitHub Service', () => { it('should fetch repository data', async () => { const result = await githubService.getRepositoryInfo('https://github.com/test/repo'); expect(result).toBeDefined(); expect(result.name).toBe('repo'); }); }); // Integration test example describe('fetch_repository_data tool', () => { it('should return repository analysis', async () => { const response = await callTool('fetch_repository_data', { url: 'https://github.com/test/repo' }); expect(response.success).toBe(true); expect(response.data).toBeDefined(); }); }); ``` ### Test Commands ```bash # Run all tests npm test # Run unit tests only npm run test:unit # Run integration tests only npm run test:integration # Run tests with coverage npm run test:coverage # Run tests in watch mode npm run test:watch ``` ## 📝 Code Style ### TypeScript Guidelines - Use **strict TypeScript** configuration - Define **interfaces** for all data structures - Use **type guards** for runtime validation - Avoid **`any`** type unless absolutely necessary ### TypeScript Configuration The project uses two TypeScript configurations: - **`tsconfig.json`** - Production build with strict type checking - **`tsconfig.dev.json`** - Development build with optimizations #### Key Features: - **Incremental builds** for faster compilation - **Source maps** for debugging - **Path mapping** for clean imports (`@/services/*`, `@/types/*`) - **Strict type checking** for code quality - **Node.js compatibility** with ES modules - **Declaration files** for TypeScript consumers ### Formatting - Use **Prettier** for code formatting - Follow **ESLint** rules for code quality - Use **2 spaces** for indentation - Max line length: **100 characters** ### Naming Conventions - **Variables**: `camelCase` - **Functions**: `camelCase` - **Classes**: `PascalCase` - **Constants**: `UPPER_SNAKE_CASE` - **Files**: `kebab-case.ts` - **MCP Tools**: `snake_case` ## 📚 Documentation ### Required Documentation - **API Reference**: Update `docs/API.md` for new tools - **README**: Update main README for significant changes - **Code Comments**: Add JSDoc comments for public APIs - **Examples**: Provide usage examples for new features ### Documentation Style ```typescript /** * Analyzes repository structure and complexity * @param url - GitHub repository URL * @param options - Analysis options * @returns Promise<AnalysisResult> * @throws {Error} When repository is not accessible */ async function analyzeRepository(url: string, options: AnalysisOptions): Promise<AnalysisResult> { // Implementation } ``` ## 🔄 CI/CD and Automation ### GitHub Actions The project uses GitHub Actions for: - **Automated testing** on pull requests - **Code quality checks** (linting, formatting) - **Build verification** on multiple Node.js versions - **Security scanning** with CodeQL - **Automated releases** with semantic versioning ### Pre-commit Hooks ```bash # Install pre-commit hooks npm run prepare # Hooks run automatically on commit: # - Code formatting # - Linting # - Type checking # - Test execution ``` ## 🚀 Release Process ### Version Management We use **semantic versioning** (semver): - **Major** (1.0.0): Breaking changes - **Minor** (1.1.0): New features, backward compatible - **Patch** (1.0.1): Bug fixes, backward compatible ### Release Steps 1. **Create release branch**: `git checkout -b release/v1.1.0` 2. **Update version**: `npm version minor` 3. **Update changelog**: Document changes in `CHANGELOG.md` 4. **Test thoroughly**: Run all tests and manual verification 5. **Submit PR**: Create pull request for release 6. **Merge and tag**: After approval, merge and create Git tag 7. **Publish**: Automated GitHub Actions handles npm publishing ## 🛡️ Security ### Security Guidelines - **No hardcoded secrets**: Use environment variables - **Validate all inputs**: Use Zod schemas for validation - **Handle errors safely**: Don't expose sensitive information - **Keep dependencies updated**: Regular security audits ### Reporting Security Issues Please report security vulnerabilities to: - **Email**: security@myronlabs.com - **GitHub**: Use private security advisories - **Response time**: We aim to respond within 24 hours ## 📊 Performance ### Performance Guidelines - **Cache API responses** when possible - **Implement rate limiting** for external APIs - **Use streaming** for large data processing - **Monitor memory usage** in long-running operations - **Optimize database queries** if adding persistence ### Benchmarking ```bash # Run performance tests npm run benchmark # Profile memory usage npm run profile ``` ## 🤖 AI Integration ### OpenRouter Integration - **Model selection**: Use intelligent auto-selection - **Error handling**: Graceful fallbacks for API failures - **Cost optimization**: Prefer cost-effective models for batch operations - **Transparency**: Always log model usage and costs ### Adding New AI Features 1. **Update model characteristics** in `src/services/openai.ts` 2. **Add model selection logic** for new use cases 3. **Implement proper error handling** for AI failures 4. **Add cost warnings** for expensive operations 5. **Include model transparency** in responses ## 📞 Getting Help ### Community Resources - **GitHub Issues**: Bug reports and feature requests - **GitHub Discussions**: General questions and ideas - **Documentation**: Comprehensive guides and API reference - **Examples**: Working code examples and patterns ### Maintainer Contact - **GitHub**: @alchemist6 - **Email**: support@myronlabs.com - **Response time**: Usually within 24-48 hours ## 📜 Code of Conduct ### Our Standards - **Be respectful**: Treat all contributors with respect - **Be inclusive**: Welcome people of all backgrounds - **Be constructive**: Provide helpful feedback - **Be collaborative**: Work together toward common goals ### Enforcement Violations of the code of conduct should be reported to the maintainers. All complaints will be reviewed and investigated promptly and fairly. --- **Thank you for contributing to CodeCompass MCP!** 🙏 Your contributions help make code analysis and AI-powered development tools accessible to everyone. Together, we're building something amazing! 🚀