Add Claude Code MCP server docs

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)）
 
 ### 🚧 进行中
 - [ ] 可视化自我成长面板

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.

src/mcp/__init__.py

@@ -2,15 +2,15 @@
 Clawra MCP Server Module
 
 Usage:
-    python -m clawra.mcp.server
+    python -m mcp.server
 
 Claude Code MCP Configuration:
     在 .claude/mcp.json 中添加:
     {
         "mcpServers": {
             "clawra": {
                 "command": "python",
-                "args": ["-m", "clawra.mcp.server"],
+                "args": ["-m", "mcp.server"],
                 "cwd": "/path/to/clawra-engine"
             }
         }

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"]
             }
         }
     }