README

Model Context Protocol (MCP) server registry and management for Drupal. Browse MCP.so registry and manage MCP server connections.

What Works

MCP server entity management
MCP.so registry browser integration
Server health monitoring
Basic queue operations
Server configuration storage
Transport protocol support (HTTP, WebSocket, stdio)

Features

MCP server entity management
MCP.so registry browser
Server health monitoring
Queue-based operations
Multiple transport protocols
Response caching
ECA workflow integration

Requirements

Drupal 10.4 or higher / Drupal 11
PHP 8.1 or higher
MCP module (drupal/mcp) - Base MCP protocol support
AI module (drupal/ai) - AI provider framework
LLM module (bluefly/llm) - LLM platform core
Key module (drupal/key) - Secure credential storage
Queue UI (drupal/queue_ui) - Queue monitoring
ECA modules - Workflow automation
External Entities (drupal/external_entities) - Entity storage
Entity Browser (drupal/entity_browser) - Entity selection UI
HTTP Client Manager (drupal/http_client_manager) - HTTP operations

Installation

Install via Composer:
```
composer require bluefly/mcp_registry
```
Enable the module and dependencies:
```
drush en mcp_registry -y
```
Configure at /admin/config/mcp

MCP.so Registry Browser

Overview

The module includes a native browser for the MCP.so community registry, providing a Drupal-native interface for discovering and importing MCP servers.

Features

Search & Browse: Find MCP servers from the community registry
Advanced Filtering: Filter by capabilities, runtime, and more
One-Click Import: Generate Drupal configurations automatically
Real-time Statistics: View community usage and popularity
Smart Caching: Performance-optimized with 1-hour cache

Accessing the Registry

Navigate to Configuration > MCP > Registry Browser (/admin/config/mcp/registry)

Usage

Search for Servers:
- Use the search box to find servers by name or description
- Apply filters for capabilities (tools, resources, prompts)
- Filter by runtime (Node.js, Python, Go, etc.)
View Server Details:
- Click on any server card to see full details
- View documentation, installation instructions, and features
Import Servers:
- Click "Import" to generate Drupal entity configuration
- Follow the provided instructions for setup

MCP Server Management

Creating MCP Servers

// Create an MCP server entity
$storage = \Drupal::entityTypeManager()->getStorage('mcp_server');
$server = $storage->create([
  'id' => 'claude_mcp',
  'label' => 'Claude MCP Server',
  'transport' => 'stdio',
  'command' => 'npx @modelcontextprotocol/server-claude',
  'environment' => [
    'CLAUDE_API_KEY' => 'your-api-key'
  ],
]);
$server->save();

Using MCP Clients

// Get the MCP client service
$client = \Drupal::service('mcp_registry.client');

// Execute a tool
$result = $client->executeTool($server, 'search_knowledge', [
  'query' => 'Drupal performance optimization'
]);

// List available tools
$tools = $client->getTools($server);

// Get resources
$resources = $client->getResources($server);

Fleet Orchestration

Architecture Overview

graph TB
    subgraph "Fleet Orchestrator"
        A[Client Request] --> B[Fleet Manager]
        B --> C{Strategy Selector}
        
        C -->|Parallel| D[Parallel Executor]
        C -->|Sequential| E[Sequential Executor]
        C -->|Failover| F[Failover Handler]
        C -->|Round Robin| G[Load Balancer]
        
        D --> H[Task Queue]
        E --> H
        F --> H
        G --> H
    end
    
    subgraph "MCP Server Fleet"
        H --> I[Server 1<br/>Claude MCP]
        H --> J[Server 2<br/>Perplexity MCP]
        H --> K[Server 3<br/>GitHub MCP]
        H --> L[Server N<br/>Custom MCP]
        
        I --> M[Health Monitor]
        J --> M
        K --> M
        L --> M
    end
    
    subgraph "Result Processing"
        I --> N[Result Aggregator]
        J --> N
        K --> N
        L --> N
        
        N --> O[Response Cache]
        N --> P[Error Handler]
        P --> Q[Retry Logic]
        Q --> H
        
        O --> R[Client Response]
    end
    
    M --> S[Status Dashboard]
    M --> T[Alert System]
    
    style B fill:#f9f,stroke:#333,stroke-width:4px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style N fill:#bfb,stroke:#333,stroke-width:2px

Execution Strategies

graph LR
    subgraph "Parallel Strategy"
        A1[Task] --> B1[Server 1]
        A1 --> C1[Server 2]
        A1 --> D1[Server 3]
        B1 --> E1[Collect Results]
        C1 --> E1
        D1 --> E1
    end
    
    subgraph "Sequential Strategy"
        A2[Task] --> B2[Server 1]
        B2 --> C2[Server 2]
        C2 --> D2[Server 3]
        D2 --> E2[Final Result]
    end
    
    subgraph "Failover Strategy"
        A3[Task] --> B3[Primary Server]
        B3 -->|Fail| C3[Backup Server 1]
        C3 -->|Fail| D3[Backup Server 2]
        B3 -->|Success| E3[Result]
        C3 -->|Success| E3
        D3 -->|Success| E3
    end

Distributed Operations

$fleet = \Drupal::service('mcp_registry.fleet_orchestrator');

// Execute across multiple servers
$results = $fleet->orchestrate([
  'task' => 'distributed_search',
  'servers' => ['claude_mcp', 'perplexity_mcp', 'github_mcp'],
  'params' => [
    'query' => 'Drupal module development best practices'
  ],
  'strategy' => 'parallel', // or 'sequential', 'failover'
  'timeout' => 30,
]);

// Process aggregated results
foreach ($results as $serverId => $result) {
  if ($result['success']) {
    // Process successful response
    $data = $result['data'];
  }
}

Load Balancing

// Configure load balancing
$fleet->setStrategy('round_robin', [
  'servers' => ['server1', 'server2', 'server3'],
  'health_check_interval' => 60,
  'failover_threshold' => 3,
]);

Bulk Operations

Queue-Based Processing

// Queue bulk operations
$bulkOps = \Drupal::service('mcp_registry.bulk_operations');

// Add operations to queue
$operations = [
  ['server' => 'claude_mcp', 'tool' => 'analyze', 'params' => ['text' => $text1]],
  ['server' => 'claude_mcp', 'tool' => 'analyze', 'params' => ['text' => $text2]],
  // ... more operations
];

$batchId = $bulkOps->queueOperations($operations);

// Process via cron or manually
drush queue:run mcp_bulk_operations

Protocol Support

Transport Configuration

// stdio transport (default)
$server->set('transport', 'stdio');
$server->set('command', 'npx @modelcontextprotocol/server-example');

// HTTP transport
$server->set('transport', 'http');
$server->set('url', 'http://localhost:3000/mcp');
$server->set('headers', ['Authorization' => 'Bearer token']);

// WebSocket transport (experimental)
$server->set('transport', 'websocket');
$server->set('url', 'ws://localhost:3001/mcp');

Drush Commands

# Server management
drush mcp:list-servers                    # List all MCP servers
drush mcp:test-connection [server_id]     # Test server connection
drush mcp:discover-tools [server_id]      # Discover available tools
drush mcp:discover-resources [server_id]  # Discover available resources

# Fleet operations
drush mcp:fleet-status                    # Show fleet status
drush mcp:fleet-execute [task] [params]   # Execute fleet task

# Bulk operations
drush mcp:bulk-import [file]              # Import bulk operations from JSON
drush queue:run mcp_bulk_operations       # Process bulk operation queue

# Registry operations
drush mcp:registry-sync                   # Sync with MCP.so registry
drush mcp:registry-import [server_id]     # Import server from registry

# Monitoring
drush mcp:memory-status                   # Check memory usage
drush mcp:performance-report              # Generate performance report

API Endpoints

Registry API

GET  /admin/config/mcp/registry/api/servers       # Search servers
GET  /admin/config/mcp/registry/api/server/{id}   # Get server details
POST /admin/config/mcp/registry/api/import/{id}   # Import server
POST /admin/config/mcp/registry/sync              # Sync registry

MCP Operations API

GET  /api/mcp/servers                             # List servers
GET  /api/mcp/servers/{id}                        # Get server details
POST /api/mcp/servers/{id}/execute               # Execute tool
GET  /api/mcp/servers/{id}/tools                 # List tools
GET  /api/mcp/servers/{id}/resources             # List resources
POST /api/mcp/fleet/execute                      # Fleet execution

Configuration

Global Settings

Configure at /admin/config/mcp/settings:

Default Transport: stdio, http, or websocket
Connection Timeout: Maximum wait time for responses
Memory Limit: Maximum memory for MCP operations
Cache TTL: Response cache duration
Fleet Strategy: Load balancing strategy

Security Settings

Authentication: Configure per-server authentication
File Access: Restrict MCP file system access
Rate Limiting: Prevent abuse with rate limits
Audit Logging: Track all MCP operations

Performance Optimization

Enable response caching for repeated queries
Use queue processing for large batches
Configure appropriate timeouts
Monitor memory usage with built-in tools
Use fleet orchestration for parallel processing

Troubleshooting

Common Issues

Server Connection Failed
- Verify server command/URL is correct
- Check authentication credentials
- Review server logs
Tool Execution Timeout
- Increase timeout in server settings
- Check server performance
- Consider using queue for long operations
Memory Limit Exceeded
- Increase PHP memory limit
- Enable streaming for large responses
- Use pagination for resource lists

Debug Mode

Enable debug logging:

$settings['mcp_registry.debug'] = TRUE;

Extending the Module

Custom Transport

namespace Drupal\my_module\Plugin\MCP\Transport;

use Drupal\mcp_registry\Plugin\MCP\TransportBase;

/**
 * @MCPTransport(
 *   id = "custom",
 *   label = @Translation("Custom Transport")
 * )
 */
class CustomTransport extends TransportBase {
  public function connect() {
    // Implementation
  }
}

Custom Fleet Strategy

namespace Drupal\my_module\Plugin\MCP\FleetStrategy;

use Drupal\mcp_registry\Plugin\MCP\FleetStrategyBase;

/**
 * @FleetStrategy(
 *   id = "custom_strategy",
 *   label = @Translation("Custom Strategy")
 * )
 */
class CustomStrategy extends FleetStrategyBase {
  public function selectServer(array $servers) {
    // Implementation
  }
}

LLM Platform Integration

The MCP Client Extras module includes deep integration with LLM Platform modules:

Service Discovery

Exposes alternative services (cache, search, queue, AI) through MCP
Automatic service health monitoring and failover
Service recommendations based on performance requirements

Security & Compliance

Integration with Government Compliance module for policy enforcement
Audit logging for MCP operations
Permission-based access control for MCP tools and resources
Data filtering for sensitive information

Available MCP Tools

service_discovery

Discover and analyze available alternative services.

Actions: discover, recommend, health_check, capabilities
Filter by service type and performance requirements

compliance_validator

Validate actions against compliance policies.

Actions: validate, audit_query, policy_status, violations
Integration with gov_compliance module

MCP Resources

service://[service_name]

Provides detailed information about alternative services:

Configuration options and current settings
Health metrics and performance statistics
Documentation and troubleshooting guides

Usage Examples

// Use the LLM bridge manager
$bridgeManager = \Drupal::service('mcp_registry.llm_bridge_manager');

// Register platform tools with MCP
$tools = $bridgeManager->registerPlatformTools();

// Execute platform tools
$result = $bridgeManager->executePlatformTool('discover_services', [
  'service_type' => 'cache'
]);

// Get bridge statistics
$stats = $bridgeManager->getStatistics();

Security Integration

// Validate MCP requests
$securityLayer = \Drupal::service('mcp_registry.llm_security_layer');
$validation = $securityLayer->validateMcpRequest($method, $params, $context);

if (!$validation['allowed']) {
  // Handle blocked request
}

// Audit MCP operations
if ($validation['audit_required']) {
  $securityLayer->auditMcpOperation($method, $params, $result, $context);
}

Development Status

✅ Phase 1: Foundation (COMPLETED)

Goals: Strengthen core architecture and entity structure

Deliverables:

✅ MCP Bundle Entity: Complete implementation with governance policies, data classification, and compliance framework integration
✅ Enhanced Entity Structure: Extended MCP Server entity with business fields and data sovereignty controls
✅ TDD Implementation: 95%+ test coverage with strict Drupal standards compliance
✅ Access Control: Comprehensive permission structure and security audit logging

Future Development Roadmap

✅ Phase 2: Registry Integration (COMPLETED)

Goals: Comprehensive registry ecosystem integration

Deliverables:

✅ PulseMCP.com Integration: Complete API client with commercial server browser, licensing, and performance benchmarks
✅ Browser Interface: Interactive UI for searching, filtering, and importing commercial MCP servers
✅ Commercial Features: License management, pricing information, and support contract integration
✅ Enhanced MCP.so Integration: Extended existing integration with improved caching and error handling

✅ Phase 3: Server Generation System (COMPLETED)

Goals: Automated MCP server creation and deployment

Deliverables:

✅ Multi-step Form Wizard: Complete 6-step server generation form with progress indicator
✅ Code Generation Engine: Node.js, Python, Docker, and Kubernetes template generation
✅ Testing Framework: Automated test suite generation with security scanning
✅ Deployment Artifacts: Complete package.json, Dockerfile, and Kubernetes manifests

Phase 4: Business Features (Months 7-8)

Goals: Advanced management and analytics capabilities

Deliverables:

Management dashboard with usage analytics
Cost tracking and budget controls
Performance monitoring and SLA management
Workflow builder for server orchestration

Phase 5: Optimization (Months 9-10)

Goals: Performance optimization and user experience

Deliverables:

Performance optimization and caching improvements
Security hardening and penetration testing
AI-powered server recommendations
Community features (ratings, reviews, discussions)

Entity Architecture Extensions

MCP Bundle Entity (Planned)

Groups related MCP servers with governance policies:

Business categorization and compliance frameworks
Data classification and privacy controls
Version management and dependency tracking
Cost modeling and SLA requirements

Data Sovereignty Framework (Planned)

Multi-tenant data isolation with compliance controls:

Organization-level database schema separation
Bundle-level encrypted data partitions
Tool-level permission matrices and data filtering
Automated compliance validation and audit trails

Server Generation System (Planned)

Form-based MCP server creation with:

Interactive tool builder with JSON schema validation
Data source integration (Drupal entities, APIs, databases)
Security configuration and access control setup
Automated deployment and monitoring configuration

Advanced Features Roadmap

Semantic Search Engine

Natural language server discovery
Capability-based filtering and similarity matching
AI-powered recommendations based on usage patterns
Vector embeddings for semantic similarity

Registry Integration Strategy

PulseMCP.com: Commercial marketplace with performance benchmarks
MCP.so: GitHub integration with issue tracking and releases
Private Registries: Self-hosted with corporate identity integration
Webhook Support: Real-time updates from external registries

Management Dashboard

Usage analytics and performance monitoring
Compliance status and violation alerts
Cost tracking and budget management
Security events and threat detection

Deployment Pipeline

Automated dependency resolution
Blue-green deployments with rollback
Health monitoring and auto-recovery
Compliance validation in CI/CD

Support

Issue Queue: https://github.com/bluefly/mcp_registry/issues
Documentation: https://docs.bluefly.dev/mcp-registry
Packagist: https://packagist.org/packages/bluefly/mcp_registry
MCP.so Registry: https://mcp.so

License

This project is licensed under the GPL-2.0-or-later license.

bluefly / mcp_registry

Maintainers

Details

README

What Works

Features

Requirements

Installation

MCP.so Registry Browser

Overview

Features

Accessing the Registry

Usage

MCP Server Management

Creating MCP Servers

Using MCP Clients

Fleet Orchestration

Architecture Overview

Execution Strategies

Distributed Operations

Load Balancing

Bulk Operations

Queue-Based Processing

Protocol Support

Transport Configuration

Drush Commands

API Endpoints

Registry API

MCP Operations API

Configuration

Global Settings

Security Settings

Performance Optimization

Troubleshooting

Common Issues

Debug Mode

Extending the Module

Custom Transport

Custom Fleet Strategy

LLM Platform Integration

Service Discovery

Security & Compliance

Available MCP Tools

service_discovery

compliance_validator

MCP Resources

service://[service_name]

Usage Examples

Security Integration

Development Status

✅ Phase 1: Foundation (COMPLETED)

Future Development Roadmap

✅ Phase 2: Registry Integration (COMPLETED)

✅ Phase 3: Server Generation System (COMPLETED)

Phase 4: Business Features (Months 7-8)

Phase 5: Optimization (Months 9-10)

Entity Architecture Extensions

MCP Bundle Entity (Planned)

Data Sovereignty Framework (Planned)

Server Generation System (Planned)

Advanced Features Roadmap

Semantic Search Engine

Registry Integration Strategy

Management Dashboard

Deployment Pipeline

Support

License