使用说明
MCP Memory Server
標籤式記憶服務器，支持多種傳輸模式的 Model Context Protocol (MCP) 實現。提供LLM長期記憶功能。
🌟 特性
- ✅ Stdio Transport: 穩定的標準輸入輸出傳輸模式（推薦）
- 🧪 HTTP Transport: 實驗性的 HTTP 流式傳輸模式
- ✅ 標籤管理: 多標籤分類和模糊搜尋
- ✅ 進階查詢: 支持內容、標籤、時間範圍的複雜查詢
- ✅ 分頁支持: 高效處理大量數據
- ✅ 類型安全: 完整的 TypeScript 類型定義
- ✅ 事務處理: 確保數據一致性
- ✅ 批次操作: 優化的批次刪除和查詢
📦 安裝
npm install
npm run build
🚀 快速開始
環境變數配置
複製 .env.example 並根據需求修改：
cp .env.example .env
關鍵環境變數：
TRANSPORT_MODE: 設定傳輸模式 (stdio或http)HTTP_PORT: HTTP 服務器端口（預設：3000）HTTP_HOST: HTTP 服務器主機（預設：0.0.0.0）ENABLE_CORS: 是否啟用 CORS（預設：true）
使用方式
⚠️ 重要提示
HTTP Transport 目前為實驗性功能，MCP 協議訊息處理尚未完整實現。
生產環境建議使用 Stdio Transport (TRANSPORT_MODE=stdio)。
方式 1：透過環境變數啟動（推薦）
# Stdio 模式（本地/CLI 使用，推薦）
TRANSPORT_MODE=stdio npm start
# HTTP 模式（實驗性，僅用於測試）
TRANSPORT_MODE=http npm start
方式 2：使用預設腳本
# Stdio 模式
npm run start:stdio
# HTTP 模式
npm run start:http
方式 3：生產環境部署
# 編譯專案
npm run build
# 啟動 Stdio 模式
npm run node:stdio
# 啟動 HTTP 模式
npm run node:http
HTTP 模式端點
⚠️ HTTP Transport 限制
目前 HTTP 模式僅提供健康檢查端點，完整的 MCP 協議支援正在開發中。
當使用 HTTP 模式時，服務器將提供以下端點：
- 健康檢查:
GET http://localhost:3000/health✅ 可用 - MCP Stream:
GET http://localhost:3000/mcp✅ 可用 - MCP 訊息:
POST http://localhost:3000/mcp/{sessionId}✅ 可用
🛠️ 可用工具
1. remember - 儲存記憶
{
"name": "remember",
"arguments": {
"tags": ["工作", "會議"],
"content": "討論 Q1 專案進度和資源分配"
}
}
2. forget - 刪除記憶
{
"name": "forget",
"arguments": {
"memory_ids": [1, 2, 3]
}
}
3. forget_by_tag - 按標籤刪除
{
"name": "forget_by_tag",
"arguments": {
"tags": ["過時", "測試"]
}
}
4. update_memory - 更新記憶
{
"name": "update_memory",
"arguments": {
"memory_id": 1,
"content": "更新後的內容",
"tags": ["新標籤"]
}
}
5. get_memories_by_tag - 按標籤查詢
{
"name": "get_memories_by_tag",
"arguments": {
"tags": ["工作"],
"page": 1,
"pageSize": 10
}
}
6. get_memories - 進階查詢
支持複雜的查詢語法：
{
"name": "get_memories",
"arguments": {
"query": "(content=\"報告\" AND tag=工作) OR timespan=2025-01-01..2025-01-31",
"page": 1,
"pageSize": 10
}
}
查詢語法：
content=關鍵字- 內容搜尋tag=標籤- 標籤搜尋（模糊比對）timespan=日期- 時間範圍YYYY-MM-DD..YYYY-MM-DD- 日期範圍>=YYYY-MM-DD- 大於等於<=YYYY-MM-DD- 小於等於>YYYY-MM-DD- 大於<YYYY-MM-DD- 小於YYYY-MM-DD- 當日
- 支持
AND、OR和括號巢狀
7. list_tags - 列出標籤
{
"name": "list_tags",
"arguments": {
"query": "工作"
}
}
⚙️ 配置
創建 .env 文件（參考 .env.example）：
# 資料庫
DB_PATH=/path/to/database
# HTTP 服務器（僅 HTTP 模式需要）
HTTP_PORT=3000
HTTP_HOST=0.0.0.0
ENABLE_CORS=true
# 限制
MAX_TAGS=10
MAX_CONTENT_LENGTH=10000
MAX_PAGE_SIZE=100
DEFAULT_PAGE_SIZE=10
🌐 HTTP API 使用
詳細的 HTTP API 文檔請參考 HTTP-README.md。
快速範例
健康檢查
curl http://localhost:3000/health
連接 MCP Stream
curl -N http://localhost:3000/mcp
測試服務器
node test-http.js
🏗️ 架構
src/
├── app.ts # Stdio 模式入口
├── http-server.ts # HTTP 模式入口
├── config/
│ └── index.ts # 配置管理
├── constants/
│ └── messages.ts # 訊息常數
├── helpers/
│ └── database.ts # 資料庫輔助
├── schemas/
│ └── validation.ts # Zod 驗證
├── services/
│ └── DatabaseManager.ts # 資料庫管理
├── types/
│ └── database.ts # 類型定義
└── utils/
├── Pagination.ts # 分頁工具
├── QueryParser.ts # 查詢解析
├── ResponseFormatter.ts # 回應格式化
└── TransactionHelper.ts # 事務處理
🐳 Docker 部署
Stdio 模式
docker build -t mcp-memory-server .
docker run -it mcp-memory-server
HTTP 模式
docker run -d \
-p 3000:3000 \
-e HTTP_PORT=3000 \
-v $(pwd)/db:/root/node/db \
--name mcp-http \
mcp-memory-server \
npx ts-node src/http-server.ts
📊 效能特性
- ✅ 批次操作: 批次刪除減少 90%+ 查詢次數
- ✅ N+1 查詢優化: 使用 JOIN 一次查詢所有標籤
- ✅ WAL 模式: 提升併發效能 30-50%
- ✅ 連接池: 配置
busy_timeout避免鎖定
🔒 安全建議
- HTTP 模式: 在生產環境使用 HTTPS
- 驗證: 所有輸入通過 Zod 驗證
- 限速: 考慮添加 rate limiting
- 認證: 添加 API 認證機制
- 隔離: 將資料庫與公網隔離
📝 開發指南
代碼檢查
npm run build
測試
# 啟動 HTTP 服務器
npm run start:http
# 在另一個終端運行測試
node test-http.js
調試
使用 VS Code 的 launch.json：
{
"name": "Launch via NPM",
"request": "launch",
"runtimeArgs": ["ts-node", "${workspaceFolder}/src/app.ts"],
"runtimeExecutable": "npx",
"env": {
"DB_PATH": "/Users/your-path/db"
}
}
📄 許可證
版本: 1.2.5
更新日期: 2025-11-13
