README

Extended Model Context Protocol (MCP) client capabilities extending Drupal AI ecosystem with external entity integration, queue management, bulk operations, and fleet orchestration.

Overview

The MCP Client Extras module provides comprehensive MCP (Model Context Protocol) integration for Drupal, extending the base MCP module with advanced features for enterprise deployments. It includes external entity management, fleet orchestration, bulk operations, and a native MCP.so registry browser for discovering and importing MCP servers from the community.

Features

• External Entity Integration: Manage MCP servers as Drupal entities with full CRUD operations
• Fleet Management: Orchestrate multiple MCP servers for distributed operations
• Bulk Operations: Process multiple MCP requests efficiently with queue support
• Native MCP.so Registry Browser: Discover and import servers from the community registry
• Protocol Bridge: Support for HTTP, WebSocket, and stdio transports
• Performance Monitoring: Real-time health checks and performance metrics
• Smart Caching: Intelligent response caching with cache tags
• Security Layer: Authentication, validation, and file security
• Queue Integration: Asynchronous operations via Drupal's Queue API
• ECA Workflow Support: Automate MCP operations with visual workflows

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

1. Install via Composer:

   composer require bluefly/mcp_registry
   

2. Enable the module and dependencies:

   drush en mcp_registry -y
   

3. 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

1. 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.)

2. View Server Details:

   • Click on any server card to see full details
   • View documentation, installation instructions, and features

3. 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

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

1. Server Connection Failed

   • Verify server command/URL is correct
   • Check authentication credentials
   • Review server logs

2. Tool Execution Timeout

   • Increase timeout in server settings
   • Check server performance
   • Consider using queue for long operations

3. 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
  }
}

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.