CONTRIBUTING.md•5.65 kB
# Contributing to MCP ADR Analysis Server
Thank you for your interest in contributing! This document provides comprehensive guidelines tailored to our TypeScript/Node.js MCP server architecture.
## Prerequisites
- Node.js ≥20.0.0
- npm ≥9.0.0
- Git with pre-commit hooks enabled
- Editor with EditorConfig, ESLint, and Prettier support
## Development Setup
```bash
# Clone and setup
git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
cd mcp-adr-analysis-server
npm install
# Verify setup works
npm run typecheck
npm run lint
npm run test
# Start development
npm run dev
```
## Code Standards
### TypeScript Guidelines
- Use strict TypeScript configuration (already configured with `strict: true`)
- Prefer explicit types over `any` (ESLint will warn about `any` usage)
- Document complex types and interfaces with JSDoc comments
- Follow existing import patterns (ESM modules with `.js` extensions in imports)
- Use the established error types (`McpAdrError`) for consistent error handling
### Formatting and Linting
Our automated toolchain ensures consistency:
```bash
# Before committing, run:
npm run lint:fix # Auto-fix ESLint issues
npm run format # Format with Prettier
npm run typecheck # Verify TypeScript compilation
# Or run all checks together:
npm run prepublishOnly
```
**Pre-commit hooks automatically:**
- Format code with Prettier
- Run ESLint with auto-fix
- Validate TypeScript compilation
### Testing Requirements
- Maintain ≥85% coverage threshold (enforced by Jest)
- Write unit tests for new utilities in `src/utils/`
- Add integration tests for new tools in `src/tools/`
- Use descriptive test names following the pattern: `should [expected behavior] when [condition]`
- Test files should mirror source structure: `src/utils/file.ts` → `tests/utils/file.test.ts`
### File Structure and Architecture
```
src/
├── tools/ # MCP tools (main functionality)
├── utils/ # Reusable utilities
├── types/ # TypeScript type definitions
├── prompts/ # MCP prompts
├── templates/ # Code generation templates
└── config/ # Configuration management
```
Follow these patterns when adding new code:
- **Tools**: Implement MCP protocol handlers in `src/tools/`
- **Utilities**: Place reusable logic in `src/utils/` and export through `index.ts`
- **Types**: Define interfaces in `src/types/` with proper JSDoc documentation
- **Tests**: Mirror source structure in `tests/` directory
## Commit Standards
We use conventional commits with automated validation:
- Format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
- Examples:
- `feat(tools): add new ADR analysis tool`
- `fix(utils): resolve caching issue in file operations`
- `docs(contributing): update setup instructions`
## Architecture Patterns
### Tool Development
When creating new MCP tools in `src/tools/`:
1. **Error Handling**: Use `McpAdrError` for consistent error reporting
2. **Caching**: Leverage the existing cache system (`src/utils/cache.ts`)
3. **Validation**: Use Zod schemas for input validation
4. **Logging**: Use the enhanced logging utility (`src/utils/enhanced-logging.ts`)
Example tool structure:
```typescript
import { McpAdrError } from '../types/index.js';
import { logger } from '../utils/enhanced-logging.js';
export async function myNewTool(args: MyToolArgs): Promise<MyToolResult> {
try {
logger.info('Starting tool operation', { args });
// Implementation
return result;
} catch (error) {
throw McpAdrError.fromError(error, 'MY_TOOL_ERROR');
}
}
```
### Utility Functions
For reusable logic in `src/utils/`:
1. **Export Pattern**: Always export through `src/utils/index.ts`
2. **Documentation**: Include comprehensive JSDoc comments
3. **Testing**: Write corresponding unit tests
4. **Type Safety**: Use strict TypeScript with proper return types
## Pull Request Process
1. **Create Feature Branch**: `git checkout -b feature/description`
2. **Implement Changes**: Follow our coding standards above
3. **Run Full Test Suite**: `npm test` (includes coverage verification)
4. **Update Documentation**: Add/update relevant docs if needed
5. **Submit PR**: Use our PR template with clear description
6. **CI Verification**: Ensure all automated checks pass
### PR Review Guidelines
Reviewers focus on:
- **Functionality**: Does it work as intended?
- **Architecture**: Does it follow established patterns?
- **Testing**: Is coverage maintained and are edge cases covered?
- **Security**: Any potential security implications?
- **MCP Compliance**: Does it properly implement MCP protocol standards?
_Note: Style and formatting are automated, so reviews focus on substance over syntax._
## Quality Gates
All contributions must pass:
- ✅ TypeScript compilation (`npm run typecheck`)
- ✅ ESLint rules (`npm run lint`)
- ✅ Test suite with ≥85% coverage (`npm run test:coverage`)
- ✅ Build process (`npm run build`)
- ✅ Pre-commit hooks execution
## Getting Help
- **Architecture Questions**: Review existing ADRs in `././adrs/`
- **Tool Development**: Examine existing tools in `src/tools/`
- **Testing Patterns**: Check `tests/` for examples
- **MCP Protocol**: Refer to [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/sdk)
## Code of Conduct
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
---
_This guide is maintained to reflect our current toolchain and practices. When in doubt, follow the automated tooling—it embodies our agreed-upon standards._