opal-mcp-adapter 0.0.5

Bidirectional adapter for converting between MCP and Opal tools

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.

Quick start

Install the opal-mcp-adapter cli

pip install opal-mcp-adapter

Start the mcp adapter with an mcp config

opal-mcp-adapter --port 8030 --config mcp.json

You can now see the MCP tools registered as Opal tools at

http://localhost:8030/discovery

and use them inside Opal

Usage

Using a config file

The adapter supports standard mcp.json files as a config argument

A sample mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

In order to run these mcp tools through the adapter, it needs to be pointed towards the config file

opal-mcp-adapter --config mcp.json

This will register the servers defined in the config file, and launch a compatible opal tools server at "http://localhost:8000" (with the default host and port)

See more mcp.json examples here https://modelcontextprotocol.io/quickstart/user

CLI Usage Examples

The opal-mcp-adapter command supports various options for customizing the server behavior:

# Start server on 0.0.0.0:8000 (default)
opal-mcp-adapter

# Start server on localhost:8000
opal-mcp-adapter --host localhost

# Start server on 0.0.0.0:9000
opal-mcp-adapter --port 9000

# Start server on 127.0.0.1:8080
opal-mcp-adapter --host 127.0.0.1 --port 8080

# Start server with MCP configuration file
opal-mcp-adapter --config mcp.json

# Start server on custom port with config
opal-mcp-adapter --port 8030 --config mcp.json

# Display version information
opal-mcp-adapter --version

Command Line Options

• --host: Host address to bind the server to (default: 0.0.0.0)
• --port: Port number to bind the server to (default: 8000)
• --config: Path to the MCP configuration file
• --version: Display version information and exit

Port Validation

The CLI validates that the port number is within the valid range (1-65535). If an invalid port is specified, the command will exit with an error message.

API Usage Examples

The MCP-Opal adapter provides a REST API for dynamic tool registration and management. All endpoints return JSON responses.

Register MCP Tools

POST /register

Register MCP tools by discovering them from an MCP server via HTTP transport.

Request Body:

{
  "transport": "http",
  "url": "http://localhost:3000"
}

Example using curl:

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "http",
    "url": "http://localhost:3000"
  }'

Response:

{
  "status": "registered",
  "tools": ["tool1", "tool2", "tool3"],
  "total_discovered": 3,
  "successfully_registered": 3
}

Error Response (400):

{
  "detail": "Failed to discover tools from http://localhost:3000: Connection refused"
}

Health Check

GET /health

Check the health status of the adapter service.

Example using curl:

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "mcp_tools_count": 5,
  "opal_tools_count": 5
}

Get Adapter Status

GET /status

Get detailed status and configuration information.

Example using curl:

curl http://localhost:8000/status

Response:

{
  "mcp_tools": ["filesystem_read", "filesystem_write", "web_search"],
  "opal_tools": ["filesystem_read", "filesystem_write", "web_search"],
  "opal_discovery_url": "/discovery"
}

Remove a Tool

DELETE /tools/{tool_name}

Remove a configured tool from the adapter.

Example using curl:

curl -X DELETE http://localhost:8000/tools/filesystem_read

Response:

{
  "status": "removed",
  "tool": "filesystem_read"
}

Error Response (404):

{
  "detail": "Tool not found"
}

Complete API Workflow Example

Here's a complete example of registering and using MCP tools:

# 1. Start the adapter server
opal-mcp-adapter --port 8000

# 2. Register MCP tools from a server
curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "http",
    "url": "http://localhost:3000"
  }'

# 3. Check health status
curl http://localhost:8000/health

# 4. View registered tools
curl http://localhost:8000/status

# 5. Access Opal tools discovery endpoint
curl http://localhost:8000/discovery

# 6. Remove a tool when no longer needed
curl -X DELETE http://localhost:8000/tools/tool_name

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     │                 │
│  └─────────────────┘    └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

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 /configure/{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)

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.