README.md•9.22 kB
# MCP 内存服务器 - HTTP 流式传输
基于官方 [MCP Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 重构的 HTTP 流式传输版本，使用 Hono.js 框架。
## 项目来源
本项目基于 [MCP Servers 仓库](https://github.com/modelcontextprotocol/servers) 中的官方 **@modelcontextprotocol/server-memory** 重构而来。原始内存服务器使用 stdio 传输，而此版本经过重构以支持 HTTP 流式传输，适用于独立部署场景。
## 与原版本的主要差异
- **传输方式**: HTTP 流式传输，而非 stdio
- **框架选择**: 使用 Hono.js，而非 Express.js（其他 HTTP 服务器使用）
- **架构设计**: 按单一职责原则重构为多文件架构
- **部署方式**: 可作为独立 HTTP 服务部署
## 架构设计
原始的单文件实现已重构为模块化结构：
```
src/memory-http/
├── types.ts # 接口定义 (Entity, Relation, KnowledgeGraph)
├── storage.ts # 文件存储操作
├── knowledge-graph.ts # KnowledgeGraphManager 类及所有图操作
├── tools.ts # MCP 工具定义
├── server.ts # MCP 服务器逻辑
└── http-server.ts # Hono.js HTTP 服务器及流式传输支持
```
## 功能特性
完全保留原始内存服务器的所有功能：
- **知识图谱存储**: 存储和管理实体、关系和观察
- **文件持久化**: JSON 行格式存储（与原版兼容）
- **搜索能力**: 按名称、类型或观察内容查询实体
- **CRUD 操作**: 对所有图元素的完整增删改查支持
### 可用工具
1. **create_entities** - 在知识图谱中创建新实体
2. **create_relations** - 在实体间创建关系
3. **add_observations** - 向现有实体添加观察
4. **delete_entities** - 删除实体及相关关系
5. **delete_observations** - 从实体中移除特定观察
6. **delete_relations** - 删除特定关系
7. **read_graph** - 读取整个知识图谱
8. **search_nodes** - 按查询字符串搜索实体
9. **open_nodes** - 按名称检索特定实体
## 安装和使用
### 安装依赖
```bash
cd src/memory-http
pnpm install
```
### 构建项目
```bash
pnpm build
```
### 启动 HTTP 服务器
```bash
pnpm start
```
服务器将默认在 `http://localhost:3002/mcp` 启动。
### 环境变量
- `PORT` - 服务器端口（默认：3002）
- `MEMORY_FILE_PATH` - 内存存储文件路径（默认：./memory.json）
## HTTP API 端点
服务器提供符合 MCP 协议的端点：
- `GET /` - 服务器基本信息
- `GET /health` - 健康检查端点（用于服务监控）
- `POST /mcp` - 初始化会话并处理 MCP 请求
- `GET /mcp` - 服务器发送事件（SSE）流式传输实时更新
- `DELETE /mcp` - 会话终止
所有 MCP 请求必须包含 `mcp-session-id` 请求头进行会话管理。
### 健康检查示例
```bash
curl http://localhost:3002/health
```
响应示例：
```json
{
"status": "healthy",
"service": "mcp-memory-http",
"version": "0.6.3",
"timestamp": "2024-01-15T10:30:00.000Z",
"sessions": 2
}
```
## 存储格式
存储格式与原始内存服务器完全相同：
- 每行包含一个带有 `type` 字段的 JSON 对象（"entity" 或 "relation"）
- 实体包含 name、entityType 和 observations 数组
- 关系包含 from、to 和 relationType 字段
## 基础用法和测试示例
### 1. 启动服务器
```bash
cd src/memory-http
pnpm start
```
服务器将在 `http://localhost:3002/mcp` 启动。
### 2. 使用 cURL 测试
#### 初始化会话
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {}
},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'
```
响应将包含 `mcp-session-id` 头，后续请求需要使用此 ID。
#### 创建实体
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "create_entities",
"arguments": {
"entities": [
{
"name": "张三",
"entityType": "人物",
"observations": ["软件工程师", "喜欢编程", "在北京工作"]
},
{
"name": "阿里巴巴",
"entityType": "公司",
"observations": ["中国电商巨头", "总部在杭州", "成立于1999年"]
}
]
}
}
}'
```
#### 创建关系
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "create_relations",
"arguments": {
"relations": [
{
"from": "张三",
"to": "阿里巴巴",
"relationType": "在...工作"
}
]
}
}
}'
```
#### 查询知识图谱
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "read_graph"
}
}'
```
#### 搜索实体
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "search_nodes",
"arguments": {
"query": "软件工程师"
}
}
}'
```
#### 添加观察
```bash
curl -X POST http://localhost:3002/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "add_observations",
"arguments": {
"observations": [
{
"entityName": "张三",
"contents": ["精通 TypeScript", "有5年工作经验"]
}
]
}
}
}'
```
### 3. 查看存储数据
查看 `memory.json` 文件内容：
```bash
cat src/memory-http/memory.json
```
示例输出：
```json
{"type":"entity","name":"张三","entityType":"人物","observations":["软件工程师","喜欢编程","在北京工作","精通 TypeScript","有5年工作经验"]}
{"type":"entity","name":"阿里巴巴","entityType":"公司","observations":["中国电商巨头","总部在杭州","成立于1999年"]}
{"type":"relation","from":"张三","to":"阿里巴巴","relationType":"在...工作"}
```
### 4. 使用 MCP 客户端连接
如果使用支持 MCP 协议的客户端（如 Claude Desktop），可以在配置中添加：
```json
{
"mcpServers": {
"memory-http": {
"command": "node",
"args": ["/path/to/src/memory-http/dist/http-server.js"],
"env": {
"PORT": "3002"
}
}
}
}
```
### 5. TypeScript 测试脚本
我们还提供了一个 TypeScript 测试脚本 `test-memory-server.ts`，展示如何以编程方式与 MCP 服务器交互：
```bash
# 使用 npm 脚本运行测试
pnpm test
# 或者直接运行
npx tsx test-memory-server.ts
```
TypeScript 测试脚本包含以下测试用例：
- 会话初始化和管理
- 创建实体和关系
- 添加观察数据
- 搜索和查询功能
- 完整的知识图谱读取
- 存储文件验证
### 6. Bash 测试脚本
也可以使用 Bash 脚本进行测试：
```bash
# 使用 npm 脚本运行
pnpm run test:bash
# 或者直接运行
./test-memory-server.sh
```
运行测试：
```bash
chmod +x test-memory-server.sh
./test-memory-server.sh
```
### 测试数据示例
测试完成后，`memory.json` 文件将包含类似以下内容：
```json
{"type":"entity","name":"赵六","entityType":"人物","observations":["全栈开发者","TypeScript专家","在广州工作","熟悉Node.js","有4年工作经验","毕业于中山大学"]}
{"type":"entity","name":"WebApp项目","entityType":"项目","observations":["React应用","使用TypeScript","REST API"]}
{"type":"entity","name":"TechStart","entityType":"公司","observations":["初创公司","总部在广州","专注Web开发"]}
{"type":"relation","from":"赵六","to":"TechStart","relationType":"在...工作"}
{"type":"relation","from":"赵六","to":"WebApp项目","relationType":"开发"}
```
## 开发
### 监视模式
```bash
pnpm watch
```
### 文件结构
- **types.ts** - TypeScript 接口和类型定义
- **storage.ts** - 知识图谱持久化的文件 I/O 操作
- **knowledge-graph.ts** - 图操作的核心业务逻辑
- **tools.ts** - MCP 工具模式定义
- **server.ts** - MCP 服务器设置和请求处理
- **http-server.ts** - 基于 Hono.js 的 HTTP 服务器实现
## 兼容性
此服务器与以下内容完全兼容：
- 原始 MCP Memory Server 数据格式
- MCP 协议规范
- stdio 版本的现有内存文件
## 许可证
MIT - 与原始 MCP Servers 项目相同