Skip to content

MCP_INTEGRATION.md

Latest commit

 

History

History
377 lines (302 loc) · 10 KB

MCP_INTEGRATION.md

File metadata and controls

377 lines (302 loc) · 10 KB
Raw

MCP Integration Guide

This document describes the recommended Model Context Protocol (MCP) servers for enhancing the Agentic Development Framework.

Overview

MCPs extend Claude's capabilities by providing specialized tools and data sources. This framework is designed to work with several MCPs that significantly enhance autonomous development workflows.

MCP Tiers

Tier 1: Critical Enhancement (Implement First)

These MCPs provide transformative capabilities for the framework:

1. GitHub MCP 🔥

Package: @modelcontextprotocol/server-github Impact: Critical for PR/issue workflows

What it provides:

  • github_create_or_update_file - Programmatic file updates
  • github_create_issue - Automated issue creation
  • github_create_pull_request - Enhanced PR creation
  • github_get_file_contents - Direct file access
  • github_list_commits - Commit history access
  • github_search_code - Advanced code search
  • github_search_issues - Issue/PR search

Framework Skills Enhanced:

  • /create-pr - More robust PR creation with better error handling
  • /review-pr - Fetch PR diffs and comments programmatically
  • /bugfix - Search issues for similar bugs before implementing
  • /explore - Search code across repositories

Installation:

npm install -g @modelcontextprotocol/server-github

Configuration (in Claude Code settings):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

Usage in Skills: When GitHub MCP is available, prefer its tools over gh CLI for:

  • Fetching PR details and diffs
  • Creating/updating issues programmatically
  • Searching code and issues
  • File operations in PRs

2. Memory MCP 🔥

Package: @modelcontextprotocol/server-memory Impact: Game-changing for multi-session development

What it provides:

  • create_entities - Store facts, patterns, conventions
  • create_relations - Link related concepts
  • search_nodes - Query stored knowledge
  • open_nodes - Retrieve detailed information
  • add_observations - Record insights

Framework Enhancements:

  • Cross-session ADR awareness - Remember established patterns
  • Project conventions - Store and recall user preferences
  • Historical context - Remember why decisions were made
  • Pattern recognition - Identify when similar code patterns recur
  • User preferences - Remember commit message style, testing preferences

Installation:

npm install -g @modelcontextprotocol/server-memory

Configuration:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

Usage Patterns:

// Store ADR summary when created
create_entities({
  entities: [{
    name: "ADR-017: Feature-Specific Custom Hooks",
    entityType: "architectural_decision",
    observations: [
      "Custom hooks should be placed in feature directories",
      "Colocation reduces import complexity",
      "Established 2026-01-23"
    ]
  }]
})

// Recall patterns before implementing similar features
search_nodes({
  query: "custom hooks architecture pattern"
})

Framework Integration Points:

  • /adr skill - Store ADR summaries in memory
  • /heavy-task - Recall similar patterns before starting
  • /medium-task - Remember component patterns
  • /explore - Store findings for future reference
  • Orchestrator Agent - Leverage historical decision context

Tier 2: Important Improvements (Implement Second)

3. Sequential Thinking MCP 💎

Package: @modelcontextprotocol/server-sequential-thinking Impact: Enhanced reasoning and planning

What it provides:

  • Structured thinking process
  • Step-by-step reasoning
  • Decision tree exploration
  • Complex problem decomposition

Framework Enhancements:

  • Orchestrator Agent - Better task decomposition
  • Bugfix investigations - Systematic root cause analysis
  • Architecture reviews - Trade-off analysis
  • Planning phase - Complex feature breakdown

Installation:

npm install -g @modelcontextprotocol/server-sequential-thinking

Configuration:

{
  "mcpServers": {
    "sequentialthinking": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking"
      ]
    }
  }
}

Usage in Skills:

  • /heavy-task - Planning complex features with multiple domains
  • /bugfix - Root cause analysis with systematic elimination
  • /refactor - Analyzing multiple refactoring approaches
  • Orchestrator planning - Breaking down complex tasks

4. Brave Search MCP 📚

Package: @modelcontextprotocol/server-brave-search Impact: Better research and documentation discovery

What it provides:

  • brave_web_search - Privacy-respecting web search
  • brave_local_search - Location-aware results
  • Developer-focused results

Framework Enhancements:

  • /research skill - Better external information gathering
  • Library documentation discovery
  • API documentation search
  • Best practices research
  • Technology comparison research

Installation:

npm install -g @modelcontextprotocol/server-brave-search

Configuration:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Usage in Skills:

  • /research - Prefer Brave Search over WebSearch for developer topics
  • Technology evaluation
  • Library comparison research
  • API documentation lookup

Implementation Strategy

Phase 1: Core MCPs (Week 1)

  1. Install GitHub MCP
  2. Install Memory MCP
  3. Update /create-pr and /review-pr to use GitHub MCP tools
  4. Integrate memory persistence in ADR creation workflow

Phase 2: Enhanced Intelligence (Week 2)

  1. Install Sequential Thinking MCP
  2. Install Brave Search MCP
  3. Update Orchestrator Agent to leverage sequential thinking
  4. Update /research skill to use Brave Search

Phase 3: Optimization (Ongoing)

  1. Identify additional MCP usage opportunities
  2. Fine-tune memory storage patterns
  3. Optimize MCP tool selection logic
  4. Document MCP-specific patterns

Skill Updates for MCP Usage

Updated Skills

/create-pr

With GitHub MCP:

  • Use github_create_pull_request for more reliable PR creation
  • Better error handling and validation
  • Automatic branch detection
  • Link issues automatically

/review-pr

With GitHub MCP:

  • Use github_get_file_contents to fetch PR files directly
  • Use GitHub API for more accurate diff retrieval
  • Check PR CI status programmatically
  • Fetch existing review comments

/adr

With Memory MCP:

  • Store ADR summary in memory after creation
  • Tag with decision type and domains affected
  • Link related ADRs automatically

/heavy-task & Orchestrator

With Memory MCP:

  • Recall similar task patterns before starting
  • Remember user preferences for testing, commits, etc.
  • Store successful orchestration patterns

With Sequential Thinking MCP:

  • Enhanced task decomposition
  • Better parallel vs sequential decision-making
  • Improved trade-off analysis

/bugfix

With GitHub MCP:

  • Search for similar issues before implementing fix
  • Link fix to related issues automatically

With Sequential Thinking MCP:

  • Systematic root cause elimination
  • Evidence-based debugging

/research

With Brave Search MCP:

  • Privacy-respecting searches
  • Developer-focused results
  • Better API documentation discovery

MCP Detection Pattern

Skills should detect MCP availability and adapt:

// Example pattern in skill documentation
**If GitHub MCP available**:
- Use `github_create_pull_request` for PR creation
- Otherwise: Fall back to `gh pr create` command

**If Memory MCP available**:
- Store ADR summary with `create_entities`
- Otherwise: Skip memory persistence (no error)

Benefits Summary

With Tier 1 MCPs (GitHub + Memory):

  • 40% faster PR workflows - Direct API access vs CLI parsing
  • Cross-session continuity - Remember patterns and decisions
  • Better code search - GitHub API search vs local grep
  • Historical context - Why decisions were made, not just what

With Tier 2 MCPs (Sequential Thinking + Brave):

  • Improved planning - Systematic problem decomposition
  • Better research - Developer-focused search results
  • Enhanced debugging - Structured root cause analysis
  • Architectural insight - Trade-off analysis support

Future MCP Considerations

Tier 3 (Future):

  • Filesystem MCP - Advanced file operations
  • Puppeteer MCP - Browser automation for E2E testing
  • Slack/Discord MCP - Team notifications
  • PostgreSQL/Database MCPs - Database operations

Troubleshooting

MCP Not Working

  1. Verify MCP server is installed: npx -y @modelcontextprotocol/server-github --version
  2. Check API keys are configured in Claude Code settings
  3. Restart Claude Code after configuration changes
  4. Check MCP server logs for errors

Performance Issues

  • MCPs add latency for network calls
  • Memory MCP should be lightweight (local storage)
  • GitHub MCP caches responses (check cache settings)
  • Sequential Thinking MCP has minimal overhead

Tool Selection

  • Skills should gracefully degrade without MCPs
  • Always provide CLI fallback paths
  • Document MCP vs non-MCP behavior differences

References

See Also