Module tool_generator 

OpenAPI to MCP Tool Generator with Reference Metadata Enhancement

This module provides comprehensive tooling for converting OpenAPI 3.1 specifications into Model Context Protocol (MCP) tools with sophisticated reference metadata handling. The implementation follows OpenAPI 3.1 semantics to ensure contextual information takes precedence over generic schema documentation.

Reference Metadata Enhancement Strategy

Core Philosophy

The OpenAPI 3.1 specification introduces reference metadata fields (summary and description) that can be attached to $ref objects. These fields serve a fundamentally different purpose than schema-level metadata:

• Reference Metadata: Contextual, usage-specific information about how a schema is used in a particular location within the API specification
• Schema Metadata: General, reusable documentation about the schema definition itself

This distinction is crucial for generating meaningful MCP tools that provide contextual information to AI assistants rather than generic schema documentation.

Implementation Architecture

The enhancement strategy is implemented through several coordinated components:

1. ReferenceMetadata Struct

Central data structure that encapsulates OpenAPI 3.1 reference metadata fields and provides the core precedence logic through helper methods (best_description(), summary()).

2. Precedence Hierarchy Implementation

All description enhancement follows the strict precedence hierarchy:

1. Reference description (highest) - Detailed contextual information
2. Reference summary (medium) - Brief contextual information
3. Schema description (lower) - General schema documentation
4. Generated fallback (lowest) - Auto-generated descriptive text

3. Context-Aware Enhancement Methods

• merge_with_description(): General-purpose description merging with optional formatting
• enhance_parameter_description(): Parameter-specific enhancement with name integration
• Various schema conversion methods that apply reference metadata throughout tool generation

Usage Throughout Tool Generation Pipeline

The reference metadata enhancement strategy is applied systematically:

Parameter Processing

• Parameter schemas are enhanced with contextual information from parameter references
• Parameter descriptions include contextual usage information rather than generic field docs
• Special formatting ensures parameter names are clearly associated with contextual descriptions

Request Body Processing

• Request body schemas are enriched with operation-specific documentation
• Content type handling preserves reference metadata through schema conversion
• Complex nested schemas maintain reference context through recursive processing

Response Processing

• Response schemas are augmented with endpoint-specific information
• Unified response structures include contextual descriptions in the response body schemas
• Error handling maintains reference context for comprehensive tool documentation

Tool Metadata Generation

• Tool names, descriptions, and parameter schemas all benefit from reference metadata
• Operation-level documentation is combined with reference-level context for comprehensive tool docs
• Output schemas preserve contextual information for structured MCP responses

Quality Assurance

The implementation includes comprehensive safeguards:

• Precedence Consistency: All enhancement methods follow identical precedence rules
• Backward Compatibility: Systems without reference metadata continue to work with schema-level docs
• Fallback Robustness: Multiple fallback levels ensure tools always have meaningful documentation
• Context Preservation: Reference metadata is preserved through complex schema transformations

Examples

use rmcp_openapi::tool_generator::{ToolGenerator, ReferenceMetadata};
use oas3::spec::Spec;

// Reference metadata provides contextual information
let ref_metadata = ReferenceMetadata::new(
    Some("Store pet data".to_string()),      // contextual summary
    Some("Pet information for inventory management".to_string()) // contextual description
);

// Enhancement follows precedence hierarchy
let enhanced = ref_metadata.merge_with_description(
    Some("Generic animal schema"), // schema description (lower priority)
    false
);
// Result: "Pet information for inventory management" (reference description wins)

// Parameter enhancement includes contextual formatting
let param_desc = ref_metadata.enhance_parameter_description(
    "petId",
    Some("Database identifier")
);
// Result: "petId: Pet information for inventory management"

This comprehensive approach ensures that MCP tools generated from OpenAPI specifications provide meaningful, contextual information to AI assistants rather than generic schema documentation, significantly improving the quality of human-AI interactions.

Structs

Annotations

Collection of annotations that can be applied to schema objects

ExtractedParameters

Extracted parameters from MCP tool call

QueryParameter

Query parameter with explode information

ReferenceMetadata

Metadata extracted from OpenAPI 3.1 reference objects for MCP tool generation

RequestConfig

Request configuration options

ToolGenerator

Tool generator for creating MCP tools from OpenAPI operations

Enums

Annotation

Annotation types that can be applied to parameters and request bodies

Location

Location type that extends ParameterIn with Body variant