# WMcpServer

**Repository Path**: fengxian21/wmcp-server

## Basic Information

- **Project Name**: WMcpServer
- **Description**: 基于WHttpServer写个mcp server，可以供claude code这样的ai agent工具连接，自定义任务
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WMcpServer

`WMcpServer` 是一个使用 C++11 实现的 MCP Streamable HTTP 服务，可供 Claude Code 通过 HTTP 连接，其基于基础的WHttpServer项目编写。  
WHttpserver服务地址：https://gitee.com/fengxian21/whttp-server  

默认服务地址：

```text
http://0.0.0.0:7777/mcp
```

当前提供以下工具：

| 工具 | 功能 |
| --- | --- |
| `echo` | 原样返回输入文本 |
| `add` | 计算两个数字之和 |
| `get_time` | 获取服务端本地时间 |

## 1. 编译

进入工程上层目录：

```bash
cd wmcp-server
```

编译 Release 版本：

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
```

生成的可执行文件：

```text
../bin/WMcpServer
```

## 2. 启动服务

使用默认端口 `7777`：

```bash
../bin/WMcpServer
```

通过第一个参数指定端口：

```bash
../bin/WMcpServer 8888
```

## 3. 检查服务

本机检查：

```bash
curl http://127.0.0.1:7777/health
```

正常响应：

```json
{
  "status": "ok",
  "server": "WMcpServer",
  "version": "1.0.0"
}
```

如果 Claude Code 运行在虚拟机中，需要在虚拟机内检查宿主机地址：

```bash
curl http://宿主机IP:7777/health
```

例如：

```bash
curl http://192.168.1.10:7777/health
```

无法访问时检查：

- 虚拟机使用的是桥接网络还是 NAT 网络。
- NAT 模式是否配置端口转发。
- 宿主机防火墙是否允许 TCP `7777` 端口。
- `WMcpServer` 是否正在运行。
- 宿主机 IP 是否可以从虚拟机访问。

## 4. MCP 初始化流程

Claude Code 连接 `/mcp` 后，主要通过下面三个步骤完成初始化。所有请求均使用：

```http
POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
```

初始化成功后，后续请求还会携带服务端协商确定的协议版本：

```http
MCP-Protocol-Version: 2025-06-18
```

### 4.1 客户端发送 `initialize`

客户端首先发送自己的协议版本、能力和客户端信息：

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {}
    },
    "clientInfo": {
      "name": "claude-code",
      "version": "2.1.190"
    }
  }
}
```

该请求由 `WMcpServer::handleInitialize()` 处理。当前服务支持：

- `2025-03-26`
- `2025-06-18`

如果客户端请求的版本不受支持，服务端会回退到 `2025-06-18`。返回 HTTP `200`，响应示例：

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "WMcpServer",
      "version": "1.0.0"
    },
    "instructions": "A C++ MCP HTTP server providing echo, add and get_time tools."
  }
}
```

主要字段说明：

- `protocolVersion`：最终协商使用的 MCP 协议版本。
- `capabilities.tools`：表示服务端支持 MCP Tools。
- `serverInfo`：服务名称和版本。
- `instructions`：提供给客户端的服务功能说明。

### 4.2 客户端发送 `notifications/initialized`

收到初始化响应后，客户端发送初始化完成通知：

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

这是 JSON-RPC Notification，没有 `id`，因此服务端不能返回 JSON-RPC 响应体。当前服务返回：

```http
HTTP/1.1 202 Accepted
Content-Length: 0
```

也就是 HTTP 状态码为 `202`，响应体为空。

### 4.3 客户端可能探测 SSE 通道

部分 Claude Code 版本会在初始化通知后发送：

```http
GET /mcp HTTP/1.1
Accept: text/event-stream
MCP-Protocol-Version: 2025-06-18
```

GET 请求没有 JSON 请求体。当前 `WMcpServer` 没有提供独立的 SSE 长连接，返回：

```http
HTTP/1.1 405 Method Not Allowed
Allow: POST
```

这只是客户端对可选 SSE 通道的探测。Claude Code 随后仍可继续通过 POST 调用 `tools/list` 和其他 MCP 方法。

### 4.4 客户端获取工具列表

初始化完成后，Claude Code 通过 `tools/list` 获取可用工具：

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

该请求由 `WMcpServer::handleToolsList()` 处理，返回 HTTP `200`：

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "echo",
        "description": "Return the input text unchanged",
        "inputSchema": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "description": "Text to return"
            }
          },
          "required": [
            "text"
          ]
        }
      },
      {
        "name": "add",
        "description": "Add two numbers",
        "inputSchema": {
          "type": "object",
          "properties": {
            "a": {
              "type": "number",
              "description": "First number"
            },
            "b": {
              "type": "number",
              "description": "Second number"
            }
          },
          "required": [
            "a",
            "b"
          ]
        }
      },
      {
        "name": "get_time",
        "description": "Get the current local time",
        "inputSchema": {
          "type": "object"
        }
      }
    ]
  }
}
```

Claude Code 会根据这里返回的工具名称、描述及 `inputSchema`，判断何时调用工具以及生成哪些参数。

初始化时序可以概括为：

```text
Claude Code                         WMcpServer
    |                                   |
    |-- initialize -------------------->|
    |<------------- initialize result --|
    |                                   |
    |-- notifications/initialized ----->|
    |<-------------------- HTTP 202 -----|
    |                                   |
    |-- GET /mcp（可选探测）----------->|
    |<-------------------- HTTP 405 -----|
    |                                   |
    |-- tools/list --------------------->|
    |<------------------ tools result ---|
    |                                   |
```

### 4.5 可选的连通性检查

初始化后，客户端可能发送 `ping`：

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "ping"
}
```

服务端返回：

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {}
}
```

`ping` 不是上述初始化握手的必需步骤，只用于确认 MCP 连接仍然可用。

## 5. 添加到 Claude Code

在 Claude Code 所在机器中执行：

```bash
claude mcp add --transport http --scope user w-mcp-server \
  http://宿主机IP:7777/mcp
```

例如：

```bash
claude mcp add --transport http --scope user w-mcp-server \
  http://192.168.1.10:7777/mcp
```

参数说明：

- `--transport http`：使用 MCP Streamable HTTP。
- `--scope user`：对当前用户的所有 Claude Code 项目生效。
- `w-mcp-server`：Claude Code 中显示的服务名称。
- `/mcp`：MCP 服务入口。

如果只希望当前项目使用，进入目标项目后执行：

```bash
claude mcp add --transport http --scope project w-mcp-server \
  http://宿主机IP:7777/mcp
```

## 6. 检查 Claude Code 配置

查看所有 MCP Server：

```bash
claude mcp list
```

查看当前服务的详细配置：

```bash
claude mcp get w-mcp-server
```

进入 Claude Code 后执行：

```text
/mcp
```

正常情况下，`w-mcp-server` 应显示为已连接，并能看到 3 个工具。

## 7. 调用工具

测试加法：

```text
调用 w-mcp-server 的 add 工具，计算 12.5 加 7.5。
```

测试服务端时间：

```text
调用 w-mcp-server 的 get_time 工具，获取服务端当前时间。
```

测试回显：

```text
调用 w-mcp-server 的 echo 工具，回显“Hello MCP”。
```

## 8. 扩展自己的 MCP 工具

新增普通 Tool 时，不需要修改 HTTP 接口、`processRequest()` 或初始化流程，主要扩展以下位置：

1. 在 `WMcpServer.h` 中声明工具处理函数。
2. 在 `WMcpServer::handleToolsList()` 中注册工具名称、说明和参数格式，让 Claude Code 能发现该工具。
3. 在 `WMcpServer::handleToolsCall()` 中根据工具名称分发调用。
4. 在 `WMcpServer.cpp` 中实现具体功能。

下面以新增 `multiply` 乘法工具为例。

### 8.1 声明处理函数

在 `WMcpServer.h` 的工具处理函数区域添加：

```cpp
CJsonObject callMultiply(const CJsonObject& arguments);
```

### 8.2 注册工具

在 `WMcpServer::handleToolsList()` 中，将下面的工具描述添加到 `tools` 数组：

```cpp
CJsonObject multiplyA;
multiplyA.Add("type", "number");

CJsonObject multiplyB;
multiplyB.Add("type", "number");

CJsonObject multiplyProperties;
multiplyProperties.Add("a", multiplyA);
multiplyProperties.Add("b", multiplyB);

CJsonObject multiplyRequired("[]");
multiplyRequired.Add(std::string("a"));
multiplyRequired.Add(std::string("b"));

CJsonObject multiplyInputSchema;
multiplyInputSchema.Add("type", "object");
multiplyInputSchema.Add("properties", multiplyProperties);
multiplyInputSchema.Add("required", multiplyRequired);

CJsonObject multiplyTool;
multiplyTool.Add("name", "multiply");
multiplyTool.Add("description", "Multiply two numbers");
multiplyTool.Add("inputSchema", multiplyInputSchema);
tools.Add(multiplyTool);
```

注意：向 JSON 数组添加字符串时使用 `std::string("a")`，避免 `const char*` 被错误匹配成布尔类型。

### 8.3 分发工具调用

在 `WMcpServer::handleToolsCall()` 的工具名称判断中添加：

```cpp
else if (name == "multiply") {
    toolResult = callMultiply(arguments);
}
```

### 8.4 实现工具功能

在 `WMcpServer.cpp` 中添加：

```cpp
CJsonObject WMcpServer::callMultiply(const CJsonObject& arguments)
{
    double a = 0.0;
    double b = 0.0;
    const int aType = arguments.GetValueType("a");
    const int bType = arguments.GetValueType("b");
    if ((aType != cJSON_Int && aType != cJSON_Double) ||
        (bType != cJSON_Int && bType != cJSON_Double) ||
        !arguments.Get("a", a) ||
        !arguments.Get("b", b)) {
        CJsonObject error;
        error.Add("_error", "Parameters 'a' and 'b' must be numbers");
        return error;
    }

    std::ostringstream stream;
    stream << std::setprecision(15) << (a * b);
    return makeToolTextResult(stream.str());
}
```

`makeToolTextResult()` 用于生成 MCP 规定的文本结果。如果工具执行失败，可以返回带 `_error` 字段的对象，现有的 `handleToolsCall()` 会将其转换成 MCP 工具错误。

修改完成后重新编译并重启 `WMcpServer`。然后重新连接 Claude Code，或在 Claude Code 中执行 `/mcp` 检查工具列表，即可调用新工具：

```text
调用 w-mcp-server 的 multiply 工具，计算 6 乘以 7。
```

## 9. 删除 Claude Code 配置

```bash
claude mcp remove --scope user w-mcp-server
```

项目级配置使用：

```bash
claude mcp remove --scope project w-mcp-server
```

## 10. 常见问题

### 访问 `/mcp` 返回 405

浏览器和普通 `curl` 默认发送 GET 请求，而当前服务的 GET `/mcp` 返回 `405 Method Not Allowed`，这是正常行为。

Claude Code 会使用 POST 向 `/mcp` 发送 MCP JSON-RPC 请求。健康检查应访问：

```text
http://宿主机IP:7777/health
```

### 修改端口后无法连接

服务端端口和 Claude Code 配置必须一致。例如服务使用：

```bash
../bin/WMcpServer 8888
```

Claude Code 地址也应改为：

```text
http://宿主机IP:8888/mcp
```

### 安全提示

当前服务监听 `0.0.0.0`，且暂未启用身份认证。建议只在可信局域网或受控虚拟机网络中使用，不要直接暴露到公网。