Content
# Memory Bank MCP Server
A memory bank server based on the MCP protocol, supporting multi-project isolation and Markdown format document management, suitable for large language model (LLM) tool calls.
## Features
- **MCP Protocol Compliance**: Fully compliant with the Model Context Protocol specification, can be directly called by large models.
- **Multi-Project Isolation**: Supports isolated management of multiple projects, with separate storage for tasks and progress information for each project.
- **Markdown Format**: All project documents are stored in Markdown format, making them easy to edit and maintain.
- **Web Interface**: Provides an intuitive web management interface for viewing and editing project documents.
- **Flexible Rules System**: Supports global rules and project-specific rule settings, with project rules taking precedence over global rules.
- **Import and Export Functionality**: Supports data import and export at the project level.
- **No Database Required**: Uses the file system for storage, lowering deployment barriers.
## Architecture Design
The Memory Bank MCP Server adopts a modular design, mainly consisting of the following components:
- **MCP Server**: Implements the MCP protocol, providing tool interfaces for LLM calls.
- **Web Server**: Provides REST API and frontend interface.
- **File Storage System**: Uses JSON files and Markdown files for data persistence.
- **Project Management System**: Isolates data and rules for different projects.
## Installation and Running
### Prerequisites
- Node.js 16+ (recommended 18+)
- npm 7+ or yarn 1.22+
### Installation Steps
1. Clone the repository
```bash
git clone https://github.com/your-username/memory-bank-mcp-server.git
cd memory-bank-mcp-server
```
2. Install dependencies
```bash
npm install
```
3. Build the project
```bash
npm run build
```
4. Start the server
```bash
# Start both Web and MCP servers
npm start
# Start only the Web server
npm start -- web
# Start only the MCP server
npm start -- mcp
```
### Environment Variables
You can configure the server by creating a `.env` file or setting environment variables:
```
PORT=3000 # Web server port
ROOT_DIR=/app/data # Data storage root directory
SESSION_SECRET=your-secret-key # Session secret key
```
## Data Storage
The server uses the file system for data storage, mainly consisting of the following files and directories:
```
data/
├── projects.json # Project metadata
├── documents.json # Document metadata
├── rules.json # Rule metadata
├── projects/ # Project file directory
│ ├── {project-id}/ # Individual project directory
│ │ ├── projectbrief.md # Project overview
│ │ ├── activeContext.md # Current context
│ │ ├── tasks.md # Task list
│ │ └── ... # Other documents
├── templates/ # Document template directory
```
### Markdown File Format
Project documents are stored in Markdown format, with the following main document types:
1. **projectbrief.md** - Project Overview
```markdown
# Project Overview
## Project Name
## Goals
## Requirements
## Tech Stack
## Timeline
```
2. **tasks.md** - Task Tracking
```markdown
# Tasks
## To-Do Tasks
- [ ] Task 1
- [ ] Task 2
## In-Progress Tasks
- [ ] Task 3
## Completed Tasks
- [x] Task 4
```
## API Reference
The server provides the following main API interfaces:
### REST API
#### Project Management
- `GET /api/projects` - Get all projects
- `GET /api/projects/:id` - Get project details
- `POST /api/projects` - Create a new project
- `PUT /api/projects/:id` - Update a project
- `DELETE /api/projects/:id` - Delete a project
#### Document Management
- `GET /api/projects/:projectId/documents` - Get project document list
- `GET /api/projects/:projectId/documents/:type` - Get document content
- `PUT /api/projects/:projectId/documents/:type` - Update document content
#### Rule Management
- `GET /api/projects/:projectId/rules` - Get project rule list
- `GET /api/rules/:id` - Get rule content
- `POST /api/rules` - Create a rule
- `PUT /api/rules/:id` - Update a rule
- `DELETE /api/rules/:id` - Delete a rule
### MCP Tool Interfaces
The server provides the following MCP tool interfaces for large model calls:
- `list_projects` - Get all projects
- `create_project` - Create a new project
- `update_project` - Update a project
- `delete_project` - Delete a project
- `list_documents` - Get project document list
- `get_document` - Get document content
- `update_document` - Update document content
- `list_rules` - Get project rule list
- `get_rule` - Get rule content
- `create_rule` - Create a rule
- `update_rule` - Update a rule
- `delete_rule` - Delete a rule
## Using with Cursor
### Configuration Steps
1. Start the MCP server
```bash
npm start -- mcp
```
2. Open settings in Cursor and find "AI Settings"
3. In the Tool Providers section, add a custom tool provider:
- Name: Memory Bank
- Description: Multi-project Markdown document management tool
- Command: `node [your installation path]/memory-bank-mcp-server/dist/index.js mcp`
- Check "Enable"
4. Save the settings and restart Cursor
5. Now you can use commands like this in Cursor to call Memory Bank:
```
Create a new project in Memory Bank named "My Project" with the description "This is my first project"
```
## Differences and Improvements from cursor-memory-bank
Compared to the original cursor-memory-bank project, the main differences and improvements in this project include:
1. **MCP Protocol Support**: Implemented complete MCP protocol, can be directly called by large models.
2. **Multi-Project Isolation**: Supports managing multiple projects, each with independent documents and rules.
3. **Web Interface**: Provides a visual web management interface.
4. **Rules System**: Supports global rules and project-specific rule settings.
5. **More Flexible Document Management**: Supports custom document types and templates.
6. **Modular Design**: Adopts a modular architecture, easy to extend and maintain.
## Best Practices
- **Document Naming**: Use clear and consistent naming conventions for each document.
- **Project Structure**: Create a consistent document structure for each project.
- **Rule Management**: Set general rules in global rules and specific project rules in project rules.
- **Regular Backups**: Regularly export project data for backup.
- **Markdown Format**: Utilize Markdown's formatting features, such as heading levels, lists, and tables, to make documents more structured.
## Notes
- File modifications take effect immediately, no server restart required.
- Deleting a project will remove all documents and rules associated with that project; this action cannot be undone.
- Project IDs cannot be changed after creation.
- Document content is stored using UTF-8 encoding.
## Troubleshooting
- **MCP Server Connection Failed**: Check if the command path is correct and ensure the server is running.
- **Web Interface Access Failed**: Check if the port is occupied and ensure the server is running.
- **Document Save Failed**: Check file system permissions to ensure the directory is writable.
- **Project Import Failed**: Check if the import file format is correct.
## Future Plans
- Add user authentication system
- Support real-time collaborative editing
- Add more document type templates
- Support document version history
- Add search functionality
- Support more import/export formats
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Contribution
Contributions, issue reports, and feature suggestions are welcome. Please create an issue to discuss the changes you want to make.
### API Reference
#### Project Management
##### Get All Projects
```
GET /api/projects
```
Request Example:
```javascript
fetch('/api/projects')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": [
{
"id": "project-123",
"name": "Example Project",
"description": "This is an example project",
"createdAt": "2023-11-30T08:15:30Z",
"updatedAt": "2023-11-30T10:22:45Z"
},
{
"id": "project-456",
"name": "Test Project",
"description": "Project for testing",
"createdAt": "2023-11-29T14:25:10Z",
"updatedAt": "2023-11-29T16:30:22Z"
}
]
}
```
##### Create New Project
```
POST /api/projects
```
Request Example:
```javascript
fetch('/api/projects', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'New Project',
description: 'This is a new project'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "project-789",
"name": "New Project",
"description": "This is a new project",
"createdAt": "2023-12-01T09:45:12Z",
"updatedAt": "2023-12-01T09:45:12Z",
"documents": [
"projectbrief.md",
"tasks.md",
"activeContext.md"
]
}
}
```
##### Get Project Details
```
GET /api/projects/:id
```
Request Example:
```javascript
fetch('/api/projects/project-123')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "project-123",
"name": "Example Project",
"description": "This is an example project",
"createdAt": "2023-11-30T08:15:30Z",
"updatedAt": "2023-11-30T10:22:45Z"
}
}
```
##### Update Project
```
PUT /api/projects/:id
```
Request Example:
```javascript
fetch('/api/projects/project-123', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Updated Project Name',
description: 'Updated project description'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "project-123",
"name": "Updated Project Name",
"description": "Updated project description",
"updatedAt": "2023-12-01T11:30:25Z"
}
}
```
##### Delete Project
```
DELETE /api/projects/:id
```
Request Example:
```javascript
fetch('/api/projects/project-123', {
method: 'DELETE'
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"success": true,
"message": "Project deleted successfully"
}
}
```
#### Document Management
##### Get Project Document List
```
GET /api/projects/:projectId/documents
```
Request Example:
```javascript
fetch('/api/projects/project-123/documents')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```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 Document Content
```
GET /api/projects/:projectId/documents/:type
```
Request Example:
```javascript
fetch('/api/projects/project-123/documents/tasks')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "doc-002",
"name": "tasks.md",
"content": "# Task List\n\n## To-Do Tasks\n- [ ] [High] Implement user authentication\n- [ ] [Medium] Add logging\n\n## In-Progress Tasks\n- [-] Improve error handling (60%)\n\n## Completed Tasks\n- [x] Design data model\n- [x] Create project structure",
"type": "tasks",
"updatedAt": "2023-11-30T10:15:30Z",
"html": "<h1>Task List</h1>..."
}
}
```
##### Update Document Content
```
PUT /api/projects/:projectId/documents/:type
```
Request Example:
```javascript
fetch('/api/projects/project-123/documents/tasks', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: "# Task List\n\n## To-Do Tasks\n- [ ] [High] Implement user authentication\n- [ ] [Medium] Add logging\n- [ ] [Low] Optimize performance\n\n## In-Progress Tasks\n- [-] Improve error handling (60%)\n\n## Completed Tasks\n- [x] Design data model\n- [x] Create project structure"
})
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "doc-002",
"name": "tasks.md",
"type": "tasks",
"updatedAt": "2023-12-01T14:25:45Z",
"message": "Document updated successfully"
}
}
```
#### Rule Management
##### Get Project Rule List
```
GET /api/projects/:projectId/rules
```
Request Example:
```javascript
fetch('/api/projects/project-123/rules')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"projectRules": [
{
"id": "rule-001",
"name": "Project Specifications",
"description": "Project-specific specifications",
"isGlobal": false
}
],
"globalRules": [
{
"id": "rule-global-001",
"name": "Document Format",
"description": "Markdown document format specifications",
"isGlobal": true
},
{
"id": "rule-global-002",
"name": "Workflow",
"description": "Standard workflow specifications",
"isGlobal": true
}
]
}
}
```
##### Get Rule Content
```
GET /api/rules/:ruleId
```
Request Example:
```javascript
fetch('/api/rules/rule-001')
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "rule-001",
"name": "Project Specifications",
"content": "# Project Specifications\n\n## Naming Conventions\n\n1. Use lowercase letters and hyphens for file names\n2. Use camelCase for variables\n3. Use uppercase letters and underscores for constants\n\n## Code Style\n\n1. Use 2 spaces for indentation\n2. No trailing spaces at the end of lines\n3. Keep one blank line at the end of files",
"description": "Project-specific specifications",
"isGlobal": false,
"projectId": "project-123"
}
}
```
##### Create Rule
```
POST /api/rules
```
Request Example:
```javascript
fetch('/api/rules', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'New Rule',
content: '# New Rule\n\n## Rule Content\n\n1. Rule item 1\n2. Rule item 2',
isGlobal: false,
projectId: 'project-123',
description: 'New project-specific rule'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "rule-002",
"name": "New Rule",
"description": "New project-specific rule",
"isGlobal": false,
"projectId": "project-123",
"message": "Rule created successfully"
}
}
```
##### Update Rule
```
PUT /api/rules/:ruleId
```
Request Example:
```javascript
fetch('/api/rules/rule-001', {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: '# Updated Project Specifications\n\n## Naming Conventions\n\n1. Use lowercase letters and hyphens for file names\n2. Use camelCase for variables\n3. Use uppercase letters and underscores for constants\n\n## Code Style\n\n1. Use 2 spaces for indentation\n2. No trailing spaces at the end of lines\n3. Keep one blank line at the end of files\n\n## New Sections\n\n1. New rule 1\n2. New rule 2',
description: 'Updated project specifications description'
})
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"id": "rule-001",
"name": "Project Specifications",
"description": "Updated project specifications description",
"updatedAt": "2023-12-01T16:10:30Z",
"message": "Rule updated successfully"
}
}
```
##### Delete Rule
```
DELETE /api/rules/:ruleId
```
Request Example:
```javascript
fetch('/api/rules/rule-001', {
method: 'DELETE'
})
.then(response => response.json())
.then(data => console.log(data));
```
Response Example:
```json
{
"status": "success",
"data": {
"success": true,
"message": "Rule deleted successfully"
}
}
```
### MCP Tool Interfaces
The Memory Bank MCP server supports calling the following tool interfaces via the MCP protocol:
#### Basic Tools
- `list_projects` - Get the list of all projects
- `create_project` - Create a new project
- `update_project` - Update project information
- `delete_project` - Delete a project
- `list_documents` - Get the list of project documents
- `get_document` - Get document content
- `update_document` - Update document content
- `list_rules` - Get the list of project rules
- `get_rule` - Get rule content
- `create_rule` - Create a new rule
- `update_rule` - Update rule content
- `delete_rule` - Delete a rule
#### Workflow Mode Tools
##### VAN Mode - Project Verification and Initialization
- `van_init` - Initialize a project; if no project name is provided, use the default name.
- `van_verify` - Verify project status and file integrity.
##### PLAN Mode - Planning and Task Breakdown
- `plan_get_tasks` - Get the current task list.
- `plan_add_task` - Add a new task to the task list.
- `plan_update_tasks` - Update the task planning document.
##### CREATIVE Mode - Idea Generation and Design
- `creative_add_idea` - Create an idea record.
- `creative_get_ideas` - Get the list of ideas.
- `creative_update_design` - Update the system design document.
##### IMPLEMENT Mode - Implementation and Development
- `implement_update_progress` - Update development progress.
- `implement_add_note` - Record implementation details.
- `implement_update_context` - Update the active context document.
##### REFLECT Mode - Review and Improvement
- `reflect_create` - Create a project reflection record.
- `reflect_get_history` - Get historical reflection records.
- `reflect_update_progress` - Update progress documents.
##### ARCHIVE Mode - Archiving and Knowledge Accumulation
- `archive_completed_tasks` - Archive completed tasks.
- `archive_generate_summary` - Generate project summary report.
- `archive_export_project` - Export project documents.
For detailed usage and parameter descriptions of each tool interface, please refer to the [Usage Tutorial](./public/tutorial.html).
### License
MIT
