# mcp扩展平台

**Repository Path**: chen_dl/mcp-extension-platform

## Basic Information

- **Project Name**: mcp扩展平台
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Extension Platform

一个基于 C++20 的 MCP（Model Context Protocol）可扩展服务器，支持 C++ 原生插件和 Python 插件，为 Claude Code 等 MCP 客户端提供丰富的工具能力。

## 功能特性

- **双语言插件系统**：同时支持 C++ 原生插件（`.so`）和 Python 插件（`.py`），统一加载
- **多传输协议**：支持 Stdio（标准输入输出）、SSE（Server-Sent Events）、HTTP Stream 三种传输方式
- **RAG 语义搜索**：基于向量相似度的智能工具检索，根据用户意图自动匹配合适的工具
- **丰富的内置工具**：涵盖数学计算、时间转换、天气查询、SQL 查询、系统监控、翻译、占卜等
- **JSON-RPC 2.0**：完整实现 MCP 协议，支持工具调用、资源管理、提示词、通知等全部原语

## 环境要求

| 依赖 | 版本 | 用途 |
|------|------|------|
| CMake | ≥ 3.20 | 构建系统 |
| GCC / Clang | 支持 C++20 | 编译器 |
| libcurl | — | RAG 模块的 HTTP 请求 |
| Python 3 | ≥ 3.8 | Python 插件运行时 |
| Linux | — | 当前仅支持 Linux |

## 快速开始

### 1. 构建

```bash
# 配置（在仓库根目录执行）
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_BUILD_TYPE=Debug

# 编译
cmake --build build -j$(nproc)
```

构建产物：
- `build/mcp_server/mcp_server` — 服务器主程序
- `mcp_server/plugins/native/libweather.so` — 原生天气插件
- `mcp_server/plugins/native/libshell.so` — 原生 Shell 执行插件
- `build/compile_commands.json` — clangd 代码补全配置

### 2. 运行

```bash
# 加载所有插件，通过 Stdio 模式运行
PYTHONPATH=mcp_server/plugins/python ./build/mcp_server/mcp_server \
    -p mcp_server/plugins --python-path /usr/bin/python3

# SSE 模式（HTTP，端口 8080）
./build/mcp_server/mcp_server -s -p mcp_server/plugins --python-path /usr/bin/python3

# 查看完整帮助
./build/mcp_server/mcp_server --help
```

### 3. 命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-h`, `--help` | — | 显示帮助信息 |
| `-n`, `--name` | `mcp-server` | 服务器名称 |
| `-p`, `--plugins` | `./plugins` | 插件目录（递归扫描 `.so` 和 `.py`） |
| `-l`, `--logs` | `./logs` | 日志目录（启动时自动创建） |
| `-c`, `--config` | `conf/conf.ini` | RAG 配置文件路径（INI 格式） |
| `-v`, `--verbose` | off | 启用详细日志 |
| `-s`, `--sse` | off | 使用 SSE 传输 |
| `-t`, `--http-stream` | off | 使用 HTTP Stream 传输 |
| `--python-path` | `python3` | Python 解释器路径 |

## 配置 Claude Code

在项目根目录的 `.mcp.json` 中配置 MCP 服务器连接：

```json
{
  "mcpServers": {
    "mcp-extension": {
      "command": "/path/to/build/mcp_server/mcp_server",
      "args": [
        "-p", "/path/to/mcp_server/plugins",
        "-c", "/path/to/conf/conf.ini",
        "--python-path", "/usr/bin/python3",
        "-l", "/path/to/logs"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp_server/plugins/python"
      }
    }
  }
}
```

> ⚠️ **重要**：`.mcp.json` 中所有路径必须使用**绝对路径**。MCP 服务器由 Claude Code 在未知工作目录下启动，相对路径（如 `conf/conf.ini`）会导致配置文件、插件、日志等找不到。

配置后 Claude Code 中可用的工具 ID 格式为 `mcp__mcp-extension__<工具名>`，例如：
- `mcp__mcp-extension__calculate` — 数学计算
- `mcp__mcp-extension__get_weather` — 天气查询
- `mcp__mcp-extension__translate` — 翻译
- `mcp__mcp-extension__xiaoliuren_divination` — 小六壬占卜

## 项目架构

```
                    ┌─────────────────┐
                    │   客户端         │
                    │  (Claude Code)  │
                    └────────┬────────┘
                             │ JSON-RPC (stdio / HTTP SSE)
                    ┌────────▼────────┐
                    │   Transport     │  ◄── 传输抽象层
                    │ Stdio / SSE /   │
                    │ HttpStream      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │    Server       │  ◄── JSON-RPC 2.0 核心路由
                    │  ToolsListCmd   │     初始化 / ping / tools/list / tools/call ...
                    │  ToolsCallCmd   │
                    │  ToolsSearchCmd │  ◄── RAG 语义搜索
                    └──┬──────────┬───┘
                       │          │
          ┌────────────▼──┐  ┌───▼──────────────┐
          │  PluginManager │  │  RAG Module      │
          │  .so + .py 扫描│  │  向量嵌入 / 搜索  │
          └──┬─────────┬───┘  └──────────────────┘
             │         │
    ┌────────▼──┐ ┌───▼──────────┐
    │ 原生 .so  │ │ Python 子进程 │
    │ (dlopen)  │ │ (fork/exec)  │
    │ Weather   │ │ Calculator   │
    │ Shell     │ │ Translator   │
    └───────────┘ │ SQLite       │
                  │ SystemMon    │
                  │ TimeTools    │
                  │ XiaoLiuRen   │
                  └──────────────┘
```

### 核心模块

| 模块 | 路径 | 职责 |
|------|------|------|
| **Server** | `mcp_server/src/server/` | JSON-RPC 路由、请求分发、通知队列、RAG 集成 |
| **Transport** | `mcp_server/src/transport/` | Stdio / SSE / HttpStream 三种传输实现 |
| **PluginManager** | `mcp_server/src/loader/` | 统一扫描目录，加载 `.so` 和 `.py` 插件 |
| **PluginsLoader** | `mcp_server/src/loader/` | `dlopen` 方式加载 C++ 原生插件 |
| **PythonBridge** | `mcp_server/src/bridge/` | fork/exec Python 子进程，管道 JSON 通信 |
| **RAG** | `mcp_server/src/rag/` | 向量嵌入、缓存、索引、语义检索 |
| **MCPBuilder** | `mcp_server/src/utils/` | JSON-RPC 响应构建工具 |
| **PluginAPI** | `mcp_server/src/interface/` | 插件 C ABI 接口定义 |
| **mcp_plugin** | `mcp_server/plugins/python/mcp_plugin/` | Python 插件 SDK（装饰器、类型、桥接协议） |

## 插件系统

### 插件目录结构

```
mcp_server/plugins/
├── weather/               ← C++ 原生插件源码
│   ├── CMakeLists.txt
│   └── Weather.cpp
├── shell/                 ← C++ 原生插件源码
│   ├── CMakeLists.txt
│   └── Shell.cpp
├── native/                ← 编译产物（gitignore，构建自动生成）
│   ├── libweather.so
│   └── libshell.so
└── python/                ← Python 插件
    ├── mcp_plugin/        ← Python 插件 SDK
    │   ├── bridge.py      ← 子进程入口，JSON 协议
    │   ├── plugin.py      ← 装饰器基类
    │   └── types.py       ← 数据类型定义
    ├── calculator.py      ← 数学计算
    ├── sqlite_plugin.py   ← SQLite 数据库操作
    ├── system_monitor.py  ← 系统监控
    ├── time_tools.py      ← 时间工具
    ├── translator.py      ← 翻译
    └── xiaoliuren.py      ← 小六壬占卜
```

### 编写 Python 插件

使用 `@tool_plugin` 装饰器，只需定义一个类：

```python
from mcp_plugin import tool_plugin, Tool

@tool_plugin(name="my-plugin", version="1.0.0")
class MyPlugin:
    def get_tools(self):
        return [
            Tool(
                name="my_tool",
                description="工具描述",
                inputSchema={
                    "type": "object",
                    "properties": {
                        "param1": {"type": "string", "description": "参数说明"}
                    },
                    "required": ["param1"]
                }
            )
        ]

    def handle_tool_call(self, tool_name, arguments):
        # 处理工具调用，返回结果
        return {
            "content": [{"type": "text", "text": "结果内容"}],
            "isError": False
        }
```

将 `.py` 文件放入 `mcp_server/plugins/python/`，服务器会自动发现并加载。

### 编写 C++ 原生插件

1. 在 `mcp_server/plugins/` 下创建目录，添加 `CMakeLists.txt` 和 `.cpp` 源文件
2. 实现 `CreatePlugin()` / `DestroyPlugin()` 函数（`extern "C"`），返回 `PluginAPI*` 结构体
3. 在 `mcp_server/CMakeLists.txt` 中添加 `add_subdirectory(plugins/<插件名>)`
4. 详细说明参见 `docs/plugin_dev_guide.md`

## RAG 语义检索（可选）

RAG 模块利用向量嵌入技术，根据用户的自然语言查询自动匹配最相关的工具。启用方式：

### 1. 创建 API Key 配置文件

复制以下内容，创建 `conf/conf.ini`（该文件已被 gitignore，不会提交到仓库）：

```ini
[dashscope]
# 阿里百炼 DashScope API Key
# 获取地址: https://dashscope.console.aliyun.com
api_key = sk-your-api-key-here

# 可选: 覆盖默认模型和维度
# model = text-embedding-v2
# dimension = 1536
```

> ⚠️ **隐私提醒**：`conf/conf.ini` 包含 API Key，已被 `.gitignore` 忽略。请勿将包含真实 Key 的配置文件提交到仓库。

### 2. 启动服务器

通过 `-c` 参数指定配置文件路径，服务器启动时自动加载并启用 RAG：

```bash
./build/mcp_server/mcp_server -p mcp_server/plugins -c conf/conf.ini
```

> **注意**：通过 Claude Code（`.mcp.json`）启动时，`-c` 必须使用**绝对路径**，否则服务器会因工作目录不同而找不到配置文件。

如果 API Key 有效，日志会显示 `RAG enabled via <config_path>`。嵌入向量索引会自动保存到 `mcp_server/plugins/.rag_index.json`，下次启动直接加载，无需重复计算。

## 运行测试

```bash
# 运行所有测试
for t in mcp_server/tests/test_*.py; do
    echo "=== $t ===" && python3 "$t" || break
done

# 单独运行某个测试
python3 mcp_server/tests/test_calculator.py
python3 mcp_server/tests/test_translator.py
```

测试文件位于 `mcp_server/tests/`，每个测试会独立启动服务器实例，通过 stdio 进行 JSON-RPC 通信。

## 项目结构总览

```
.
├── .mcp.json                        ← Claude Code MCP 配置
├── .clang-format                    ← C++ 代码格式化规则
├── .clangd                          ← clangd 静态检查配置
├── CMakeLists.txt                   ← 顶层构建脚本
├── CLAUDE.md                        ← Claude Code 开发指南
├── README.md                        ← 本文件
├── conf/
│   └── conf.ini                     ← 🔒 RAG API Key（需自行创建，gitignore）
├── docs/
│   ├── plugin_dev_guide.md          ← 插件开发详细指南
│   └── plugin_recommendations.md    ← 插件推荐列表
├── logs/                            ← 🔒 日志输出目录（gitignore）
├── mcp_server/
│   ├── CMakeLists.txt               ← 服务器构建脚本
│   ├── include/                     ← 头文件
│   │   ├── common/                  ← 第三方库头文件（json, httplib, popl 等）
│   │   └── rag/                     ← RAG 模块头文件
│   ├── libs_tier_01/                ← 第三方源码（aixlog 日志库）
│   ├── plugins/                     ← 插件目录
│   │   ├── native/                  ← 🔒 编译产物（gitignore）
│   │   └── python/                  ← Python 插件
│   ├── src/                         ← 服务器源码
│   │   ├── bridge/                  ← Python 子进程桥接
│   │   ├── interface/               ← 传输/插件接口定义
│   │   ├── loader/                  ← 插件加载器
│   │   ├── rag/                     ← RAG 检索增强模块
│   │   ├── server/                  ← Server 核心
│   │   ├── transport/               ← 传输层实现
│   │   └── utils/                   ← 工具类
│   └── tests/                       ← 集成测试
```

> 🔒 标记的目录/文件已被 `.gitignore` 忽略，clone 后需要自行创建或生成。

## 开发必读

1. **C++ 代码风格**：Microsoft 风格，4 空格缩进，120 列宽，`BreakBeforeBraces: Attach`。详细规则见 `.clang-format`。
2. **头文件包含顺序**：项目头文件 → C 系统头文件 → C++ 标准库 → 第三方库。
3. **Python 插件协议**：桥接层使用换行分隔的 JSON 协议，`SendCommand()` 的参数包装方式与 Bridge 端的 `_resolve_index()` 有所不同，详见 `CLAUDE.md`。
4. **新增原生插件**：需要在 `mcp_server/CMakeLists.txt` 中添加 `add_subdirectory`。
5. **日志目录**：服务器启动时会自动创建，无需手动 `mkdir`。

## 常见问题

### RAG 未启用：`no API key found`

日志提示 `RAG not enabled — no API key found in ...`，常见原因：

| 原因 | 解决 |
|------|------|
| **配置文件路径错误** | `.mcp.json` 中 `-c` 必须使用**绝对路径**，不能写相对路径（服务器工作目录不是项目根目录） |
| **section 名不匹配** | `conf/conf.ini` 的 section 必须是 `[dashscope]`（不是 `[embedding]` 或其他名称） |
| **API key 加了引号** | `api_key = sk-xxx` 不要加引号，解析器不会自动去除引号字符 |
| **没有传 `-c` 参数** | 检查启动命令是否包含 `-c /path/to/conf/conf.ini` |

### 索引文件在哪？为什么首次启动有警告？

向量索引缓存在 `mcp_server/plugins/.rag_index.json`。首次启动时该文件不存在，日志会显示：

```
[Warn] Index file not found: .../.rag_index.json
```

这是正常现象，RAG 会自动构建索引并写入该文件。索引构建完成后会立即持久化，后续启动直接加载。

### `.mcp.json` 配置注意事项

1. **所有路径必须用绝对路径**（`command`、`args` 中的所有路径）
2. **必须同时配置 `-p`、`-c`、`-l` 三个路径参数**
3. **`PYTHONPATH` 环境变量**也必须用绝对路径，指向 `mcp_server/plugins/python`

### RAG 索引丢失

如果进程被 `kill -9`（SIGKILL）强制终止，索引可能来不及写入磁盘。正常关闭（Ctrl+C 或 `kill`）会触发 `SIGINT`/`SIGTERM` 信号，服务器会走清理流程并保存索引。

## 许可证

待定