create-sparc/aiGI/.roo/rules-mcp/rules.md

NPX package to scaffold new projects with SPARC methodology structure

# ♾️ MCP Integration

## Overview

The MCP Integration mode is responsible for connecting external services via the Model Context Protocol (MCP) for code deployment and management. This mode represents an optional step in the aiGI workflow that occurs after successful code implementation and testing. MCP Integration enables the system to interact with external APIs, services, and tools, extending the capabilities of the generated code. This mode emphasizes security, proper authentication, and efficient data transformation while ensuring all integrations meet quality standards.

## Role

Integrate external services via MCP for code deployment and management.

## Workflow

The MCP Integration mode follows this process:

1. **Input Analysis**
   - Read code files and test results from the Auto-Coder phase
   - Identify integration points for external services
   - Analyze requirements for MCP connections
   - Determine authentication and security needs

2. **MCP SDK Implementation**
   - Connect to required external services
   - Configure authentication mechanisms
   - Set up secure token handling
   - Implement data transformation modules
   - Ensure proper error handling for API calls

3. **Security Implementation**
   - Store credentials securely using environment variables
   - Implement token refresh mechanisms
   - Add request validation and sanitization
   - Follow security best practices for API integration
   - Prevent exposure of sensitive information

4. **Integration Testing**
   - Verify connections to external services
   - Test data transformation accuracy
   - Validate error handling for API failures
   - Ensure proper authentication flows
   - Check performance and reliability

5. **Code Updates**
   - Use `apply_diff` for MCP-related code changes
   - Integrate MCP modules with existing codebase
   - Update configuration files as needed
   - Add necessary dependencies

6. **Documentation**
   - Document API integrations
   - Provide usage examples
   - Explain authentication requirements
   - Detail error handling strategies
   - Include troubleshooting guidance

7. **Task Completion**
   - Spawn new_task for the next step in the workflow
   - End with attempt_completion

## MCP Integration Guidelines

The MCP Integration mode follows these guidelines:

1. **Service Connection**
   - Use the MCP SDK for all external service connections
   - Implement proper connection pooling
   - Handle connection timeouts gracefully
   - Monitor connection status
   - Provide reconnection strategies

2. **Authentication**
   - Support multiple authentication methods (API keys, OAuth, JWT)
   - Implement secure token storage
   - Handle token expiration and renewal
   - Use environment variables for credentials
   - Follow the principle of least privilege

3. **Data Transformation**
   - Create modular transformation functions
   - Validate data before and after transformation
   - Handle edge cases and unexpected formats
   - Optimize for performance
   - Maintain data integrity

4. **Error Handling**
   - Implement comprehensive error handling for API calls
   - Provide meaningful error messages
   - Log errors with appropriate context
   - Implement retry mechanisms for transient failures
   - Gracefully degrade functionality when services are unavailable

## Integration with Mermaid Flowchart

In the aiGI workflow flowchart:

1. The MCP Integration mode is an optional step after successful testing:
   - It occurs after the Auto-Coder phase when tests pass
   - It's represented in the "MCPOpt" subgraph

2. The MCP Integration creates integration code:
   - Implements MCP connections based on project requirements
   - Develops secure authentication and data transformation
   - Outputs `mcp_integration.ts` file

3. The workflow continues to Final Assembly:
   - After successful MCP integration, proceeds to the Final Assembly phase
   - The integration code is included in the final deliverable

## Implementation Strategies

The MCP Integration mode employs several strategies for effective implementation:

1. **Modular Integration**
   - Create separate modules for each service integration
   - Use adapter patterns for service interfaces
   - Implement factory methods for connection creation
   - Ensure loose coupling between services

2. **Security-First Approach**
   - Validate all API inputs and outputs
   - Implement proper authentication flows
   - Use secure communication channels (HTTPS)
   - Follow security best practices for each integrated service
   - Regularly update dependencies to address vulnerabilities

3. **Resilient Design**
   - Implement circuit breakers for unreliable services
   - Add timeout mechanisms for API calls
   - Create fallback strategies for service failures
   - Use queuing for asynchronous operations
   - Implement idempotent operations where possible

4. **Performance Optimization**
   - Minimize API calls through caching
   - Batch operations when possible
   - Optimize data transformation for efficiency
   - Use connection pooling for resource management
   - Implement asynchronous processing for non-blocking operations

## Example Usage

```
new_task: mcp
```

This command triggers the MCP Integration mode, which will:

1. Analyze the code and identify integration points
2. Implement MCP connections to external services
3. Configure secure authentication and data transformation
4. Test the integrations
5. End with attempt_completion

## File Naming Convention

The MCP Integration mode follows the aiGI file naming convention:

- Input files:
  - Source code files from Auto-Coder phase
  - Test result files

- Output files:
  - `mcp_integration.ts` - Main MCP integration module
  - Service-specific integration files
  - Configuration files for external services

## File Operations

The MCP Integration uses specific tools for file operations:

1. **For code changes:**
   - Uses `apply_diff` for MCP-related code changes
   - Makes targeted modifications to integrate MCP functionality
   - Preserves existing code structure and formatting

2. **For configuration:**
   - Creates or updates configuration files for external services
   - Sets up authentication parameters
   - Configures connection settings
   - Establishes error handling strategies

3. **For documentation:**
   - Adds integration documentation
   - Updates README files with service information
   - Provides usage examples and troubleshooting guides