opal-mcp-adapter

MCP-Opal Adapter

A bidirectional adapter service that converts between MCP (Model Context Protocol) tools and Opal tools using the official Opal Tools SDK with automatic MCP discovery.

Key Features

• MCP Discovery: Automatically discovers tools from MCP servers
• Proper Opal Tools SDK Integration: Uses ToolsService and @tool decorator
• Dynamic Schema Translation: JSON Schema to Pydantic model conversion
• JSON-RPC Proxy: Forwards MCP calls via JSON-RPC protocol
• Discovery Endpoint: Exposes /discovery for tool listing
• Just-in-Time Configuration: HTTP API for dynamic tool registration

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    HTTP Configuration API                   │
│           POST /register (MCP endpoint only)                │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                 MCP-Opal Proxy Service                      │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │   MCP Discovery │◄──►│   Opal Tools    │                 │
│  │   (tools/list)  │    │   SDK           │                 │
│  └─────────────────┘    └─────────────────┘                 │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │  Dynamic Tool   │    │  Protocol       │                 │
│  │  Registry       │    │  Translator     │                 │
│  └─────────────────┘    └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

Quick Start

1. Build and Run

# Build the Docker image
docker build -t mcp-opal-adapter .

# Run with Docker Compose
docker-compose up -d

2. Configure MCP Tools via Discovery

# Configure tools by discovering them from an MCP server
curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '"http://your-mcp-server:3000"'

3. Discover Available Tools

# Get list of available Opal tools
curl http://localhost:8000/discovery

4. Call Tools

# Call a discovered tool
curl -X POST http://localhost:8000/tools/weather_lookup \
  -H "Content-Type: application/json" \
  -d '{"location": "New York", "units": "imperial"}'

API Reference

Configuration Endpoints

POST /register

Configure MCP tools by discovering them from an MCP server.

Request Body:

"http://mcp-server:3000"

Response:

{
  "status": "configured",
  "tools": ["weather_lookup", "calculator"],
  "total_discovered": 2,
  "successfully_configured": 2
}

Opal Tools Endpoints

GET /discovery

Discover available Opal tools (auto-generated by Opal Tools SDK).

POST /tools/{tool_name}

Call a configured tool via Opal interface.

Request Body:

{
  "param1": "value1",
  "param2": 42
}

Management Endpoints

GET /health

Health check endpoint.

GET /status

Get adapter status and configuration.

DELETE /tools/{tool_name}

Remove a configured tool.

MCP Discovery Process

The adapter automatically:

1. Discovers Tools: Calls tools/list on the MCP server
2. Extracts Schemas: Gets tool names, descriptions, and input schemas
3. Converts Schemas: Transforms JSON Schema to Pydantic models
4. Creates Proxies: Generates proxy functions for each tool
5. Registers Tools: Registers them with the Opal Tools SDK

MCP Protocol Support

The adapter supports the standard MCP protocol:

• tools/list: Discovers available tools
• tools/call: Executes tool calls via JSON-RPC
• server/health: Health checking (optional)

Development

Local Development

# Install uv if not already installed
pip install uv

# Install dependencies using uv
uv sync

# For development with testing tools
uv sync --extra dev

# Run development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Testing

# Run tests using uv
uv run pytest

# Or install dev dependencies and run tests
uv sync --extra dev
pytest

Development Workflow

# Install all dependencies including dev tools
make build-dev

# Run tests
make test

# Run development server
make run

Deployment

Docker Compose

version: '3.8'
services:
  mcp-opal-adapter:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ADAPTER_PORT=8000
      - LOG_LEVEL=info
    networks:
      - adapter-network

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-opal-adapter
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-opal-adapter
  template:
    metadata:
      labels:
        app: mcp-opal-adapter
    spec:
      containers:
      - name: adapter
        image: mcp-opal-adapter:latest
        ports:
        - containerPort: 8000
        env:
        - name: ADAPTER_PORT
          value: "8000"
        - name: LOG_LEVEL
          value: "info"

Protocol Translation

MCP to Opal Flow

1. Discover Tools: Call tools/list on MCP server
2. Convert Schema: JSON Schema → Pydantic model using create_model()
3. Create Proxy Function: Async function that forwards to MCP server
4. Register with Opal SDK: Use @tool decorator to register
5. Handle Calls: Proxy function forwards JSON-RPC calls to MCP server

JSON-RPC Proxy

# MCP JSON-RPC request format
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {"param1": "value1"}
  }
}

Key Implementation Details

Opal Tools SDK Integration

from opal_tools_sdk import ToolsService, tool

# Initialize with FastAPI app
app = FastAPI()
tools_service = ToolsService(app)

# Register dynamic tool
tool_decorator = tool("tool_name", "description")
registered_func = tool_decorator(proxy_function)

Dynamic Pydantic Model Creation

from pydantic import create_model

# Convert JSON Schema to Pydantic model
model_class = create_model(
    "ToolParameters",
    **field_definitions
)

MCP Discovery Function

async def discover_mcp_tools(mcp_endpoint: str):
    # Call tools/list on MCP server
    discovery_request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
    }
    # Process response and extract tool information

Error Handling

Network Errors

• Connection timeouts (30s default)
• MCP server unavailability
• JSON-RPC protocol errors

Validation Errors

• Schema validation failures via Pydantic
• Required field missing
• Type conversion errors

Discovery Errors

• MCP server discovery failures
• Invalid tool schemas
• Duplicate tool names

Monitoring

Health Checks

• Service availability
• Tool count monitoring
• Configuration status

Logging

• Structured logging throughout
• Error tracking
• Performance monitoring

Security Considerations

Input Validation

• Schema-based validation via Pydantic
• Type checking and conversion
• Required field enforcement

Network Security

• Timeout configuration
• Error message sanitization
• Connection pooling

Future Enhancements

Planned Features

• Authentication and authorization
• Rate limiting
• Caching layer
• Metrics collection
• WebSocket support
• GraphQL interface

Scalability Improvements

• Database persistence
• Load balancing
• Service discovery
• Circuit breaker pattern

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.