MCP Memory Server
標籤式記憶服務器,支持多種傳輸模式的 Model Context Protocol (MCP) 實現。提供LLM長期記憶功能。
🌟 特性
- ✅ Stdio Transport: 穩定的標準輸入輸出傳輸模式(推薦)
- 🧪 HTTP Transport: 實驗性的 HTTP 流式傳輸模式
- ✅ 標籤管理: 多標籤分類和模糊搜尋
- ✅ 進階查詢: 支持內容、標籤、時間範圍的複雜查詢
- ✅ 分頁支持: 高效處理大量數據
- ✅ 類型安全: 完整的 TypeScript 類型定義
- ✅ 事務處理: 確保數據一致性
- ✅ 批次操作: 優化的批次刪除和查詢
📦 安裝```bash
npm install
npm run build
## 🚀 快速開始
### 環境變數配置
複製 `.env.example` 並根據需求修改:```bash
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:透過環境變數啟動(推薦)```bash
Stdio 模式(本地/CLI 使用,推薦)
TRANSPORT_MODE=stdio npm start
HTTP 模式(實驗性,僅用於測試)
TRANSPORT_MODE=http npm start
#### 方式 2:使用預設腳本```bash
# Stdio 模式
npm run start:stdio
# HTTP 模式
npm run start:http
方式 3:生產環境部署```bash
編譯專案
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 - 儲存記憶```json
{
"name": "remember",
"arguments": {
"tags": ["工作", "會議"],
"content": "討論 Q1 專案進度和資源分配"
}
}
2. forget - 刪除記憶```json
{
"name": "forget",
"arguments": {
"memory_ids": [1, 2, 3]
}
}
### 3. forget_by_tag - 按標籤刪除```json
{
"name": "forget_by_tag",
"arguments": {
"tags": ["過時", "測試"]
}
}
4. update_memory - 更新記憶```json
{
"name": "update_memory",
"arguments": {
"memory_id": 1,
"content": "更新後的內容",
"tags": ["新標籤"]
}
}
### 5. get_memories_by_tag - 按標籤查詢```json
{
"name": "get_memories_by_tag",
"arguments": {
"tags": ["工作"],
"page": 1,
"pageSize": 10
}
}
6. get_memories - 進階查詢
支持複雜的查詢語法:```json
{
"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 - 列出標籤```json
{
"name": "list_tags",
"arguments": {
"query": "工作"
}
}
⚙️ 配置
創建 .env 文件(參考 .env.example):```env
資料庫
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。
### 快速範例
#### 健康檢查```bash
curl http://localhost:3000/health
連接 MCP Stream```bash
curl -N http://localhost:3000/mcp
#### 測試服務器```bash
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 模式```bash
docker build -t mcp-memory-server .
docker run -it mcp-memory-server
HTTP 模式```bash
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` 避免鎖定
## 🔒 安全建議
1. **HTTP 模式**: 在生產環境使用 HTTPS
2. **驗證**: 所有輸入通過 Zod 驗證
3. **限速**: 考慮添加 rate limiting
4. **認證**: 添加 API 認證機制
5. **隔離**: 將資料庫與公網隔離
## 📝 開發指南
### 代碼檢查```bash
npm run build
測試```bash
啟動 HTTP 服務器
npm run start:http
在另一個終端運行測試
node test-http.js
### 調試
使用 VS Code 的 launch.json:```json
{
"name": "Launch via NPM",
"request": "launch",
"runtimeArgs": ["ts-node", "${workspaceFolder}/src/app.ts"],
"runtimeExecutable": "npx",
"env": {
"DB_PATH": "/Users/your-path/db"
}
}
📄 許可證
- Apache License 2
版本: 1.2.5
更新日期: 2025-11-13
