From f6a809599f882041cf0c15d5b83b5347b56a92fd Mon Sep 17 00:00:00 2001 From: CalibratedGhosts Date: Mon, 11 May 2026 11:23:40 +0000 Subject: [PATCH] Add Claude Code MCP server docs --- README.md | 2 + docs/mcp-server.md | 157 ++++++++++++++++++++++++++++++++++++++++++++ src/mcp/__init__.py | 4 +- src/mcp/server.py | 4 +- 4 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 docs/mcp-server.md diff --git a/README.md b/README.md index 91b2b65..16902fd 100644 --- a/README.md +++ b/README.md @@ -214,6 +214,7 @@ python -c "from clawra import Clawra; print(Clawra().self_memory.stats)" | [SDK_GUIDE.md](docs/SDK_GUIDE.md) | API 使用指南 | | [CONFIGURATION.md](docs/CONFIGURATION.md) | 配置说明 | | [CHANGELOG.md](docs/CHANGELOG.md) | 版本记录 | +| [mcp-server.md](docs/mcp-server.md) | Claude Code MCP Server 连接与故障排查 | --- @@ -228,6 +229,7 @@ python -c "from clawra import Clawra; print(Clawra().self_memory.stats)" - [x] Neo4j 图数据库存储 - [x] Hermes Agent 集成插件 - [x] run_self_check 定时自检 +- [x] Claude Code MCP Server（见 [docs/mcp-server.md](docs/mcp-server.md)） ### 🚧 进行中 - [ ] 可视化自我成长面板 diff --git a/docs/mcp-server.md b/docs/mcp-server.md new file mode 100644 index 0000000..256f9d7 --- /dev/null +++ b/docs/mcp-server.md @@ -0,0 +1,157 @@ +# Clawra MCP Server for Claude Code + +Clawra 4.2.0 includes a stdio MCP server that exposes Clawra memory, +reasoning, retrieval, and evolution tools to Claude Code. + +The server implementation lives in `src/mcp/server.py`. After installing the +project, run it as: + +```bash +python -m mcp.server +``` + +Use `python3` instead of `python` if your system does not provide a `python` +alias. + +## Install + +From a local checkout: + +```bash +git clone https://github.com/wu-xiaochen/clawra-engine.git +cd clawra-engine +pip install -e . +``` + +Optional development install: + +```bash +pip install -e ".[dev]" +``` + +## Claude Code configuration + +Add a server entry to your Claude Code MCP configuration, for example +`.claude/mcp.json` in the workspace where you want to use Clawra: + +```json +{ + "mcpServers": { + "clawra": { + "command": "python", + "args": ["-m", "mcp.server"], + "cwd": "/absolute/path/to/clawra-engine" + } + } +} +``` + +If your environment only has `python3`, use: + +```json +{ + "mcpServers": { + "clawra": { + "command": "python3", + "args": ["-m", "mcp.server"], + "cwd": "/absolute/path/to/clawra-engine" + } + } +} +``` + +Restart Claude Code after editing the MCP configuration. Claude Code should +then discover a server named `clawra`. + +## Available tools + +The server currently exposes: + +| Tool | Purpose | +| --- | --- | +| `clawra_learn` | Learn facts, relations, and constraints from natural-language text. | +| `clawra_add_fact` | Add a fact triple to the knowledge graph. | +| `clawra_reason` | Run Clawra's neurosymbolic reasoning/orchestration path. | +| `clawra_query_patterns` | Search learned patterns and rules. | +| `clawra_retrieve` | Retrieve related knowledge with GraphRAG-style context search. | +| `clawra_evolve` | Trigger the autonomous evolution loop. | +| `clawra_stats` | Return system statistics. | +| `clawra_orchestrate` | Run retrieval, reasoning, and chain-of-thought orchestration for a query. | + +## Quick smoke test + +You can test the stdio server without Claude Code by sending JSON-RPC messages +on stdin. + +```bash +printf '%s\n' \ + '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \ + '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ + | python -m mcp.server +``` + +Expected result: + +- the `initialize` response includes server name `clawra`; +- the `tools/list` response includes tools such as `clawra_learn`, + `clawra_reason`, and `clawra_stats`. + +## Common troubleshooting + +### `python: command not found` + +Use `python3` in both the command line and Claude Code configuration. + +### `No module named mcp.server` + +Install Clawra from the repository root: + +```bash +pip install -e . +``` + +Also make sure the `cwd` in `.claude/mcp.json` points at the Clawra checkout. + +### Dependency import errors + +The MCP server imports Clawra and its runtime dependencies. Reinstall the +package with: + +```bash +pip install -e . +``` + +If you are developing locally, use: + +```bash +pip install -e ".[dev]" +``` + +### Claude Code does not show the server + +Check: + +1. The JSON in `.claude/mcp.json` is valid. +2. `cwd` is an absolute path to the repository checkout. +3. The same command works in a terminal: + + ```bash + cd /absolute/path/to/clawra-engine + python -m mcp.server + ``` + +4. Claude Code was restarted after editing the MCP configuration. + +### A tool call returns an initialization error + +The server initializes a `Clawra()` instance when it starts. If that fails, MCP +will still respond with an error message. Run the server command directly in a +terminal and read stderr for the underlying import, dependency, or local data +path problem. + +## Notes + +This document is a text setup guide. It does not include a live Claude Code +screenshot or video. The smoke test above verifies the JSON-RPC server path, and +the Claude Code configuration shows how to wire the same server into Claude +Code. diff --git a/src/mcp/__init__.py b/src/mcp/__init__.py index 0221df6..a58344b 100644 --- a/src/mcp/__init__.py +++ b/src/mcp/__init__.py @@ -2,7 +2,7 @@ Clawra MCP Server Module Usage: - python -m clawra.mcp.server + python -m mcp.server Claude Code MCP Configuration: 在 .claude/mcp.json 中添加: @@ -10,7 +10,7 @@ "mcpServers": { "clawra": { "command": "python", - "args": ["-m", "clawra.mcp.server"], + "args": ["-m", "mcp.server"], "cwd": "/path/to/clawra-engine" } } diff --git a/src/mcp/server.py b/src/mcp/server.py index 45fa55f..f2fcd11 100644 --- a/src/mcp/server.py +++ b/src/mcp/server.py @@ -5,14 +5,14 @@ 通过 Model Context Protocol (MCP) 暴露 Clawra 的核心功能。 启动方式: - python -m clawra.mcp.server + python -m mcp.server Claude Code 配置 (.claude/mcp.json): { "mcpServers": { "clawra": { "command": "python", - "args": ["-m", "clawra.mcp.server"] + "args": ["-m", "mcp.server"] } } }