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 操作: 对所有图元素的完整增删改查支持

可用工具

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 - 按名称检索特定实体

安装和使用

安装依赖

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 项目相同