# 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.