Skip to content

Contributing

Jump to bottom
j0KZ edited this page Oct 8, 2025 · 2 revisions

Contributing Guide

Thank you for your interest in contributing to MCP Agent Toolkit! This guide will help you get started.

Please note that this project follows our Code of Conduct. By participating, you are expected to uphold this code.

🤝 Ways to Contribute

  • 🐛 Report bugs
  • 💡 Suggest new features
  • 📝 Improve documentation
  • 🔧 Submit bug fixes
  • ✨ Add new features
  • 🧪 Write tests
  • 🎨 Improve code quality

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: v18.x or higher
  • npm: v8.x or higher
  • Git: Latest version

Check your versions:

node --version  # Should be v18 or higher
npm --version   # Should be v8 or higher
git --version

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/mcp-agents.git
cd mcp-agents
npm install

2. Build

npm run build

3. Run Tests

npm test

4. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

📋 Development Workflow

Project Structure

mcp-agents/
├── packages/
│   ├── smart-reviewer/      # Code review tool
│   ├── test-generator/      # Test generation
│   ├── architecture-analyzer/  # Architecture analysis
│   ├── security-scanner/    # Security scanning
│   ├── refactor-assistant/  # Code refactoring
│   ├── api-designer/        # API design
│   ├── db-schema/           # Database schema
│   ├── doc-generator/       # Documentation
│   ├── orchestrator-mcp/    # Workflow orchestration
│   ├── config-wizard/       # Installation wizard
│   └── shared/              # Shared utilities (private)
├── docs/                    # Documentation
├── scripts/                 # Build and utility scripts
└── tests/                   # Integration tests

Working on a Package

# Build specific package
npm run build -w packages/smart-reviewer

# Run tests for specific package
npm test -w packages/smart-reviewer

# Watch mode for development
npm run dev -w packages/smart-reviewer

Code Style

We use:

  • TypeScript for type safety
  • ES Modules (import/export)
  • Prettier for formatting
  • ESLint for linting

Run formatters before committing:

npm run format        # Format all files
npm run lint         # Check for lint errors
npm run lint:fix     # Auto-fix lint issues

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in CI mode (no watch)
npm run test:ci

# Run tests for specific package
npm test -w packages/smart-reviewer

Testing Requirements:

  • All new features must have tests
  • Aim for >70% code coverage
  • Test edge cases and error handling
  • Use descriptive test names

Writing Tests

We use Vitest. Example test structure:

import { describe, it, expect } from 'vitest';
import { MyClass } from './my-class.js';

describe('MyClass', () => {
  describe('myMethod', () => {
    it('should handle valid input', () => {
      const instance = new MyClass();
      const result = instance.myMethod('test');
      expect(result).toBe('expected output');
    });

    it('should throw error for invalid input', () => {
      const instance = new MyClass();
      expect(() => instance.myMethod(null)).toThrow();
    });

    it('should handle edge cases', () => {
      const instance = new MyClass();
      expect(instance.myMethod('')).toBe('');
      expect(instance.myMethod('a'.repeat(1000))).toBeDefined();
    });
  });
});

📐 Architecture Patterns

Modular Architecture

Follow the established refactoring pattern:

  1. Extract Constants → constants/ directory

    • Magic numbers, thresholds, patterns
    • Single source of truth

  2. Extract Helpers → helpers/ directory

    • Complex calculations (>30 lines)
    • Reusable business logic

  3. Extract Utilities → utils/ directory

    • Cross-cutting concerns
    • Shared code across modules

Example Structure:

packages/my-tool/src/
├── mcp-server.ts          # MCP protocol orchestration
├── main-class.ts          # Main logic (delegates to modules)
├── constants/
│   ├── thresholds.ts
│   └── patterns.ts
├── helpers/
│   ├── calculator.ts
│   └── validator.ts
└── utils.ts               # Shared utilities

Shared Package Integration

Import from @j0kz/shared for common functionality:

import {
  FileSystemManager,
  AnalysisCache,
  PerformanceMonitor,
  validatePath
} from '@j0kz/shared';

// Use shared utilities
const fs = new FileSystemManager();
const cache = new AnalysisCache<AnalysisResult>();
const perf = new PerformanceMonitor();

// Validate paths to prevent traversal attacks
validatePath(filePath);

MCP Server Pattern

All tools follow this structure:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  ListToolsRequestSchema,
  CallToolRequestSchema
} from '@modelcontextprotocol/sdk/types.js';

const server = new Server({
  name: 'my-tool',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

// Register tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'my_tool',
      description: 'Description of what it does',
      inputSchema: {
        type: 'object',
        properties: {
          param: { type: 'string', description: 'Parameter description' }
        },
        required: ['param']
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'my_tool') {
    const result = await doWork(args);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

🔀 Pull Request Process

1. Make Your Changes

  • Follow the code style guide
  • Add/update tests
  • Update documentation
  • Keep commits atomic and focused

2. Commit Messages

We use Conventional Commits:

# Feature
git commit -m "feat: add auto-fix for unused variables"

# Bug fix
git commit -m "fix: handle null values in analyzer"

# Documentation
git commit -m "docs: update API reference for security-scanner"

# Refactor
git commit -m "refactor: extract validation logic to helpers"

# Test
git commit -m "test: add edge cases for circular dependency detection"

# Chore
git commit -m "chore: update dependencies"

Format:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Formatting, missing semi-colons, etc.
  • refactor: Code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests
  • chore: Maintaining, dependencies, etc.

3. Push and Create PR

git push origin feature/your-feature-name

Then create a pull request on GitHub with:

  • Clear title describing the change
  • Detailed description of what changed and why
  • Reference any related issues (#123)
  • Screenshots/examples if applicable

4. Code Review

  • Respond to feedback promptly
  • Make requested changes
  • Keep the PR focused and small
  • Don't force-push after review starts (makes reviewing harder)

📝 Documentation

Updating Documentation

If your change affects user-facing functionality:

  1. Update README - Main repository README.md
  2. Update Package README - packages/YOUR_PACKAGE/README.md
  3. Update Wiki - Create/update wiki pages
  4. Update CHANGELOG - Add entry to CHANGELOG.md
  5. Update API Docs - JSDoc comments in code

Writing Good Documentation

  • Use clear, concise language
  • Include code examples
  • Explain the "why", not just the "what"
  • Add before/after examples for changes
  • Link to related documentation

🐛 Reporting Bugs

Before Reporting

  1. Check existing issues
  2. Try the latest version
  3. Read the troubleshooting guide

Bug Report Template

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Run command '...'
2. With input '...'
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- OS: [e.g., Windows 11]
- Node version: [e.g., 20.10.0]
- Package version: [e.g., 1.0.35]
- Editor: [e.g., Claude Code, Cursor]

**Additional context**
Any other relevant information.

💡 Feature Requests

Before Requesting

  1. Check if it already exists
  2. Search closed issues
  3. Consider if it fits the project scope

Feature Request Template

**Problem Statement**
What problem does this feature solve?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
What other solutions did you consider?

**Additional Context**
Any other relevant information.

🏆 Recognition

Contributors will be:

  • Listed in CHANGELOG.md
  • Mentioned in release notes
  • Added to GitHub contributors list
  • Credited in relevant documentation

📞 Getting Help

  • GitHub Discussions: Ask questions
  • GitHub Issues: Report bugs or request features
  • Wiki: Read documentation
  • Discord: Join our community (coming soon)

📜 License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing! 🎉

Clone this wiki locally