oatpp-mcp

Creates a central Server instance that coordinates all MCP functionality by managing a registry of capabilities (Tools, Resources, Prompts) and event listeners. The Server class acts as the orchestration hub, initializing subsystems and providing methods to register capabilities declaratively before exposing them through communication channels. Uses a listener-based event processing architecture to route incoming LLM requests to appropriate capability handlers.

Introspects existing Oat++ API controllers and endpoints, automatically generating MCP tools from their signatures, parameter schemas, and return types. The API Bridge component extracts endpoint metadata (HTTP method, path, parameters, response types) and wraps them as callable MCP tools with JSON Schema validation. This eliminates manual tool definition for existing REST APIs by leveraging Oat++ reflection capabilities.

Provides mechanisms for handling multiple concurrent LLM requests safely, with thread-safe access to shared capability registries and session state. The system uses synchronization primitives (mutexes, atomic operations) to protect shared data structures when multiple communication channels or threads access capabilities simultaneously. Each request is processed with proper locking to prevent race conditions in tool execution, resource access, and session state updates.

Provides three distinct communication channels for LLM-to-server interaction: STDIO for command-line/local development, Server-Sent Events (SSE) for web-based real-time bidirectional communication, and REST API endpoints for traditional HTTP clients. Each channel implements the same MCP protocol but with different transport mechanics — STDIO uses stdin/stdout, SSE uses HTTP streaming, and REST uses standard HTTP request/response. The Server exposes controller methods for each channel that deserialize incoming messages, route them through the event processing pipeline, and serialize responses back.

Enables developers to define custom callable tools with input schemas, descriptions, and handler functions that LLMs can invoke through MCP. Tools are registered with the Server using a declarative API that specifies the tool name, description, input JSON Schema, and a callback function. When an LLM requests tool execution, the system deserializes the input JSON according to the schema, validates it, invokes the handler function, and returns the result. Supports both synchronous and asynchronous tool execution with error handling and result serialization.

Provides a mechanism for LLMs to read and access application data through Resources — named data providers that expose files, project information, or other structured data. Resources are registered with the Server and return data in a format specified by the resource (text, JSON, structured). When an LLM requests a resource, the system invokes the resource handler, which retrieves the data and returns it in MCP ResourceContents format. Supports both static resources (files) and dynamic resources (computed data, database queries).

Enables developers to define interactive prompts that guide LLM behavior and provide structured conversation templates. Prompts are registered with the Server and contain a name, description, and argument schema that specifies what parameters the prompt accepts. When an LLM requests a prompt, the system returns the prompt definition and arguments, allowing the LLM to understand how to use it. Prompts serve as a way to expose domain-specific conversation patterns and reasoning frameworks to LLMs without requiring tool invocation.

Implements a Listener-based event processing architecture that routes incoming MCP requests (from any communication channel) to appropriate capability handlers. The Listener class subscribes to events from the Server and processes them in sequence, deserializing JSON-RPC messages, validating them against the MCP protocol, and dispatching them to Tool, Resource, or Prompt handlers. The event flow ensures proper handling of all request types (initialize, call_tool, read_resource, get_prompt) with error handling and response serialization.

Automatically generates JSON Schema definitions for tool input parameters and validates incoming tool invocation requests against those schemas. The system uses Oat++ DTO reflection to extract parameter types and constraints, generating JSON Schema that describes what inputs a tool accepts. When an LLM invokes a tool, the incoming JSON is validated against the schema before the handler function is called, ensuring type safety and catching malformed requests early.

Manages LLM client sessions and maintains context across multiple requests within a session. The system tracks active sessions, associates requests with sessions, and provides a mechanism for storing and retrieving session-specific state. Session data can include conversation history, tool execution results, and application-specific context that persists across multiple tool calls. The Server coordinates session lifecycle (creation, updates, termination) and provides handlers with access to current session context.

Implements full compliance with Anthropic's Model Context Protocol specification, including proper JSON-RPC message formatting, protocol version negotiation, and capability advertisement. The system serializes all responses in MCP-compliant format, handles protocol-level errors (invalid requests, unsupported methods), and advertises server capabilities during initialization. Message serialization uses Oat++'s JSON serialization to convert C++ objects to JSON-RPC format, ensuring compatibility with any MCP client.