Skip to content

README.md

Latest commit

 

History

History
282 lines (206 loc) · 8.57 KB

README.md

File metadata and controls

282 lines (206 loc) · 8.57 KB

MCP Protocol Framework

Model Context Protocol (MCP) is an open protocol that provides a standardized way for AI models and agents to interact with various resources, tools, and services. This framework implements the core functionality of the MCP protocol, conforming to the 2025-03-26 basic protocol specification.

Core Features

  • JSON-RPC 2.0 Communication: Request/response communication based on JSON-RPC 2.0 standard
  • Resource Abstraction: Standard interfaces for resources such as files, APIs, etc.
  • Tool Registration: Register and call tools with structured parameters
  • Extensible Architecture: Easy to extend with new resource types and tools
  • Multi-Transport Support: Supports HTTP and standard input/output (stdio) communication methods

How to Build

Example of building with CMake:

cmake -B build
cmake --build build --config Release

Build with tests:

git submodule update --init --recursive # Get GoogleTest

cmake -B build -DMCP_BUILD_TESTS=ON
cmake --build build --config Release

Build with SSL support:

git submodule update --init --recursive # Get GoogleTest

cmake -B build -DMCP_SSL=ON
cmake --build build --config Release

Adopters

Here are some open-source projects that are using this repository.
If you're using it too, feel free to submit a PR to be featured here!

  • humanus.cpp: Lightweight C++ LLM agent framework
  • ...waiting for your contribution...

Components

The MCP C++ library includes the following main components:

Core Components

Client Interface (mcp_client.h)

Defines the abstract interface for MCP clients, which all concrete client implementations inherit from.

SSE Client (mcp_sse_client.h, mcp_sse_client.cpp)

Client implementation that communicates with MCP servers using HTTP and Server-Sent Events (SSE).

Stdio Client (mcp_stdio_client.h, mcp_stdio_client.cpp)

Client implementation that communicates with MCP servers using standard input/output, capable of launching subprocesses and communicating with them.

Message Processing (mcp_message.h, mcp_message.cpp)

Handles serialization and deserialization of JSON-RPC messages.

Tool Management (mcp_tool.h, mcp_tool.cpp)

Manages and invokes MCP tools.

Resource Management (mcp_resource.h, mcp_resource.cpp)

Manages MCP resources.

Server (mcp_server.h, mcp_server.cpp)

Implements MCP server functionality.

Examples

HTTP Server Example (examples/server_example.cpp)

Example MCP server implementation with custom tools:

  • Time tool: Get the current time
  • Calculator tool: Perform mathematical operations
  • Echo tool: Echo input with optional transformations (to uppercase, reverse)
  • Greeting tool: Returns Hello, + input name + !, defaults to Hello, World!

HTTP Client Example (examples/client_example.cpp)

Example MCP client connecting to a server:

  • Get server information
  • List available tools
  • Call tools with parameters
  • Access resources

Stdio Client Example (examples/stdio_client_example.cpp)

Demonstrates how to use the stdio client to communicate with a local server:

  • Launch a local server process
  • Access filesystem resources
  • Call server tools

Agent Example (examples/agent_example.cpp)

Option Description
--base-url LLM base URL (e.g. https://openrouter.ai)
--endpoint LLM endpoint (default to /v1/chat/completions/)
--api-key LLM API key
--model Model name (e.g. gpt-3.5-turbo)
--system-prompt System prompt
--max-tokens Maximum number of tokens to generate (default to 2048)
--temperature Temperature (default to 0.0)
--max-steps Maximum steps calling tools without user input (default to 3)

Example usage:

./build/examples/agent_example --base-url <base_url> --endpoint <endpoint> --api-key <api_key> --model <model_name>

Note: Remember to compile with -DMCP_SSL=ON when connecting to an https base URL.

How to Use

Setting up an HTTP Server

// Create and configure the server
mcp::server::configuration srv_conf;
srv_conf.host = "localhost";
srv_conf.port = 8888;

mcp::server server(srv_conf);
server.set_server_info("MCP Example Server", "0.1.0"); // Name and version

// Register tools
mcp::json hello_handler(const mcp::json& params, const std::string /* session_id */) {
    std::string name = params.contains("name") ? params["name"].get<std::string>() : "World";

    // Server will catch exceptions and return error contents
    // For example, you can use `throw mcp::mcp_exception(mcp::error_code::invalid_params, "Invalid name");` to report an error

    // Content should be a JSON array, see: https://modelcontextprotocol.io/specification/2024-11-05/server/tools#tool-result
    return {
        {
            {"type", "text"},
            {"text", "Hello, " + name + "!"}
        }
    };
}

mcp::tool hello_tool = mcp::tool_builder("hello")
        .with_description("Say hello")
        .with_string_param("name", "Name to say hello to", "World")
        .build();

server.register_tool(hello_tool, hello_handler);

// Register resources
auto file_resource = std::make_shared<mcp::file_resource>("<file_path>");
server.register_resource("file://<file_path>", file_resource);

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

Creating an HTTP Client

// Connect to the server
mcp::sse_client client("http://localhost:8080");

// Initialize the connection
client.initialize("My Client", "1.0.0");

// Call a tool
mcp::json params = {
    {"name", "Client"}
};

mcp::json result = client.call_tool("hello", params);

Using the SSE Client

The SSE client uses HTTP and Server-Sent Events (SSE) to communicate with MCP servers. This is a communication method based on Web standards, suitable for communicating with servers that support HTTP/SSE.

#include "mcp_sse_client.h"

// Create a client, specifying the server address and port
mcp::sse_client client("http://localhost:8080");

// Set an authentication token (if needed)
client.set_auth_token("your_auth_token");

// Set custom request headers (if needed)
client.set_header("X-Custom-Header", "value");

// Initialize the client
if (!client.initialize("My Client", "1.0.0")) {
    // Handle initialization failure
}

// Call a tool
json result = client.call_tool("tool_name", {
    {"param1", "value1"},
    {"param2", 42}
});

Using the Stdio Client

The Stdio client can communicate with any MCP server that supports stdio transport, such as:

  • @modelcontextprotocol/server-everything - Example server
  • @modelcontextprotocol/server-filesystem - Filesystem server
  • Other MCP servers that support stdio transport
#include "mcp_stdio_client.h"

// Create a client, specifying the server command
mcp::stdio_client client("npx -y @modelcontextprotocol/server-everything");
// mcp::stdio_client client("npx -y @modelcontextprotocol/server-filesystem /path/to/directory");

// Initialize the client
if (!client.initialize("My Client", "1.0.0")) {
    // Handle initialization failure
}

// Access resources
json resources = client.list_resources();
json content = client.read_resource("resource://uri");

// Call a tool
json result = client.call_tool("tool_name", {
    {"param1", "value1"},
    {"param2", "value2"}
});

Using TLS clients and servers

Creating test certificates on Linux

  1. Generate Certificate Authority (CA) private key 
    openssl genrsa -out ca.key.pem 2048
  2. Generate CA certificate 
    openssl req -x509 -new -nodes -key ca.key.pem -sha256 -days 1 -out ca.cert.pem -subj "/CN=Test CA"
  3. Generate server private key 
    openssl genrsa -out server.key.pem 2048
  4. Generate Certificate Signing Request (CSR) 
    openssl req -new -key server.key.pem -out server.csr.pem -subj "/O=TestServer/OU=Dev/CN=localhost"
  5. Generate server certificate signed by CA 
    openssl x509 -req -in server.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out server.cert.pem -days 1 -sha256

Setting up an HTTPs server

mcp::server::configuration srv_conf;
srv_conf.host = "localhost";
srv_conf.port = 8888;
srv_conf.ssl.server_cert_path = "./server.cert.pem";
srv_conf.ssl.server_private_key_path = "./server.key.pem";

Setting up an SSE client with TLS

 mcp::sse_client client("https://localhost:8888");

License

This framework is provided under the MIT license. For details, please see the LICENSE file.