Skip to content

AGENTS.md

Latest commit

 

History

History
417 lines (312 loc) · 12.1 KB

AGENTS.md

File metadata and controls

417 lines (312 loc) · 12.1 KB
Raw

MCP Module - Agent Scaffolding

Module Overview

Purpose: Model Context Protocol implementation for standardized tool discovery, registration, and execution across all GNN modules

Pipeline Step: Step 21: Model Context Protocol processing (21_mcp.py)

Category: Protocol Integration / Tool Management

Status: ✅ Production Ready

Version: 1.7.0 (Extended from pipeline v1.6.0 — MCP subsystem has independent versioning)

Last Updated: 2026-04-16

Core Functionality

Primary Responsibilities

  1. Implement Model Context Protocol (MCP) for tool registration and discovery
  2. Provide standardized interface for tool execution across modules
  3. Enable inter-module communication and resource sharing
  4. Manage MCP server lifecycle and client connections
  5. Support multiple MCP transport protocols (stdio, HTTP, WebSocket)

Key Capabilities

  • Tool registration and discovery system
  • Resource access and management
  • JSON-RPC protocol implementation
  • Server and client implementations
  • Enhanced error handling and validation
  • Performance monitoring and caching
  • Concurrent execution control

API Reference

Public Functions

process_mcp(target_dir: Path, output_dir: Path, verbose: bool = False, logger: Optional[logging.Logger] = None, **kwargs) -> bool

Description: Main MCP processing function called by orchestrator (21_mcp.py). Discovers and registers MCP tools from all modules.

Parameters:

  • target_dir (Path): Directory containing GNN files
  • output_dir (Path): Output directory for MCP results
  • verbose (bool): Enable verbose logging (default: False)
  • logger (Optional[logging.Logger]): Logger instance for progress reporting (default: None)
  • mcp_mode (str, optional): MCP mode ("tool_discovery", "server", "client") (default: "tool_discovery")
  • enable_tools (bool, optional): Enable MCP tools functionality (default: True)
  • transport (str, optional): Transport protocol ("stdio", "http") (default: "stdio")
  • **kwargs: Additional MCP options

Returns: bool - True if MCP processing succeeded, False otherwise

Example:

from mcp import process_mcp
from pathlib import Path
import logging

logger = logging.getLogger(__name__)
success = process_mcp(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/21_mcp_output"),
    logger=logger,
    verbose=True,
    mcp_mode="tool_discovery",
    enable_tools=True,
    transport="stdio"
)

register_module_tools(module_name: Optional[str] = None) -> bool | List[Dict[str, Any]]

Description: Discover one (or all) pipeline modules and call their register_tools(mcp_instance) function against the global singleton. Each target module owns its tool definitions via src/<module>/mcp.py.

Parameters:

  • module_name (Optional[str]): Single module to register (e.g. "gnn"). None triggers full discovery via MCP.discover_modules().

Returns: bool when module_name is provided; a list of registered tool dictionaries when discovering all modules.

register_tools(mcp: Optional[MCP] = None) -> bool

Description: Module-level helper equivalent to mcp.discover_modules(). Registers every module's tools against the supplied MCP instance (default: the global singleton). Exposed from mcp.server_core and re-exported from the package.

Returns: bool — True when discovery runs to completion.

get_available_tools() -> List[Dict[str, Any]]

Description: Get list of all available MCP tools across all modules.

Returns: List[Dict[str, Any]] - List of tool information dictionaries with:

  • name (str): Tool name
  • module (str): Source module
  • description (str): Tool description
  • schema (Dict): Parameter schema
  • category (str): Tool category

MCP Protocol Implementation

Core Classes

MCP - Main Protocol Class

Description: Core Model Context Protocol implementation

Key Methods:

  • initialize() - Initialize MCP server
  • register_tools() - Register available tools
  • handle_request() - Process incoming requests
  • list_available_tools() - List available tools

MCPTool - Tool Definition Class

Description: Represents a registered MCP tool

Attributes:

  • name - Tool name
  • description - Tool description
  • input_schema - JSON schema for inputs
  • handler - Function to execute tool

MCPResource - Resource Definition Class

Description: Represents accessible MCP resources

Attributes:

  • uri - Resource URI
  • name - Resource name
  • description - Resource description
  • mime_type - Resource MIME type

Transport Protocols

STDIO Transport

  • Purpose: Standard input/output communication
  • Use Case: Local tool execution and testing
  • Implementation: mcp.server_stdio

HTTP Transport

  • Purpose: Web-based MCP server
  • Use Case: Remote tool access and web integration
  • Implementation: mcp.server_http

Dependencies

Required Dependencies

  • json - JSON-RPC protocol implementation
  • pathlib - Path and URI handling
  • typing - Type annotations and validation
  • logging - Request/response logging

Optional Dependencies

  • aiohttp - HTTP server implementation (recovery: basic HTTP)
  • websockets - WebSocket server (recovery: polling-based)
  • fastapi - REST API framework (recovery: basic HTTP)

Internal Dependencies

  • utils.pipeline_template - Standardized pipeline processing
  • pipeline.config - Configuration management

Configuration

Environment Variables

  • MCP_SERVER_PORT - MCP server port (default: 8080)
  • MCP_TRANSPORT - Transport protocol ("stdio", "http", "websocket")
  • MCP_LOG_LEVEL - MCP logging level ("DEBUG", "INFO", "WARNING", "ERROR")
  • MCP_TIMEOUT - MCP request timeout (default: 30 seconds)

Configuration Files

  • mcp_config.yaml - MCP server and tool configuration

Default Settings

The live defaults are embedded in mcp.mcp.MCP.__init__ and exposed via initialize(...). Authoritative table:

Knob Default CLI flag (step 21)
performance_mode "low" --performance-mode {low,medium,high}
strict_validation False (from mode) --mcp-strict-validation
enable_caching False (from mode) —
enable_rate_limiting False (from mode) —
cache_ttl 300.0 s --mcp-cache-ttl <seconds>
per_module_timeout 30.0 s --mcp-per-module-timeout <seconds>
overall_timeout 120.0 s --mcp-overall-timeout <seconds>
modules_allowlist None (all modules) --mcp-modules-allowlist a,b,c

See src/mcp/MCP_DOCUMENTATION.md → Configuration for the complete surface and src/mcp/SKILL.md for the capabilities-API summary.

Usage Examples

Basic MCP Processing

from mcp.processor import process_mcp

success = process_mcp(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/21_mcp_output"),
    logger=logger,
    mcp_mode="tool_discovery"
)

Tool Registration

from mcp import register_module_tools

success = register_module_tools("gnn")
all_tools = register_module_tools()

Tool Discovery

from mcp import get_available_tools

tools = get_available_tools()
for tool in tools:
    print(f"Tool: {tool['name']} - {tool['description']}")

Output Specification

Output Products

  • mcp_processing_summary.json - MCP processing summary
  • registered_tools.json - All registered tools information
  • mcp_server_status.json - Server status and configuration
  • tool_execution_log.json - Tool execution history

Output Directory Structure

output/21_mcp_output/
├── mcp_processing_summary.json
├── registered_tools.json
├── mcp_server_status.json
└── tool_execution_log.json

Performance Characteristics

Latest Execution

  • Duration: ~1-3 seconds (tool registration)
  • Memory: ~10-20MB for tool registry
  • Status: ✅ Production Ready

Expected Performance

  • Fast Path: <1s for tool discovery
  • Slow Path: ~5s for comprehensive tool validation
  • Memory: ~5-15MB for typical tool sets

Error Handling

Graceful Degradation

  • No transport libraries: Recovery to stdio-only mode
  • Tool registration failures: Continue with available tools
  • Server startup failures: Recovery to client-only mode

Error Categories

  1. Protocol Errors: Invalid JSON-RPC requests/responses
  2. Tool Errors: Tool execution failures or timeouts
  3. Transport Errors: Network or I/O communication failures
  4. Validation Errors: Invalid tool schemas or parameters

Integration Points

Orchestrated By

  • Script: 21_mcp.py (Step 21)
  • Function: process_mcp()

Imports From

  • utils.pipeline_template - Standardized processing patterns
  • pipeline.config - Configuration management

Imported By

  • src/tests/mcp/test_mcp_overall.py - MCP module tests
  • main.py - Pipeline orchestration

Data Flow

Module Tools → MCP Registration → Tool Discovery → Execution Requests → Response Handling

Testing

Test Files

  • src/tests/mcp/test_mcp_tools.py - Tool registration tests
  • src/tests/mcp/test_mcp_functional.py - Functional tests
  • src/tests/mcp/test_mcp_audit.py - Audit tests
  • src/tests/mcp/test_mcp_tools.py - Tool registration tests

Test Coverage

Measure on demand:

uv run --extra dev python -m pytest src/tests/test_mcp*.py \
    --cov=src/mcp --cov-report=term-missing

Key Test Scenarios

  1. Tool registration and discovery across modules
  2. JSON-RPC protocol compliance
  3. Multiple transport protocol operation
  4. Error handling with malformed requests
  5. Performance under concurrent tool execution

MCP Integration

Tools Registered (Across All Modules)

  • gnn_* - GNN file processing tools
  • analysis_* - Statistical analysis tools
  • visualization_* - Visualization generation tools
  • render_* - Code generation tools
  • gui_* - GUI interaction tools

Tool Categories

  • File Processing: GNN parsing, validation, transformation
  • Analysis: Statistical analysis, complexity metrics
  • Visualization: Chart generation, interactive displays
  • Code Generation: Multi-framework code rendering
  • Model Management: Registry operations, version control

Troubleshooting

Common Issues

Issue 1: Tool registration fails

Symptom: Tools not discovered or registered
Cause: Module discovery issues or tool definition errors
Solution:

  • Verify all modules have mcp.py files with tool definitions
  • Check tool function signatures match expected format
  • Use --verbose flag for detailed discovery logs
  • Review MCP tool registration patterns

Issue 2: Tool execution errors

Symptom: Tools registered but execution fails
Cause: Parameter validation errors or function implementation issues
Solution:

  • Verify tool parameter schemas are correct
  • Check tool function implementations handle errors
  • Review tool execution logs for specific errors
  • Validate tool inputs match schema

Version History

Current Version: 1.6.0

Features:

  • Tool registration and discovery
  • Resource access and management
  • JSON-RPC protocol implementation
  • Server and client implementations
  • Enhanced error handling
  • Performance monitoring

Known Issues:

  • None currently

Roadmap

  • Next Version: Enhanced transport protocols
  • Future: Real-time tool monitoring

References

Related Documentation

External Resources

Last Updated: 2026-04-16 Maintainer: GNN Pipeline Team Status: ✅ Production Ready Architecture Compliance: ✅ 100% Thin Orchestrator Pattern

Documentation

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