README.md•17.3 kB
# Memory Bank MCP Server
基于MCP协议的内存银行服务器，支持多项目隔离和Markdown格式文档管理，适用于大型语言模型（LLM）工具调用。
## 功能特点
- **符合MCP协议**: 完全符合Model Context Protocol规范，可被大模型直接调用。
- **多项目隔离**: 支持多个项目隔离管理，各项目任务及进度等信息分开存储。
- **Markdown格式**: 所有项目文档使用Markdown格式存储，易于编辑和维护。
- **Web界面**: 提供直观的Web管理界面，可以查看和编辑项目文档。
- **灵活规则系统**: 支持全局规则和项目特定规则设置，项目规则优先于全局规则。
- **导入导出功能**: 支持项目级别的数据导入和导出。
- **无需数据库**: 使用文件系统进行存储，降低部署门槛。
## 架构设计
Memory Bank MCP Server采用了模块化设计，主要包含以下组件：
- **MCP服务器**: 实现MCP协议，提供工具接口给LLM调用
- **Web服务器**: 提供REST API和前端界面
- **文件存储系统**: 使用JSON文件和Markdown文件进行数据持久化
- **项目管理系统**: 隔离不同项目的数据和规则
## 安装和运行
### 前提条件
- Node.js 16+ (推荐18+)
- npm 7+ 或 yarn 1.22+
### 安装步骤
1. 克隆代码库
```bash
git clone https://github.com/your-username/memory-bank-mcp-server.git
cd memory-bank-mcp-server
```
2. 安装依赖
```bash
npm install
```
3. 构建项目
```bash
npm run build
```
4. 启动服务器
```bash
# 同时启动Web和MCP服务器
npm start
# 仅启动Web服务器
npm start -- web
# 仅启动MCP服务器
npm start -- mcp
```
### 环境变量
可以通过创建`.env`文件或设置环境变量来配置服务器：
```
PORT=3000 # Web服务器端口
ROOT_DIR=/app/data # 数据存储根目录
SESSION_SECRET=your-secret-key # 会话密钥
```
## 数据存储
服务器采用文件系统进行数据存储，主要包含以下文件和目录：
```
data/
├── projects.json # 项目元数据
├── documents.json # 文档元数据
├── rules.json # 规则元数据
├── projects/ # 项目文件目录
│ ├── {project-id}/ # 单个项目目录
│ │ ├── projectbrief.md # 项目概述
│ │ ├── activeContext.md # 当前上下文
│ │ ├── tasks.md # 任务清单
│ │ └── ... # 其他文档
├── templates/ # 文档模板目录
```
### Markdown文件格式
项目文档采用Markdown格式存储，以下是几种主要文档类型：
1. **projectbrief.md** - 项目概述
```markdown
# 项目概述
## 项目名称
## 目标
## 需求
## 技术栈
## 时间线
```
2. **tasks.md** - 任务跟踪
```markdown
# 任务
## 待办任务
- [ ] 任务1
- [ ] 任务2
## 进行中任务
- [ ] 任务3
## 已完成任务
- [x] 任务4
```
## API参考
服务器提供以下主要API接口：
### REST API
#### 项目管理
- `GET /api/projects` - 获取所有项目
- `GET /api/projects/:id` - 获取项目详情
- `POST /api/projects` - 创建新项目
- `PUT /api/projects/:id` - 更新项目
- `DELETE /api/projects/:id` - 删除项目
#### 文档管理
- `GET /api/projects/:projectId/documents` - 获取项目文档列表
- `GET /api/projects/:projectId/documents/:type` - 获取文档内容
- `PUT /api/projects/:projectId/documents/:type` - 更新文档内容
#### 规则管理
- `GET /api/projects/:projectId/rules` - 获取项目规则列表
- `GET /api/rules/:id` - 获取规则内容
- `POST /api/rules` - 创建规则
- `PUT /api/rules/:id` - 更新规则
- `DELETE /api/rules/:id` - 删除规则
### MCP工具接口
服务器提供以下MCP工具接口供大模型调用：
- `list_projects` - 获取所有项目
- `create_project` - 创建新项目
- `update_project` - 更新项目
- `delete_project` - 删除项目
- `list_documents` - 获取项目文档列表
- `get_document` - 获取文档内容
- `update_document` - 更新文档内容
- `list_rules` - 获取项目规则列表
- `get_rule` - 获取规则内容
- `create_rule` - 创建规则
- `update_rule` - 更新规则
- `delete_rule` - 删除规则
## 与Cursor配合使用
### 配置步骤
1. 启动MCP服务器
```bash
npm start -- mcp
```
2. 在Cursor中打开设置，找到"AI设置"
3. 在Tool Providers部分添加自定义工具提供商：
- 名称: Memory Bank
- 描述: 多项目Markdown文档管理工具
- 命令: `node [你的安装路径]/memory-bank-mcp-server/dist/index.js mcp`
- 勾选"启用"
4. 保存设置并重启Cursor
5. 现在你可以在Cursor中使用像这样的命令调用Memory Bank:
```
使用Memory Bank创建一个新项目，名称为"我的项目"，描述为"这是我的第一个项目"
```
## 与cursor-memory-bank的区别与改进
与原始的cursor-memory-bank项目相比，本项目的主要区别和改进包括：
1. **MCP协议支持**: 实现了完整的MCP协议，可以被大模型直接调用
2. **多项目隔离**: 支持管理多个项目，每个项目拥有独立的文档和规则
3. **Web界面**: 提供了可视化的Web管理界面
4. **规则系统**: 支持全局规则和项目特定规则设置
5. **更灵活的文档管理**: 支持自定义文档类型和模板
6. **模块化设计**: 采用模块化架构，易于扩展和维护
## 最佳实践
- **文档命名**: 为每个文档使用清晰、一致的命名约定
- **项目结构**: 为每个项目创建一致的文档结构
- **规则管理**: 在全局规则中设置通用规则，在项目规则中设置特定项目的规则
- **定期备份**: 定期导出项目数据进行备份
- **Markdown格式**: 利用Markdown的格式特性，如标题层级、列表和表格，使文档更有结构
## 注意事项
- 文件修改是立即生效的，无需重启服务器
- 删除项目将删除该项目的所有文档和规则，此操作不可撤销
- 项目ID在创建后不可更改
- 文档内容使用UTF-8编码存储
## 故障排除
- **MCP服务器连接失败**: 检查命令路径是否正确，确保服务器已启动
- **Web界面访问失败**: 检查端口是否被占用，确保服务器已启动
- **文档保存失败**: 检查文件系统权限，确保目录可写
- **导入项目失败**: 检查导入文件格式是否正确
## 未来计划
- 添加用户认证系统
- 支持实时协作编辑
- 增加更多文档类型模板
- 支持文档版本历史
- 添加搜索功能
- 支持更多导入/导出格式
## 许可证
本项目采用MIT许可证，详见[LICENSE](LICENSE)文件。
## 贡献
欢迎提交问题报告、功能建议和代码贡献。请先创建issue讨论您要进行的更改。
### API参考
#### 项目管理
##### 获取所有项目
```
GET /api/projects
```
请求示例:
```javascript
fetch('/api/projects')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": [
{
"id": "project-123",
"name": "示例项目",
"description": "这是一个示例项目",
"createdAt": "2023-11-30T08:15:30Z",
"updatedAt": "2023-11-30T10:22:45Z"
},
{
"id": "project-456",
"name": "测试项目",
"description": "用于测试的项目",
"createdAt": "2023-11-29T14:25:10Z",
"updatedAt": "2023-11-29T16:30:22Z"
}
]
}
```
##### 创建新项目
```
POST /api/projects
```
请求示例:
```javascript
fetch('/api/projects', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '新项目',
description: '这是一个新项目'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "project-789",
"name": "新项目",
"description": "这是一个新项目",
"createdAt": "2023-12-01T09:45:12Z",
"updatedAt": "2023-12-01T09:45:12Z",
"documents": [
"projectbrief.md",
"tasks.md",
"activeContext.md"
]
}
}
```
##### 获取项目详情
```
GET /api/projects/:id
```
请求示例:
```javascript
fetch('/api/projects/project-123')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "project-123",
"name": "示例项目",
"description": "这是一个示例项目",
"createdAt": "2023-11-30T08:15:30Z",
"updatedAt": "2023-11-30T10:22:45Z"
}
}
```
##### 更新项目
```
PUT /api/projects/:id
```
请求示例:
```javascript
fetch('/api/projects/project-123', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '更新的项目名称',
description: '更新的项目描述'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "project-123",
"name": "更新的项目名称",
"description": "更新的项目描述",
"updatedAt": "2023-12-01T11:30:25Z"
}
}
```
##### 删除项目
```
DELETE /api/projects/:id
```
请求示例:
```javascript
fetch('/api/projects/project-123', {
method: 'DELETE'
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"success": true,
"message": "项目删除成功"
}
}
```
#### 文档管理
##### 获取项目文档列表
```
GET /api/projects/:projectId/documents
```
请求示例:
```javascript
fetch('/api/projects/project-123/documents')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": [
{
"id": "doc-001",
"name": "projectbrief.md",
"type": "projectbrief",
"updatedAt": "2023-11-30T09:20:15Z"
},
{
"id": "doc-002",
"name": "tasks.md",
"type": "tasks",
"updatedAt": "2023-11-30T10:15:30Z"
},
{
"id": "doc-003",
"name": "activeContext.md",
"type": "activeContext",
"updatedAt": "2023-11-30T11:05:45Z"
}
]
}
```
##### 获取文档内容
```
GET /api/projects/:projectId/documents/:type
```
请求示例:
```javascript
fetch('/api/projects/project-123/documents/tasks')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "doc-002",
"name": "tasks.md",
"content": "# 任务列表\n\n## 待办任务\n- [ ] [高] 实现用户认证\n- [ ] [中] 添加日志记录\n\n## 进行中任务\n- [-] 完善错误处理 (60%)\n\n## 已完成任务\n- [x] 设计数据模型\n- [x] 创建项目结构",
"type": "tasks",
"updatedAt": "2023-11-30T10:15:30Z",
"html": "<h1>任务列表</h1>..."
}
}
```
##### 更新文档内容
```
PUT /api/projects/:projectId/documents/:type
```
请求示例:
```javascript
fetch('/api/projects/project-123/documents/tasks', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: "# 任务列表\n\n## 待办任务\n- [ ] [高] 实现用户认证\n- [ ] [中] 添加日志记录\n- [ ] [低] 优化性能\n\n## 进行中任务\n- [-] 完善错误处理 (60%)\n\n## 已完成任务\n- [x] 设计数据模型\n- [x] 创建项目结构"
})
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "doc-002",
"name": "tasks.md",
"type": "tasks",
"updatedAt": "2023-12-01T14:25:45Z",
"message": "文档更新成功"
}
}
```
#### 规则管理
##### 获取项目规则列表
```
GET /api/projects/:projectId/rules
```
请求示例:
```javascript
fetch('/api/projects/project-123/rules')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"projectRules": [
{
"id": "rule-001",
"name": "项目规范",
"description": "项目特定的规范",
"isGlobal": false
}
],
"globalRules": [
{
"id": "rule-global-001",
"name": "文档格式",
"description": "Markdown文档格式规范",
"isGlobal": true
},
{
"id": "rule-global-002",
"name": "工作流程",
"description": "标准工作流程规范",
"isGlobal": true
}
]
}
}
```
##### 获取规则内容
```
GET /api/rules/:ruleId
```
请求示例:
```javascript
fetch('/api/rules/rule-001')
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "rule-001",
"name": "项目规范",
"content": "# 项目规范\n\n## 命名规则\n\n1. 文件名使用小写字母和连字符\n2. 变量使用驼峰式命名\n3. 常量使用大写字母和下划线\n\n## 代码风格\n\n1. 使用2个空格缩进\n2. 行末不留空格\n3. 文件末尾保留一个空行",
"description": "项目特定的规范",
"isGlobal": false,
"projectId": "project-123"
}
}
```
##### 创建规则
```
POST /api/rules
```
请求示例:
```javascript
fetch('/api/rules', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '新规则',
content: '# 新规则\n\n## 规则内容\n\n1. 规则项目1\n2. 规则项目2',
isGlobal: false,
projectId: 'project-123',
description: '项目特定的新规则'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "rule-002",
"name": "新规则",
"description": "项目特定的新规则",
"isGlobal": false,
"projectId": "project-123",
"message": "规则创建成功"
}
}
```
##### 更新规则
```
PUT /api/rules/:ruleId
```
请求示例:
```javascript
fetch('/api/rules/rule-001', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: '# 更新的项目规范\n\n## 命名规则\n\n1. 文件名使用小写字母和连字符\n2. 变量使用驼峰式命名\n3. 常量使用大写字母和下划线\n\n## 代码风格\n\n1. 使用2个空格缩进\n2. 行末不留空格\n3. 文件末尾保留一个空行\n\n## 新增部分\n\n1. 新增规则1\n2. 新增规则2',
description: '更新的项目规范描述'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"id": "rule-001",
"name": "项目规范",
"description": "更新的项目规范描述",
"updatedAt": "2023-12-01T16:10:30Z",
"message": "规则更新成功"
}
}
```
##### 删除规则
```
DELETE /api/rules/:ruleId
```
请求示例:
```javascript
fetch('/api/rules/rule-001', {
method: 'DELETE'
})
.then(response => response.json())
.then(data => console.log(data));
```
响应示例:
```json
{
"status": "success",
"data": {
"success": true,
"message": "规则删除成功"
}
}
```
### MCP工具接口
Memory Bank MCP服务器支持通过MCP协议调用以下工具接口：
#### 基础工具
- `list_projects` - 获取所有项目列表
- `create_project` - 创建新项目
- `update_project` - 更新项目信息
- `delete_project` - 删除项目
- `list_documents` - 获取项目文档列表
- `get_document` - 获取文档内容
- `update_document` - 更新文档内容
- `list_rules` - 获取项目规则列表
- `get_rule` - 获取规则内容
- `create_rule` - 创建新规则
- `update_rule` - 更新规则内容
- `delete_rule` - 删除规则
#### 工作流模式工具
##### VAN模式 - 项目验证与初始化
- `van_init` - 初始化项目，如不提供项目名称则使用默认名称
- `van_verify` - 验证项目状态和文件完整性
##### PLAN模式 - 计划制定与任务分解
- `plan_get_tasks` - 获取当前任务列表
- `plan_add_task` - 添加新任务到任务列表
- `plan_update_tasks` - 更新任务规划文档
##### CREATIVE模式 - 创意构思与方案设计
- `creative_add_idea` - 创建创意记录
- `creative_get_ideas` - 获取创意列表
- `creative_update_design` - 更新系统设计文档
##### IMPLEMENT模式 - 实施执行与开发
- `implement_update_progress` - 更新开发进度
- `implement_add_note` - 记录实现细节
- `implement_update_context` - 更新活动上下文文档
##### REFLECT模式 - 回顾反思与改进
- `reflect_create` - 创建项目反思记录
- `reflect_get_history` - 获取历史反思记录
- `reflect_update_progress` - 更新进度文档
##### ARCHIVE模式 - 归档整理与知识沉淀
- `archive_completed_tasks` - 归档已完成任务
- `archive_generate_summary` - 生成项目总结报告
- `archive_export_project` - 导出项目文档
有关每个工具接口的详细使用方法和参数说明，请参阅[使用教程](./public/tutorial.html)。
### 许可证
MIT