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