devflow-mcp

A production-ready Model Context Protocol server that gives AI assistants deep GitHub developer tooling — PR analysis, code review, changelog generation, dependency auditing, commit summarization, and refactoring suggestions.

Features

• 6 MCP tools covering the full developer workflow
• Heuristic analysis — no external LLM calls, fast and deterministic
• OSV.dev integration for real vulnerability data (npm and PyPI)
• LRU cache with TTL to minimize GitHub API calls
• Token-bucket rate limiter to stay within GitHub's limits
• Zero any — strict TypeScript throughout
• ≥80% test coverage with MSW-mocked HTTP

Requirements

• Node.js 18+
• A GitHub Personal Access Token with repo scope

Installation

npm install -g devflow-mcp

Or run directly with npx:

npx devflow-mcp

Or clone and build:

git clone https://github.com/yourorg/devflow-mcp
cd devflow-mcp
npm install
npm run build

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["devflow-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Tools

analyze_pr

Analyzes a GitHub pull request for risk, security findings, and merge readiness.

Parameters:

Returns: risk_score (0-100), risk_level, findings[], change_summary, merge_recommendation

review_code

Reviews a code snippet for quality, security issues, and improvement opportunities.

Parameters:

Returns: overall_score (1-10), issues[] with severity + fix suggestions, positive_observations[], refactor_priority

generate_changelog

Generates a changelog between two Git refs from commit history.

Parameters:

Returns: changelog string, commit_count, stats per category, breaking_changes[]

audit_dependencies

Audits project dependencies against the OSV vulnerability database.

Parameters:

Returns: vulnerabilities[] with CVE IDs, fix versions, and fix commands; audit_passed, stats per severity level, osv_query_timestamp

summarize_commits

Summarizes recent commits on a branch into a human-readable digest.

Parameters:

Returns: summary string, categories (features/fixes/docs/refactors/chores/other), authors[], commit_count

suggest_refactor

Analyzes code for refactoring opportunities ranked by impact-to-effort ratio.

Parameters:

Returns: suggestions[] with rationale and effort estimates, priority_order[], original_complexity_score

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type-check and build
npm run build

# Lint
npm run lint

# Format
npm run format

# Start the server (after build)
npm start

Project Structure

src/
  index.ts              # Entry point
  server.ts             # MCP server registration
  tools/                # Tool handlers (one per tool)
  github/               # GitHub API clients
  lib/                  # Shared utilities
    cache.ts            # LRU cache with TTL
    rate-limiter.ts     # Token-bucket rate limiter
    commit-parser.ts    # Conventional commit parser
    diff-parser.ts      # Git diff parser
    risk-scorer.ts      # PR risk scoring heuristics
    errors.ts           # Typed MCP errors
  providers/
    osv.ts              # OSV.dev vulnerability API
tests/
  integration/          # Full MCP server tests via InMemoryTransport
  tools/                # Unit tests per tool handler
  lib/                  # Unit tests for utilities

Test Strategy

• Unit tests: each tool handler and library mocked with vi.mock
• Integration tests: full MCP client↔server round-trip via InMemoryTransport, HTTP intercepted with MSW
• HTTP mocking: MSW v2 (msw/node) — no real network calls in tests
• Coverage: ≥80% branches required (npm run test:coverage)

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new behavior
4. Ensure npm run build && npm run test:coverage && npm run lint all pass
5. Open a pull request

License

MIT