TheRock/rocm-systems/experimental/python/perfxpert/docs/contributing/mcp_tools.md

Contributing: new MCP tool

What you're adding

A wrapper that exposes a perfxpert tool to external clients (Claude Desktop, Cursor, etc.) via the Model Context Protocol. MCP tools must preserve the READ_ONLY class invariant — no EXECUTION tools are exposed.

File locations

• MCP server: mcp_server/
• Tool wrapper: mcp_server/tools/<name>.py
• Tests: tests/test_mcp/test_<name>.py

Key constraint

Only READ_ONLY tools are exposed via MCP. EXECUTION tools must remain in-process only. CI enforces this via tests/test_integration/test_mcp_exposure.py.

Template

# SKIP-SAMPLE — template: <name> is a placeholder
"""<name> MCP tool wrapper."""

from typing import Any, Dict

import mcp.types as types
from mcp.server import RequestContext

from perfxpert.tools import my_read_only_tool


async def handle_name(
    context: RequestContext,
    **kwargs: Any
) -> list[types.TextContent | types.ImageContent]:
    """MCP handler for <name>."""
    try:
        result = my_read_only_tool(**kwargs)
        return [types.TextContent(type="text", text=str(result))]
    except Exception as e:
        return [types.TextContent(type="text", text=f"Error: {e}")]

Registration

Add to MCP server tool list:

# SKIP-SAMPLE — template: `server` and `handle_tool_call` are placeholders
server.set_request_handler(
    types.messages.CallToolRequest,
    lambda ctx, req: handle_tool_call(ctx, req)
)

Schema constraints (CI-enforced)

• Wrapping tool must have ToolClass.READ_ONLY set
• MCP exposure test (test_mcp_exposure.py) verifies no EXECUTION tools leak
• Type hints on wrapper args + return

Tests you must add

• test_<name>_mcp_wraps_read_only_tool() — class invariant
• test_<name>_returns_valid_mcp_content() — output shape
• test_<name>_handles_error() — error path

Review requirements

• 1 security-focused reviewer
• Exposure test green (no EXECUTION tools)
• CI green (unit + MCP policy)

Common pitfalls

• Don't wrap EXECUTION tools — they must stay in-process
• MCP responses are text + images only — complex types must serialize to JSON
• Error messages should not leak internal details

Related docs

• Design spec: Appendix A (tool-class split)
• MCP spec: https://modelcontextprotocol.io/
• Exposure test: tests/test_integration/test_mcp_exposure.py