# Mcpp

> mcpp is a mcp framework for cpp

- **Type:** MCP server
- **Install:** `agentstack add mcp-laplaceliu-mcpp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [laplaceliu](https://agentstack.voostack.com/s/laplaceliu)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [laplaceliu](https://github.com/laplaceliu)
- **Source:** https://github.com/laplaceliu/mcpp

## Install

```sh
agentstack add mcp-laplaceliu-mcpp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCPP - Modern C++ MCP Framework

A Modern C++ implementation of the Model Context Protocol (MCP), designed to be a balanced framework between simplicity and completeness.

## Features

- **100% Header-Only** - No compilation of core library needed, just include and use
- **Full MCP Protocol Support** (version 2025-06-18)
- **Multiple Transport Layers**:
  - **Stdio**: Local process communication via stdin/stdout
  - **HTTP/SSE**: Remote communication with Server-Sent Events
  - **WebSocket**: Bidirectional real-time communication (client & server modes)
- **Server Capabilities**: Tools, Resources, Prompts, Sampling, Elicitation, Logging
- **Client Capabilities**: Full client-side MCP support
- **Enterprise Features**:
  - Middleware/Filter Chain framework
  - Token Bucket Rate Limiting
  - Circuit Breaker pattern
  - Prometheus Metrics export
  - Bearer Token Authentication with RBAC

## Requirements

- C++14 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
- CMake 3.10+
- OpenSSL (libssl-dev on Ubuntu/Debian)
- **Dependencies (managed via CMake FetchContent):**
  - nlohmann/json 3.10.5
  - cpp-httplib 0.15.3
  - libwebsockets 4.3.4
  - GoogleTest 1.14.0

## Installation

### Quick Start

```bash
# Clone the repository
git clone https://github.com/laplaceliu/mcpp.git
cd mcpp

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build (header-only - only examples and tests need compilation)
make -j$(nproc)

# Run tests
ctest --output-on-failure
```

### Dependencies

The project uses CMake FetchContent to download dependencies. The dependency management is in `_deps/CMakeLists.txt`.

**Required system packages:**
- Ubuntu/Debian: `sudo apt-get install libssl-dev`
- macOS: OpenSSL is included (or `brew install openssl` if needed)
- Fedora/RHEL: `sudo dnf install openssl-devel`

### Build Options

| Option | Default | Description |
|--------|---------|-------------|
| `MCPP_BUILD_TESTS` | ON | Build unit tests |
| `MCPP_BUILD_EXAMPLES` | ON | Build example applications |

## Project Structure

```
mcpp/
├── include/mcpp/
│   ├── core/           # Core types and utilities
│   │   ├── json.hpp    # JSON type aliases
│   │   ├── types.hpp   # MCP protocol types
│   │   └── error.hpp   # Error handling
│   ├── protocol/       # JSON-RPC protocol
│   │   ├── message.hpp # Message parsing/serialization
│   │   ├── request.hpp # Request routing
│   │   └── response.hpp
│   ├── transport/      # Transport layers
│   │   ├── itransport.hpp   # ITransport interface
│   │   ├── factory.hpp      # TransportFactory
│   │   ├── transport.hpp   # Backwards compatibility (includes factory.hpp)
│   │   ├── stdio.hpp   # stdio transport
│   │   ├── http.hpp    # HTTP/SSE transport
│   │   └── websocket.hpp # WebSocket transport (libwebsockets)
│   ├── server/         # Server implementation
│   │   ├── server.hpp
│   │   ├── tool.hpp
│   │   ├── resource.hpp
│   │   └── prompt.hpp
│   ├── client/         # Client implementation
│   │   └── client.hpp
│   └── enterprise/    # Enterprise features
│       ├── middleware.hpp
│       ├── ratelimit.hpp
│       ├── circuit.hpp
│       ├── metrics.hpp
│       └── auth.hpp
├── src/               # (Empty - header-only library)
├── tests/             # Unit tests
└── examples/          # Example applications
```

**Note:** This is a **100% Header-Only** library. No source files need to be compiled for the core library. Simply include the headers and link to OpenSSL and libwebsockets.

## Usage

### Creating a Server

```cpp
#include "mcpp/server/server.hpp"
#include 

using namespace mcpp;

// Define a tool handler
CallToolResult echo_tool(const std::string& name, const JsonValue& args) {
    CallToolResult result;
    result.is_error = false;
    std::string input = args.value("message", std::string());
    result.content.push_back(JsonValue::object({
        {"type", "text"},
        {"text", "Echo: " + input}
    }));
    return result;
}

int main() {
    // Create server options
    ServerOptions options;
    options.name = "my-server";
    options.version = "1.0.0";
    options.capabilities.supports_tools = true;
    options.capabilities.supports_resources = true;

    // Create and start server
    Server server(options);

    // Register tools
    server.register_tool(
        "echo",
        "Echo back the input message",
        JsonValue::object({
            {"type", "object"},
            {"properties", JsonValue::object({
                {"message", JsonValue::object({
                    {"type", "string"},
                    {"description", "Message to echo"}
                })}
            })},
            {"required", JsonValue::array({"message"})}
        }),
        echo_tool
    );

    // Start server with stdio transport (default)
    server.start();
    server.wait();

    return 0;
}
```

### Using Different Transports

```cpp
#include "mcpp/transport/transport.hpp"

using namespace mcpp;

// Create transport using factory
auto transport = TransportFactory::create(TransportFactory::Type::Stdio);

// Or by name
auto http_transport = TransportFactory::create("http");
auto ws_transport = TransportFactory::create("websocket");

// Configure WebSocket transport
WebSocketConfig ws_config;
ws_config.host = "localhost";
ws_config.port = 8080;
ws_config.path = "/mcp";
ws_config.is_server = false;  // Client mode
ws_config.use_ssl = false;

WebSocketTransport ws(ws_config);
ws.on_message([](const std::string& msg) {
    // Handle incoming message
});
ws.start();
```

### Creating a Client

```cpp
#include "mcpp/client/client.hpp"
#include 

using namespace mcpp;

int main() {
    ClientOptions options;
    options.name = "my-client";
    options.version = "1.0.0";
    options.transport_type = TransportFactory::Type::Stdio;

    auto client = std::make_shared(options);

    // Handle sampling requests from server
    client->on_sampling_request([](const SamplingParams& params) {
        SamplingResult result;
        result.is_error = false;
        result.content = /* ... */;
        return result;
    });

    // Handle elicitation requests
    client->on_elicitation_request([](const ElicitationParams& params) {
        ElicitationResult result;
        result.is_error = false;
        result.content = /* ... */;
        return result;
    });

    client->start();
    client->wait();
    return 0;
}
```

### Using Enterprise Features

#### Rate Limiting

```cpp
#include "mcpp/enterprise/ratelimit.hpp"

using namespace mcpp::enterprise;

// Create rate limiter with custom config
RateLimiter::Config config;
config.tokens_per_second = 100;
config.max_tokens = 100;
config.tokens_per_request = 1;

RateLimiter limiter(config);

// Check if request is allowed
auto result = limiter.check("user_id");
if (result.allowed) {
    // Process request
} else {
    // Rate limited - retry_after_ms until more tokens
}
```

#### Circuit Breaker

```cpp
#include "mcpp/enterprise/circuit.hpp"

using namespace mcpp::enterprise;

CircuitBreaker breaker("my-service", CircuitBreaker::Config());

// Execute with circuit breaker protection
auto result = execute_with_circuit(
    breaker,
    []() { return call_service(); },      // Primary function
    []() { return fallback_value(); }      // Fallback when circuit open
);
```

#### Prometheus Metrics

```cpp
#include "mcpp/enterprise/metrics.hpp"

using namespace mcpp::enterprise;

// Register metrics
auto& registry = MetricsRegistry::instance();
registry.counter("requests_total", "Total requests")->increment();
registry.gauge("active_connections", "Active connections")->set(42);
registry.histogram("request_duration", "Request duration")->observe(0.123);

// Export metrics in Prometheus format
std::string output = registry.export_prometheus();
```

#### Authentication & RBAC

```cpp
#include "mcpp/enterprise/auth.hpp"

using namespace mcpp::enterprise;

// Create authorizer with RBAC
Authorizer authorizer;

// Add roles and permissions
authorizer.add_permission("admin", "tools:*");
authorizer.add_permission("user", "tools:read");
authorizer.add_role("user1", "admin");

// Check permissions
if (authorizer.has_permission("user1", "tools:read")) {
    // Access granted
}

// Generate and validate tokens
Token token = authorizer.generate_token("user1", std::chrono::hours(24));
if (authorizer.validate_token(token)) {
    // Token valid
}
```

## Testing

```bash
# Run all tests
ctest --output-on-failure

# Or run tests directly
./build/bin/tests

# Run specific test suite
./build/bin/tests --gtest_filter="RateLimiterTest.*"

# Run transport tests only
./build/bin/tests --gtest_filter="*Transport*"
```

**Test Coverage:** 109 tests across 14 test suites covering:
- JSON parsing and serialization
- JSON-RPC message protocol
- Server primitives (Tools, Resources, Prompts)
- Transport layers (Stdio, HTTP/SSE, WebSocket)
- Enterprise features (Rate limiting, Circuit breaker, Metrics)

## API Reference

### Server

- `Server::Server(ServerOptions)` - Create server with options
- `Server::start()` - Start the server
- `Server::stop()` - Stop the server
- `Server::wait()` - Wait for shutdown
- `Server::register_tool(...)` - Register a tool
- `Server::register_resource(...)` - Register a resource
- `Server::register_prompt(...)` - Register a prompt

### Client

- `Client::Client(ClientOptions)` - Create client with options
- `Client::start()` - Start the client
- `Client::stop()` - Stop the client
- `Client::on_sampling_request(...)` - Set sampling handler
- `Client::on_elicitation_request(...)` - Set elicitation handler
- `Client::on_progress_notification(...)` - Set progress handler
- `Client::logging_message(...)` - Send logging message

### Transport

- `TransportFactory::create(Type)` - Create transport by type (Stdio/Http/WebSocket)
- `TransportFactory::create(string)` - Create transport by name ("stdio"/"http"/"websocket")
- `ITransport::start()` - Start transport
- `ITransport::stop()` - Stop transport
- `ITransport::send(message)` - Send message
- `ITransport::on_message(handler)` - Set message handler
- `ITransport::on_error(handler)` - Set error handler
- `WebSocketTransport::WebSocketTransport(Config)` - Create with config
- `WebSocketTransport::set_url(url)` - Set WebSocket URL
- `WebSocketFramer::frame(message)` - Frame WebSocket message (RFC 6455)
- `StdioFramer::frame/decode` - Frame/decode stdio messages
- `HttpFramer::frame/frame_sse` - Frame HTTP messages/SSE events

### Enterprise

- `RateLimiter::check(key)` - Check rate limit for key
- `CircuitBreaker::allow_request()` - Check if request allowed
- `CircuitBreaker::record_success()` - Record successful call
- `CircuitBreaker::record_failure()` - Record failed call
- `MetricsRegistry::counter(name, help)` - Get/create counter
- `MetricsRegistry::gauge(name, help)` - Get/create gauge
- `MetricsRegistry::histogram(name, help)` - Get/create histogram
- `Authorizer::has_permission(role, permission)` - Check permission
- `Authorizer::generate_token(user_id, duration)` - Generate token

## Documentation

### Building API Documentation

This project uses Doxygen for API documentation. To generate the documentation:

```bash
# Install Doxygen (if not already installed)
# Ubuntu/Debian:
sudo apt-get install doxygen

# macOS:
brew install doxygen

# Fedora/RHEL:
sudo dnf install doxygen

# Generate documentation (run from project root)
doxygen docs/Doxyfile.in

# View the documentation
# Open docs/doxygen/html/index.html in a browser
open docs/doxygen/html/index.html  # macOS
xdg-open docs/doxygen/html/index.html  # Linux
```

The generated documentation will be in `docs/doxygen/html/` directory:
- `index.html` - Main documentation page
- `classes.html` - Class hierarchy
- `files.html` - File list

## License

MIT License - see LICENSE file for details

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [laplaceliu](https://github.com/laplaceliu)
- **Source:** [laplaceliu/mcpp](https://github.com/laplaceliu/mcpp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-laplaceliu-mcpp
- Seller: https://agentstack.voostack.com/s/laplaceliu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.