Content
# Tool List
MCP (Model Context Protocol) complete implementation.
MCP protocol complete C++ implementation, including MCP client, MCP server, and RAG-MCP intelligent tool retrieval module.
A sub-project independently extracted from the [agent-communication](../) project.
## Project Structure
```
mcp_standalone/
├── CMakeLists.txt # Root build file
├── README.md
├── common/ # Common components (logging, type definitions)
│ ├── include/agent_rpc/common/
│ │ ├── types.h # General type definitions
│ │ └── logger.h # Logging system interface
│ └── src/
│ └── logger.cpp # Logging implementation
├── mcp_client/ # MCP client library
│ ├── include/agent_rpc/mcp/
│ │ ├── mcp_client.h # MCP client interface (STDIO + SSE)
│ │ ├── mcp_agent_integration.h # AI Agent integration helper class
│ │ └── rag/ # RAG-MCP module
│ │ ├── embedding_service.h # DashScope vectorization service
│ │ ├── embedding_cache.h # LRU vector cache
│ │ ├── vector_index.h # Vector index
│ │ ├── tool_retriever.h # Tool retriever
│ │ └── tool_validator.h # Tool validator
│ └── src/
│ ├── mcp_client.cpp # Client implementation
│ ├── mcp_tool_manager.cpp # Tool manager
│ ├── mcp_agent_integration.cpp # Agent integration
│ └── rag/ # RAG implementation
├── mcp_server/ # MCP server (independent executable)
│ ├── src/
│ │ ├── main.cpp # Server entry
│ │ ├── server/Server.{h,cpp} # Core server
│ │ ├── transport/ # Transport layer
│ │ │ ├── StdioTransport # Standard I/O transport
│ │ │ ├── SseTransport # SSE transport
│ │ │ └── HttpStreamTransport # HTTP stream transport
│ │ ├── interface/ # Interface definitions
│ │ │ ├── ITransport.h # Transport interface
│ │ │ └── PluginAPI.h # Plugin API
│ │ ├── loader/ # Plugin loader
│ │ └── utils/ # Utility classes
│ ├── plugins/ # Built-in plugins
│ │ ├── calculator/ # Calculator
│ │ ├── weather/ # Weather query
│ │ ├── sleep/ # Delay tool
│ │ ├── code-review/ # Code review
│ │ ├── notification/ # Notification
│ │ └── bacio-quote/ # Quote
│ └── test/ # Test scripts
├── examples/ # Example code
│ ├── rag_mcp_example.cpp
│ └── ai_mcp_integration_example.cpp
└── docs/ # Documentation
├── mcp-plugin-development.md
└── rag-mcp-guide.md
```
## Core Components
### 1. MCP Client (`mcp_client`)
MCP client supporting two transport modes:
- **STDIO mode**: Communicates with local MCP Server process through standard input/output
- **SSE mode**: Communicates with remote MCP Server through HTTP Server-Sent Events
Main classes:
- `MCPClient` - MCP client (JSON-RPC protocol)
- `MCPToolManager` - Tool manager
- `MCPServiceIntegrator` - Service integrator
- `MCPAgentIntegration` - AI Agent simplified integration interface
### 2. RAG-MCP Module
Intelligent tool selection based on retrieval-augmented generation:
- `EmbeddingService` - Aliyun DashScope text vectorization
- `EmbeddingCache` - LRU cache, reducing API calls
- `VectorIndex` - Vector index, cosine similarity search
- `ToolRetriever` - Tool retriever, integrating above components
- `ToolValidator` - Optional tool validator
### 3. MCP Server (`mcp_server`)
Complete MCP server implementation (MIT License, by Giuseppe Mastrangelo):
- Plugin architecture, supporting dynamic loading of `.so` plugins
- Three transport modes: STDIO / SSE / HTTP Stream
- Six built-in example plugins
- Cross-platform support (Linux / macOS / Windows)
## Dependencies
| Dependency | Purpose | Module |
|------|------|------|
| C++20 compiler | Compilation | All |
| CMake >= 3.20 | Build | All |
| libcurl | HTTP/SSE client | mcp_client |
| jsoncpp | JSON parsing | mcp_client |
| nlohmann/json | JSON (header-only, built-in) | mcp_server, mcp_client(RAG) |
| Threads | Multithreading | All |
## Build
```bash
mkdir build && cd build
cmake ..
make -j$(nproc)
```
### Build MCP Server Only
```bash
cd mcp_server
mkdir build && cd build
cmake ..
make -j$(nproc)
```
### Build Options
```bash
# Do not build examples
cmake -DBUILD_MCP_EXAMPLES=OFF ..
# Debug mode
cmake -DCMAKE_BUILD_TYPE=Debug ..
```
## Quick Start
### Start MCP Server
```bash
# STDIO mode (default)
./build/mcp_server/mcp_server -p ./build/mcp_server/plugins
# SSE mode
./build/mcp_server/mcp_server -s -p ./build/mcp_server/plugins
```
### Use MCP Client
```cpp
#include "agent_rpc/mcp/mcp_client.h"
using namespace agent_rpc::mcp;
// Connect in STDIO mode
MCPClient client;
client.connect("/path/to/mcp_server", {"--plugins", "./plugins"});
// List tools
auto tools = client.listTools();
for (const auto& tool : tools) {
std::cout << tool.name << ": " << tool.description << std::endl;
}
// Call tool
auto response = client.callTool("calculator", R"({"expression": "2+3"})");
std::cout << response.result << std::endl;
client.disconnect();
```
### Use RAG-MCP Intelligent Tool Retrieval
```cpp
#include "agent_rpc/mcp/mcp_agent_integration.h"
using namespace agent_rpc::mcp;
MCPAgentConfig config;
config.enable_mcp = true;
config.mcp_server_path = "/path/to/mcp_server";
config.rag_config.enabled = true;
config.rag_config.api_key = std::getenv("DASHSCOPE_API_KEY");
MCPAgentIntegration mcp;
mcp.initialize(config);
// Retrieve most relevant tools intelligently
auto tools = mcp.getRelevantTools("计算 123 + 456");
// Get LLM function call format
std::string json = mcp.getRelevantToolsAsJson("查询天气");
```
### Test MCP Server
Unified entry script, supporting two test modes:
```bash
./test_all.sh
```
Choose mode:
- **Mode 1 — AI Integration Test (Recommended)**: Use Aliyun DashScope AI model, test complete Agent tool call chain
- **Mode 2 — Basic Function Test**: No API Key required, only verify MCP Server protocol and plugins
#### AI Integration Test
Use Aliyun DashScope large model as AI Agent, call tools through MCP protocol, verify complete chain:
```
User query → Embedding vectorization → RAG similarity retrieval → Filter relevant tools → LLM (tool selection) → MCP Server (tool execution) → LLM (generate response)
```
**Prerequisites**:
- Aliyun DashScope API Key ([application address](https://dashscope.console.aliyun.com/))
- Python 3.6+ (no extra dependencies)
```bash
# Interactive run, input API Key in terminal
./test_all.sh
# Choose 1
# Or through environment variable
DASHSCOPE_API_KEY="sk-xxx" python3 test_ai_mcp.py
# Specify model
DASHSCOPE_API_KEY="sk-xxx" DASHSCOPE_MODEL="qwen-turbo" python3 test_ai_mcp.py
```
Test coverage:
| Step | Test content |
|------|----------|
| MCP initialization | Start server, establish STDIO connection |
| Tool discovery | Get all plugin-registered tool lists |
| RAG index construction | Batch Embedding vectorization of all tools, establish vector index |
| RAG + AI interactive call | User query → Vector similarity screening tools → Only relevant tools sent to LLM → MCP execution → Return result |
| Basic tool verification | Directly call sleep, calculator, error handling |
#### Basic Function Test
No API Key required, directly verify MCP Server protocol correctness:
```bash
./test_all.sh
# Choose 2
```
Coverage: initialize, ping, tools/list, calculator, sleep, error handling.
#### Manual Test
```bash
# Send JSON-RPC request through pipe
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":"1"}' \
| ./build/mcp_server/mcp_server -p ./build/mcp_server/plugins -l ./build/test_logs
```
#### Python MCP Client Test
```bash
cd mcp_server/test
pip install -r requirements.txt
python3 test-client-stdio.py configuration-stdio-linux.json
```
## Develop Custom Plugins
See [docs/mcp-plugin-development.md](docs/mcp-plugin-development.md).
## RAG-MCP Detailed Guide
See [docs/rag-mcp-guide.md](docs/rag-mcp-guide.md).
## Protocol Version
- MCP Client: JSON-RPC 2.0
- MCP Server: v0.7.0
## License
MCP Server part based on MIT License (Copyright (C) 2025 Giuseppe Mastrangelo).
The rest follows the original project license.
