Schema Discovery & Auto-generation

Relevant source files

The following files were used as context for generating this wiki page:

• src/runtime/discover_schemas.py
• src/runtime/generate_test_params.py
• CLAUDE.md
• tests/unit/test_generate_test_params.py
• tests/unit/test_discover_schemas_mock.py
• install-global.sh

Schema Discovery and Auto-generation in Continuous Claude v2 is a specialized subsystem designed to bridge the gap between Model Context Protocol (MCP) servers and the Python runtime. While many MCP servers provide input schemas, they often lack explicit output schemas. This system automatically generates Pydantic models by introspecting tool definitions, classifying their safety, generating valid test parameters via LLMs, and inferring types from actual API responses.

The process ensures type safety and defensive coding patterns by marking all discovered fields as Optional. It supports a multi-transport architecture including stdio, SSE, and HTTP, allowing the runtime to work seamlessly with diverse MCP implementations while reducing token overhead through pre-generated wrappers.

Sources: src/runtime/discover_schemas.py:11-20, CLAUDE.md:65-75

Architectural Overview

The system operates in a multi-stage pipeline that starts with identifying tools in configured MCP servers and ends with the generation of static Python wrappers and Pydantic types.

The Discovery Pipeline

The following flowchart illustrates the sequence of operations from initial configuration to generated code.

The pipeline utilizes the McpClientManager to maintain connections and the generate_test_params module to handle LLM-driven parameter synthesis.
Sources: src/runtime/discover_schemas.py:145-170, src/runtime/generate_test_params.py:465-490

Tool Classification & Safety

Before executing tools to discover schemas, the system classifies them into safety categories. This prevents the accidental execution of destructive "mutations" (like deletes or writes) during the discovery phase.

Safety Categories

The system defines three primary safety levels:

Level	Description	Criteria
SAFE	Read-only operations.	Matches patterns like get_, list_, search_, read_.
DANGEROUS	Mutations or destructive actions.	Matches patterns like delete_, update_, drop_, execute_.
UNKNOWN	Ambiguous tools.	Default state if no keywords or patterns match.

Sources: src/runtime/generate_test_params.py:27-33, tests/unit/test_generate_test_params.py:21-45

Classification Logic

The classify_tool function prioritizes dangerous keywords found in tool descriptions over name-based regex patterns. For example, a tool named get_and_delete would be classified as DANGEROUS if the description mentions "delete".
Sources: src/runtime/generate_test_params.py:76-115, tests/unit/test_generate_test_params.py:61-65

Test Parameter Generation

To discover output schemas, the system must successfully call a tool. This requires valid input parameters that satisfy the tool's inputSchema. Continuous Claude uses LLMs to synthesize these parameters.

Generation Providers

The system supports three different mechanisms for generating test parameters:

1. Claude API: Directly calls Anthropic's API (defaulting to claude-3-5-haiku).
2. Claude Code CLI: Executes the local claude command.
3. Copilot CLI: Executes the GitHub Copilot CLI.

Schema Inference and Wrapper Generation

Once safe tools are executed with generated parameters, the system captures the response and transforms it into Pydantic models.

Discovered Types

The system writes these models to servers/{server}/discovered_types.py. Key characteristics include:

• Defensive Coding: Every field in the inferred model is marked as Optional with a default of None.
• Type Mapping: Primitives, lists, and nested dictionaries are mapped to corresponding Python/Pydantic types.
• Fallback Handling: If an API returns a simple string instead of a dictionary, the system generates a wrapper model with a value field.

"""
Example of generated discovered_types.py
Generated for a hypothetical 'weather' server.
"""
from pydantic import BaseModel
from typing import Any, Dict, List, Optional

class GetWeatherResult(BaseModel):
    temperature: Optional[float] = None
    condition: Optional[str] = None
    forecast: Optional[List[str]] = None

Sources: src/runtime/discover_schemas.py:114-142, tests/unit/test_discover_schemas_mock.py:21-35

Automated Discovery Workflow

Users typically interact with the discovery system using the following commands:

Command	Action
uv run mcp-generate-discovery	Generates discovery_config.json by scanning servers and classifying tools.
uv run mcp-discover	Executes the safe tools listed in the config and generates Python types.
uv run mcp-generate	Regenerates the primary Python wrappers for tool execution.

Sources: CLAUDE.md:65-70, install-global.sh:425-430

Global Installation and Paths

The discovery and generation tools are installed as a global Python toolset.

• Commands: mcp-exec, mcp-generate, mcp-discover.
• Output Directory: Wrappers and types are stored in the local servers/ directory or the global ~/.claude/servers/ directory depending on execution context.
• Harness Integration: The src/runtime/harness.py handles the execution environment for these scripts, ensuring proper pathing and async initialization.

Sources: install-global.sh:425-435, CLAUDE.md:85-100

Conclusion

The Schema Discovery & Auto-generation system provides a robust framework for consuming MCP tools with high type fidelity. By combining automated safety classification with LLM-powered parameter generation, it allows developers to interact with any MCP server as if it were a native, typed Python library, significantly reducing the complexity of multi-tool orchestration and the associated token costs.