mcp

Model Context Protocol (MCP) Implementation

This directory contains the comprehensive Model Context Protocol (MCP) implementation for the GeneralizedNotationNotation (GNN) project. The MCP server exposes all GNN functionalities as standardized tools that can be accessed by MCP-compatible clients.

Overview

The GNN MCP implementation provides:

• Core MCP Server: JSON-RPC 2.0 compliant server with tool and resource management
• Multiple Transport Layers: stdio and HTTP transport support
• Comprehensive Tool Ecosystem: Tools from all GNN modules (gnn, type_checker, export, visualization, etc.)
• Meta-Tools: Server introspection and diagnostic capabilities
• CLI Interface: Command-line access to all MCP functionality
• Extensible Architecture: Easy addition of new tools and resources

Architecture

graph TD
    Client[MCP Client] --> Transport{Transport Layer}
    
    Transport -->|stdio| Stdio[Stdio Server]
    Transport -->|http| HTTP[HTTP Server]
    
    Stdio & HTTP --> Core[Core MCP Server]
    
    Core --> Reg[Tool Registry]
    Core --> Res[Resource Manager]
    Core --> Meta[Meta Tools]
    
    Reg --> GNN[GNN Tools]
    Reg --> Viz[Viz Tools]
    Reg --> Export[Export Tools]
    Reg --> Others[...]

Loading

Core Components

1. MCP Server (mcp.py)

The central MCP server implementation that:

• Manages tool and resource registration
• Handles JSON-RPC 2.0 requests
• Provides module discovery and loading
• Implements error handling and logging
• Tracks performance metrics

Key Features:

• Dynamic module loading
• Tool and resource registration
• Performance tracking
• Error handling with custom MCP error codes
• Server status monitoring

2. Transport Servers

stdio Server (server_stdio.py)

• Reads JSON-RPC requests from stdin
• Writes responses to stdout
• Multi-threaded architecture for concurrent processing
• Ideal for local process communication

HTTP Server (server_http.py)

• HTTP-based JSON-RPC server for local orchestration
• Defaults to 127.0.0.1
• Supports bearer-token auth through GNN_MCP_TOKEN
• Supports per-client rate limiting through GNN_MCP_RATE_LIMIT_PER_MINUTE
• Exposes only a safe tool allowlist by default; unsafe tools require explicit opt-in
• Denies resource reads by default; expose individual URIs with GNN_MCP_SAFE_RESOURCES
• Filters HTTP capability responses to the same safe tool/resource surface

3. Command Line Interface (cli.py)

Comprehensive CLI for MCP operations:

# List all capabilities
python -m src.mcp.cli list

# Execute a tool
python -m src.mcp.cli execute get_gnn_files --params '{"target_dir": "doc"}'

# Get server status
python -m src.mcp.cli status

# Start server
python -m src.mcp.cli server --transport stdio
GNN_MCP_TOKEN=local-dev-token python -m src.mcp.cli server --transport http --host 127.0.0.1 --port 8080

4. Meta-Tools (meta_mcp.py)

Server introspection and diagnostic tools:

• get_mcp_server_capabilities: Full server capabilities
• get_mcp_server_status: Operational status and metrics
• get_mcp_server_auth_status: Authentication configuration
• get_mcp_server_encryption_status: Encryption status
• get_mcp_module_info: Detailed module information
• get_mcp_tool_categories: Tools organized by category
• get_mcp_performance_metrics: Performance statistics

Available Tools by Module

GNN Module (src/gnn/mcp.py)

• GNN file discovery and parsing
• Model structure analysis
• Parameter extraction and validation

Type Checker (src/type_checker/mcp.py)

• GNN syntax validation
• Resource estimation
• Type consistency checking

Export (src/export/mcp.py)

• Multi-format export (JSON, XML, GraphML, GEXF, Pickle)
• Network graph export
• Structured data preservation

Visualization (src/visualization/mcp.py)

• Graph visualization
• Matrix visualization
• Ontology relationship diagrams

Render (src/render/mcp.py)

• PyMDP code generation
• RxInfer.jl model translation
• Template-based code generation

Execute (src/execute/mcp.py)

• Script execution
• Result capture and reporting
• Multi-backend support

LLM (src/llm/mcp.py)

• AI-powered model analysis
• Enhancement suggestions
• Natural language explanations

Website (src/website/mcp.py)

• HTML website generation
• Report aggregation
• Interactive elements

SAPF (src/sapf/mcp.py)

• Audio generation and sonification
• Model sonification
• Real-time audio processing

Pipeline (src/pipeline/mcp.py)

• Pipeline step discovery
• Execution monitoring
• Configuration management

Utils (src/utils/mcp.py)

• System diagnostics
• File operations
• Environment validation

Usage Examples

1. Starting the MCP Server

stdio Transport (Recommended for local use)

python -m src.mcp.cli server --transport stdio

HTTP Transport (Local JSON-RPC orchestration)

GNN_MCP_TOKEN=local-dev-token python -m src.mcp.cli server --transport http --host 127.0.0.1 --port 8080

HTTP tool execution and resource reads are guarded separately. Tool calls are limited to the safe HTTP allowlist, while mcp.resource.get returns an error unless the requested URI is listed in GNN_MCP_SAFE_RESOURCES. Rate limiting is evaluated before bearer authentication so bad-token traffic is throttled by the same per-client limit.

2. Using the CLI

List all available tools

python -m src.mcp.cli list --format human

Execute a GNN tool

python -m src.mcp.cli execute get_gnn_files --params '{"target_dir": "doc", "recursive": true}'

Get server status

python -m src.mcp.cli status --format json

3. JSON-RPC API Usage

Get server capabilities

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mcp.capabilities",
  "params": {}
}

Execute a tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mcp.tool.execute",
  "params": {
    "name": "get_gnn_files",
    "params": {
      "target_dir": "doc",
      "recursive": true
    }
  }
}

Direct tool invocation

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "get_gnn_files",
  "params": {
    "target_dir": "doc",
    "recursive": true
  }
}

Error Handling

The MCP implementation provides comprehensive error handling:

Standard JSON-RPC Error Codes

• -32700: Parse error
• -32600: Invalid Request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error

Custom MCP Error Codes

• -32000: MCP-specific errors
• -32001: Tool execution errors
• -32002: Resource retrieval errors
• -32003: Module loading errors

Error Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Tool execution failed",
    "data": {
      "tool": "get_gnn_files",
      "details": "Target directory not found"
    }
  }
}

Performance Monitoring

The MCP server tracks various performance metrics:

• Request count and error rates
• Average execution times per tool
• Module loading statistics
• Server uptime and activity

Access performance data via:

python -m src.mcp.cli execute get_mcp_performance_metrics

Security Considerations

Transport Security

• stdio: Local process only, high security
• HTTP: Network accessible, consider HTTPS for production

Authentication

• HTTP transport requires Authorization: Bearer <GNN_MCP_TOKEN> by default.
• Missing or invalid bearer tokens receive 401 before JSON-RPC execution.
• Unauthenticated HTTP is only available for explicit loopback development with GNN_MCP_ALLOW_INSECURE_LOCAL=1; non-loopback clients still receive 401.
• Resource reads over HTTP are denied unless the exact URI is included in GNN_MCP_SAFE_RESOURCES.
• HTTP capability discovery lists only tools and resources exposed by those allowlists.
• Use stdio transport for maximum security.

Recommendations

1. Use stdio transport for local-only access
2. Keep HTTP bound to 127.0.0.1 unless a separate trusted reverse proxy is used
3. Set GNN_MCP_TOKEN for every HTTP run
4. Set GNN_MCP_SAFE_RESOURCES only for resource URIs that are safe to expose
5. Monitor access logs and performance metrics

Development and Extension

Adding New Tools

1. Create or update the module's mcp.py file
2. Implement tool functions with proper error handling
3. Register tools using mcp_instance.register_tool()
4. Add comprehensive documentation and schemas

Example Tool Registration

def register_tools(mcp_instance):
    mcp_instance.register_tool(
        name="my_tool",
        func=my_tool_function,
        schema={
            "type": "object",
            "properties": {
                "param1": {"type": "string"}
            },
            "required": ["param1"]
        },
        description="Description of my tool",
        module="my_module",
        category="My Category",
        version="1.0.0"
    )

Testing MCP Tools

Use the CLI to test tools:

# Test tool execution
python -m src.mcp.cli execute my_tool --params '{"param1": "value"}'

# Test tool info
python -m src.mcp.cli info my_tool

Integration with External Clients

Claude Desktop

Configure Claude Desktop to use the GNN MCP server:

{
  "mcpServers": {
    "gnn": {
      "command": "python",
      "args": ["-m", "src.mcp.cli", "server", "--transport", "stdio"]
    }
  }
}

Other MCP Clients

The server is compatible with any JSON-RPC 2.0 MCP client. Use the HTTP transport for network-based clients or stdio for local integration.

Troubleshooting

Common Issues

1. Module Import Errors

   • Ensure all dependencies are installed
   • Check Python path configuration
   • Verify module structure

2. Tool Execution Failures

   • Check tool parameters and schemas
   • Review error messages and logs
   • Validate input data

3. Server Connection Issues

   • Verify transport configuration
   • Check firewall settings for HTTP transport
   • Ensure proper permissions

Debug Mode

Enable verbose logging:

python -m src.mcp.cli --verbose list

Log Files

Check log files in the output directory:

ls -la output/logs/

Contributing

When contributing to the MCP implementation:

1. Follow the established patterns for tool registration
2. Add comprehensive error handling
3. Include proper documentation and schemas
4. Test with both stdio and HTTP transports
5. Update this README for new features

References

• Model Context Protocol Specification
• JSON-RPC 2.0 Specification
• Comprehensive MCP Documentation — Full implementation guide and live audit commands for the registered tool surface
• GNN Project Documentation
• MCP Integration Guide
• Project overview: ../../README.md
• Comprehensive docs: ../../DOCS.md
• Pipeline details (Step 22): ../../doc/pipeline/README.md

---

Documentation

• README: Module Overview
• AGENTS: Agentic Workflows
• SPEC: Architectural Specification
• SKILL: Capability API