cpp-mcp/README.md

MCP Protocol Framework

The Model Context Protocol (MCP) provides a standardized way for AI models and agents to interact with various resources, tools, and services. This framework implements the core functionality of MCP in C++ with support for agent workflows.

Core Features

• HTTP-based Communication: RESTful API for client-server interaction
• Resource Abstraction: Standard interface for files, directories, APIs, and more
• Tool Registry: Register and invoke tools with structured parameters
• Agent Framework: Create agents that can process requests and use tools
• Workflow System: Define and execute sequences of tool calls
• Extensible Architecture: Easy to extend with new resource types and tools

Components

Core Protocol (mcp_protocol.h, mcp_protocol.cpp)

Defines the fundamental structures and types for MCP:

• Request/response handling
• Error codes
• Resource interfaces
• Tool definitions

Server (mcp_server.h, mcp_server.cpp)

Implements an HTTP server that exposes MCP resources and tools:

• Register resources at specific paths
• Register tools with handlers
• Process incoming HTTP requests
• Route requests to appropriate resources

Client (mcp_client.h, mcp_client.cpp)

Implements a client for connecting to MCP servers:

• Connect to servers
• Discover available resources and tools
• Make requests to resources
• Call tools with parameters

Resources (mcp_resource.h)

Provides base implementations for common resource types:

• File resources
• Directory resources
• API resources
• Image resources

Tools (mcp_tools.h, mcp_tools.cpp)

Provides tool-related functionality and agent workflow support:

• Tool registry
• Tool builder (fluent API)
• Workflow definition and execution
• Agent base class

Workflow (mcp_workflow_resource.h, mcp_workflow_resource.cpp, mcp_agent_resource.cpp)

Implements resources for workflow and agent management:

• Create and manage workflows
• Execute workflows
• Register and manage agents
• Process requests with agents

Examples

Custom Agents (examples/custom_agent.h, examples/custom_agent.cpp)

Examples of custom agent implementations:

• Echo agent: Simple agent that echoes back input with optional processing
• Workflow agent: An agent that executes pre-defined workflows
• Chain agent: An agent that chains multiple tools together

Server Example (examples/server_example.cpp)

Example of an MCP server implementation with custom tools:

• Time tool: Get the current time
• Calculator tool: Perform mathematical operations
• Text processor tool: Process and analyze text
• Custom workflow and agent registration

Client Example (examples/client_example.cpp)

Example of an MCP client connecting to a server:

• Get server information
• List available tools
• Call tools with parameters
• List and execute workflows
• Interact with agents

Host Example (examples/host_example.cpp)

Example of a host that combines server and client functionality:

• Register local tools and resources
• Connect to other MCP servers
• Create workflows that combine local and remote tools
• Manage connections to other servers

How to Use

Setting Up a Server

// Create and configure the server
mcp::server server("localhost", 8080);
server.set_name("MCP Example Server");

// Register a tool
mcp::tool time_tool = mcp::tool_builder("get_time")
    .with_description("Get the current time")
    .build();

server.register_tool(time_tool, [](const mcp::json& params) {
    // Tool implementation
    return mcp::json::object();
});

// Register a resource
auto file_resource = std::make_shared<mcp::file_resource>("./files");
server.register_resource("/files", file_resource);

// Start the server
server.start(true);  // Blocking mode

Creating a Client

// Connect to a server
mcp::client client("localhost", 8080);

// Get server information
mcp::json server_info = client.get_server_info();

// Call a tool
mcp::json params = {
    {"key", "value"}
};
mcp::json result = client.call_tool("tool_name", params);

Defining a Workflow

// Create a workflow
mcp::workflow workflow("example_workflow", "Example workflow description");

// Add steps to the workflow
workflow.add_tool_call("get_time");
workflow.add_tool_call("text_processor", {
    {"text", "Example text"},
    {"to_uppercase", true}
});

// Execute the workflow
mcp::json context = workflow.execute();

Creating a Custom Agent

// Define a custom agent
class my_agent : public mcp::agent {
public:
    my_agent() : mcp::agent("MyAgent") {}
    
    void initialize(const mcp::json& config) override {
        // Initialize from config
    }
    
    mcp::json process(const mcp::json& input) override {
        // Process input
        return mcp::json::object();
    }
};

// Register the agent with a server
auto agent_ptr = std::make_shared<my_agent>();
agent_ptr->initialize({});

auto agent_resource = std::make_shared<mcp::agent_resource>();
agent_resource->register_agent(agent_ptr);
server.register_resource("/agents", agent_resource);

Building the Framework

The framework depends on the following libraries:

• httplib.h - HTTP server and client
• json.hpp - JSON parsing and generation
• base64.hpp - Base64 encoding/decoding
• stb_image.h - Image loading (for image resources)

All dependencies are included in the repository.

To build the examples:

g++ -std=c++17 examples/server_example.cpp mcp_protocol.cpp mcp_server.cpp mcp_tools.cpp mcp_workflow_resource.cpp mcp_agent_resource.cpp -pthread -o server_example
g++ -std=c++17 examples/client_example.cpp mcp_protocol.cpp mcp_client.cpp -pthread -o client_example
g++ -std=c++17 examples/host_example.cpp mcp_protocol.cpp mcp_server.cpp mcp_client.cpp mcp_tools.cpp mcp_workflow_resource.cpp mcp_agent_resource.cpp -pthread -o host_example

Extending the Framework

Adding New Resource Types

1. Define a new class that inherits from mcp::resource
2. Implement the required methods:
   • resource_type type() const
   • json metadata() const
   • response handle_request(const request& req)
   • json schema() const (optional)

Creating Custom Tools

Use the tool builder API:

// Create a tool definition
mcp::tool my_tool = mcp::tool_builder("my_tool")
    .with_description("My custom tool")
    .with_string_param("input", "Input parameter", true)
    .with_number_param("count", "Count parameter", false)
    .build();

// Register the tool handler
server.register_tool(my_tool, [](const mcp::json& params) {
    // Tool implementation
    return mcp::json::object();
});

Implementing Custom Agents

1. Define a new class that inherits from mcp::agent
2. Implement the required methods:
   • void initialize(const mcp::json& config)
   • mcp::json process(const mcp::json& input)
3. Register the agent with an agent resource

License

This framework is provided under the MIT License. See the LICENSE file for details.