evolve-memory-system/README_MCP.md

一个集成了GraphRAG, LMCE和MCP工具的本地记忆系统，专为小说《进化》设计。

# Evolve Memory System - MCP配置指南

本指南将帮助您将小说《进化》的记忆系统连接到Claude Code，通过标准的MCP（Model Context Protocol）实现。

## 系统架构

小说《进化》的记忆系统包含以下组件：

1. **GraphRAG**: 基于Neo4j图数据库的知识存储和查询系统
2. **LMCE (Local Memory Compression Engine)**: 本地记忆压缩引擎
3. **MCP Server**: 符合Anthropic MCP标准的工具服务器

## 配置步骤

### 1. 启动服务

您有两种方式来启动服务：

**方式一：使用npm命令启动（需要预先安装依赖）**

首先，确保所有服务都在运行：

```bash
cd /Users/fanzhang/Documents/novel/evolve
npm run start
```

检查服务状态：

```bash
npm run status
```

**方式二：使用npx直接启动（推荐，无需预先安装）**

您可以直接使用npx来启动服务，而无需预先安装：

```bash
npx evolve-memory-system@1.0.5 start
```

或者，如果您使用支持MCP配置文件的编辑器（如Claude Code），可以创建以下配置文件：

```json
{
  "mcpServers": {
    "EvolveMemorySystem": {
      "command": "npx",
      "args": ["-y", "evolve-memory-system@1.0.5", "start"]
    }
  }
}
```

### 2. 配置LM Studio

1. 打开LM Studio
2. 下载并加载模型: `II-Search-4B-GGUF/II-Search-4B-Q4_K_S.gguf`
3. 启动LM Studio服务器（默认在 `http://localhost:1234`）

### 3. 配置Claude Code MCP连接

在Claude Code中添加MCP工具配置：

1. 打开Claude Code
2. 导航到MCP设置
3. 添加新的MCP配置，使用以下设置：

```
配置文件路径: /Users/fanzhang/Documents/novel/evolve/.claude/tools/evolve-memory-system-mcp.json
```

或者，如果您想手动配置，可以使用以下信息：

- **MCP Server URL**: `http://localhost:3333`
- **OpenAPI规范**: `http://localhost:3333/openapi.json`
- **工具列表端点**: `http://localhost:3333/tools/list`

您也可以使用MCP服务器配置文件：

```
配置文件路径: /Users/fanzhang/Documents/novel/evolve/mcp-server-config.json
```

### 4. 可用工具

连接成功后，您将可以使用以下工具：

#### graphrag_query
查询图数据库中的角色、地点和事件关系。

示例用法：
```
查询所有角色:
MATCH (c:Character) RETURN c.name, c.description

查询特定角色的关系:
MATCH (c:Character {name: '李明'})-[r]->(other) RETURN c.name, type(r), other.name
```

#### lmce_search_memory
在本地记忆库中搜索相关内容。

示例用法：
```
搜索与"主角能力"相关的内容
搜索与"世界观"相关的内容
```

#### file_reader
读取项目中的设定文件和草稿。

示例用法：
```
读取文件: 1_settings/style_guide.md
读取文件: 1_settings/world.md
```

#### file_writer
将生成的内容写入项目文件。

示例用法：
```
写入文件: 3_drafts_for_review/chapter1.md
内容: (您要保存的章节内容)
```

## 创作工作流程

1. **获取设定信息**:
   - 使用 `file_reader` 读取 [1_settings/style_guide.md](file:///Users/fanzhang/Documents/novel/evolve/1_settings/style_guide.md) 了解写作风格
   - 使用 `file_reader` 读取其他设定文件了解世界观

2. **查询现有信息**:
   - 使用 `graphrag_query` 查询角色关系和事件历史
   - 使用 `lmce_search_memory` 搜索相关记忆和背景信息

3. **创作内容**:
   - 结合所有信息进行创作
   - 使用 `file_writer` 保存草稿到 [3_drafts_for_review/](file:///Users/fanzhang/Documents/novel/evolve/3_drafts_for_review/) 目录

4. **迭代完善**:
   - 将最终章节移动到 [4_final_chapters/](file:///Users/fanzhang/Documents/novel/evolve/4_final_chapters/) 目录
   - 系统会自动更新相关记忆

## 故障排除

如果遇到问题，请按以下步骤排查：

1. 检查所有服务是否运行：
   ```bash
   npm run status
   ```
   或者：
   ```bash
   npx evolve-memory-system@1.0.5 status
   ```

2. 检查MCP服务器端口：
   ```bash
   lsof -i :3333
   ```

3. 检查Neo4j服务：
   ```bash
   lsof -i :7687
   ```

4. 检查LM Studio API：
   ```bash
   curl http://localhost:1234/v1/models
   ```

5. 测试MCP工具列表：
   ```bash
   curl http://localhost:3333/tools/list
   ```

## API端点参考

- `GET /health` - 健康检查
- `GET /tools/list` - 列出所有MCP工具
- `GET /openapi.json` - OpenAPI规范
- `POST /tools/graphrag_query` - 执行GraphRAG查询
- `POST /tools/lmce_search_memory` - 搜索本地记忆
- `POST /tools/file_reader` - 读取文件
- `POST /tools/file_writer` - 写入文件

## 支持的Cypher查询示例

1. 查询所有角色：
   ```cypher
   MATCH (c:Character) RETURN c.name, c.description
   ```

2. 查询角色关系：
   ```cypher
   MATCH (c1:Character)-[r]->(c2:Character) RETURN c1.name, type(r), c2.name
   ```

3. 查询事件和参与者：
   ```cypher
   MATCH (c:Character)-[r:ATTENDED]->(e:Event) RETURN e.title, collect(c.name) as participants
   ```

现在您已经完成了MCP配置，可以开始使用Claude Code与小说《进化》的记忆系统进行交互了。