MCP 内存服务器 - HTTP 流式传输
基于官方 MCP Memory Server 重构的 HTTP 流式传输版本，使用 Hono.js 框架。
项目来源
本项目基于 MCP 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 操作: 对所有图元素的完整增删改查支持
可用工具
- create_entities - 在知识图谱中创建新实体
- create_relations - 在实体间创建关系
- add_observations - 向现有实体添加观察
- delete_entities - 删除实体及相关关系
- delete_observations - 从实体中移除特定观察
- delete_relations - 删除特定关系
- read_graph - 读取整个知识图谱
- search_nodes - 按查询字符串搜索实体
- open_nodes - 按名称检索特定实体
安装和使用
安装依赖
cd src/memory-http
pnpm install
构建项目
pnpm build
启动 HTTP 服务器
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 请求头进行会话管理。
健康检查示例
curl http://localhost:3002/health
响应示例：
{
"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. 启动服务器
cd src/memory-http
pnpm start
服务器将在 http://localhost:3002/mcp 启动。
2. 使用 cURL 测试
初始化会话
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。
创建实体
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年"]
}
]
}
}
}'
创建关系
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": "在...工作"
}
]
}
}
}'
查询知识图谱
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"
}
}'
搜索实体
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": "软件工程师"
}
}
}'
添加观察
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 文件内容：
cat src/memory-http/memory.json
示例输出：
{"type":"entity","name":"张三","entityType":"人物","observations":["软件工程师","喜欢编程","在北京工作","精通 TypeScript","有5年工作经验"]}
{"type":"entity","name":"阿里巴巴","entityType":"公司","observations":["中国电商巨头","总部在杭州","成立于1999年"]}
{"type":"relation","from":"张三","to":"阿里巴巴","relationType":"在...工作"}
4. 使用 MCP 客户端连接
如果使用支持 MCP 协议的客户端（如 Claude Desktop），可以在配置中添加：
{
"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 服务器交互：
# 使用 npm 脚本运行测试
pnpm test
# 或者直接运行
npx tsx test-memory-server.ts
TypeScript 测试脚本包含以下测试用例：
- 会话初始化和管理
- 创建实体和关系
- 添加观察数据
- 搜索和查询功能
- 完整的知识图谱读取
- 存储文件验证
6. Bash 测试脚本
也可以使用 Bash 脚本进行测试：
# 使用 npm 脚本运行
pnpm run test:bash
# 或者直接运行
./test-memory-server.sh
运行测试：
chmod +x test-memory-server.sh
./test-memory-server.sh
测试数据示例
测试完成后，memory.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":"开发"}
开发
监视模式
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 项目相同