Skip to content

ADR-017: MCP Server Integration Pattern

Status

Accepted

Context

GitHub Copilot Agent can be extended with Model Context Protocol (MCP) servers to provide specialized tools and capabilities. For OSDU fork repositories managed by this template, there's a specific need for AI-enhanced Maven dependency management, security scanning, and version control.

The Maven MCP Server provides tools specifically designed for Java/Maven projects, which are common in the OSDU ecosystem. This creates an opportunity to enhance the AI development workflow for fork repositories.

Requirements

  1. Automatic MCP Configuration: Fork repositories should have MCP servers configured automatically during initialization
  2. Template Consistency: All fork instances should have the same MCP capabilities
  3. Template Updates: MCP configuration should be updatable through template synchronization
  4. Security: MCP server integration must follow security best practices
  5. Documentation: Clear guidance for users on MCP capabilities and usage

Current Limitations

  • Manual MCP configuration is error-prone and inconsistent
  • No standardized way to provide MCP capabilities across fork instances
  • Template updates don't include MCP enhancements
  • Limited documentation for AI-enhanced dependency management workflows

Decision

We will implement an MCP Configuration Template Pattern that:

  1. Stores MCP configuration in fork-resources: Place mcp-config.json in .github/fork-resources/ for automatic deployment
  2. Automatically deploys during initialization: Copy MCP configuration to fork repositories during initialization workflow
  3. Includes in template synchronization: Allow MCP configuration updates through template sync workflow
  4. Provides comprehensive documentation: Include setup instructions and usage examples
  5. Uses read-only, security-focused MCP servers: Start with Maven MCP Server which provides read-only dependency analysis

Implementation Details

{
  "mcpServers": {
    "mvn-mcp-server": {
      "command": "uvx",
      "args": ["mvn-mcp-server"]
    }
  }
}

Workflow Integration

  • Initialization: init-complete.yml copies MCP configuration from fork-resources to .github/mcp-config.json
  • Template Sync: Future template updates can modify MCP configuration
  • Documentation: Comprehensive guide in doc/mcp-integration.md

Consequences

Positive

  • Consistent AI Capabilities: All fork instances have the same MCP server tools
  • Enhanced Dependency Management: AI agents can perform version checking, security scanning, and batch dependency analysis
  • Reduced Setup Friction: No manual MCP configuration required
  • Template Evolution: MCP capabilities can be enhanced across all fork instances
  • Security Focus: Read-only MCP servers minimize security risks
  • Documentation Coverage: Clear guidance for AI-enhanced workflows

Negative

  • Additional Complexity: Template includes another configuration layer
  • Dependency on External MCP Server: Relies on external repository for MCP server code
  • Network Requirements: MCP server requires network access to Maven Central
  • Python Runtime Dependency: MCP server requires Python 3.12+ and UV package manager

Risk Mitigation

  • MCP Server Validation: Use pinned versions and verify MCP server repository integrity
  • Fallback Behavior: GitHub Copilot Agent works normally without MCP servers if they fail
  • Documentation: Clear troubleshooting guide for MCP-related issues
  • Security Review: Regular review of MCP server capabilities and permissions

Alternatives Considered

1. Manual MCP Configuration

Rejected: Inconsistent setup, prone to errors, doesn't scale with template updates

2. External MCP Configuration Service

Rejected: Adds unnecessary complexity and external dependencies

3. Embedded MCP Tools

Rejected: Would require maintaining MCP server code within template

4. No MCP Integration

Rejected: Misses opportunity for AI-enhanced dependency management

Implementation Plan

  1. ✅ Create MCP configuration template in fork-resources
  2. ✅ Update initialization workflow to deploy MCP configuration
  3. ✅ Add comprehensive documentation
  4. ✅ Update completion messages to mention MCP setup
  5. 🔄 Update Copilot instructions to include MCP context
  6. 📋 Test MCP integration in fork repository
  7. 📋 Add MCP configuration to template sync workflow
  • ADR-014: AI-Enhanced Development Workflow - Establishes AI-first development patterns
  • ADR-002: GitHub Actions Automation - Provides workflow automation foundation
  • ADR-007: Initialization Workflow Bootstrap - Defines repository setup patterns

References

← ADR-016 | Catalog | ADR-018 →