Skip to content

MCP-SERVER.md

Latest commit

 

History

History
198 lines (147 loc) · 4.16 KB

MCP-SERVER.md

File metadata and controls

198 lines (147 loc) · 4.16 KB
Raw

WoClaw MCP Server 使用文档

通过 MCP（Model Context Protocol）将 WoClaw Hub 暴露给任何 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）。

MCP Bridge 是什么

WoClaw MCP Bridge 将 Hub 的记忆池和 Topic 消息系统以 MCP tools 的形式暴露：

记忆操作：woclaw_memory_read / write / list / delete
Topic 操作：woclaw_topics_list / topic_messages / topic_send / topic_join

安装方式

方式一：通过 woclaw CLI（推荐）

# woclaw CLI 已内置 mcp serve 子命令
npm install -g xingp14-woclaw

# 启动 MCP server（使用环境变量）
export WOCLAW_WS_URL=ws://your-hub-host:8082
export WOCLAW_REST_URL=http://your-hub-host:8083
export WOCLAW_TOKEN=WoClaw2026
woclaw mcp serve

方式二：直接运行 woclaw-mcp

npm install -g woclaw-mcp
woclaw-mcp --hub ws://your-hub-host:8082 --token WoClaw2026 --rest-url http://your-hub-host:8083

方式三：本地构建

cd /home/node/.openclaw/workspace/woclaw/mcp-bridge
npm install
npm run build
node dist/index.js --hub ws://your-hub-host:8082 --token WoClaw2026 --rest-url http://your-hub-host:8083

MCP 客户端配置

Claude Desktop

找到你的 claude_desktop_config.json：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

添加 woclaw MCP server：

{
  "mcpServers": {
    "woclaw": {
      "command": "node",
      "args": ["/path/to/woclaw-mcp/dist/index.js",
               "--hub=ws://your-hub-host:8082",
               "--token=WoClaw2026",
               "--rest-url=http://your-hub-host:8083"]
    }
  }
}

Cursor / Windsurf

在 MCP Settings 中添加同样配置，路径指向 woclaw-mcp 的安装位置。

可用工具

记忆操作

woclaw_memory_read

读取指定 key 的记忆内容。

{
  "key": "project-context",
  "intent": "code"      // 可选：code | debug | design | general
}

woclaw_memory_write

写入记忆到共享池。

{
  "key": "project-context",
  "value": "这是一个共享项目上下文",
  "tags": ["project", "context"],
  "ttl": 86400          // 可选：TTL 秒数，默认永不过期
}

woclaw_memory_list

列出所有记忆，支持按 tag 过滤。

{
  "tags": "project,context"  // 可选：逗号分隔的 tag 列表
}

woclaw_memory_delete

删除指定记忆。

{
  "key": "project-context"
}

Topic 操作

woclaw_topics_list

列出 Hub 上所有 topic。

{}

woclaw_topic_messages

获取指定 topic 最近的消息历史。

{
  "topic": "general",
  "limit": 20           // 可选：最大消息数，默认 50
}

woclaw_topic_send

向指定 topic 发送消息。

{
  "topic": "general",
  "message": "Hello from MCP client!"
}

woclaw_topic_join

订阅加入一个 topic（建立 WebSocket 订阅）。

{
  "topic": "general"
}

环境变量

变量 说明 默认值
WOCLAW_WS_URL WoClaw Hub WebSocket 地址 ws://localhost:8082
WOCLAW_REST_URL WoClaw Hub REST API 地址 http://localhost:8083
WOCLAW_TOKEN Hub 认证 Token —

通过 woclaw CLI 启动

woclaw mcp serve 是官方推荐的启动方式，会自动读取 ~/.woclaw/.env 中的配置：

# 已有 ~/.woclaw/.env（woclaw hook 安装时自动生成）
# 无需额外参数
woclaw mcp serve

# 或手动指定
woclaw mcp serve --rest-url http://your-hub-host:8083

验证

启动后，Claude Desktop/Cursor 会自动加载 MCP tools。可在客户端中测试：

# 列出所有记忆
woclaw_memory_list

# 写入一条测试记忆
woclaw_memory_write(key="mcp-test", value="MCP Bridge is working!")

故障排除

MCP tools 未出现？

  1. 重启 Claude Desktop / Cursor
  2. 检查 config 中的路径是否正确（使用绝对路径）
  3. 手动运行 node /path/to/woclaw-mcp/dist/index.js 确认无报错

连接失败？

  • 确认 Hub 地址可访问：curl http://your-hub-host:8083/health
  • 确认 Token 正确：WoClaw2026