241 lines
6.9 KiB
Markdown
241 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```cpp
|
|
// 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
|
|
|
|
```cpp
|
|
// 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
|
|
|
|
```cpp
|
|
// 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
|
|
|
|
```cpp
|
|
// 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:
|
|
```bash
|
|
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:
|
|
```cpp
|
|
// 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. |