README.md•6.08 kB
# Memory Bank MCP Server
A Model Context Protocol (MCP) server implementing the Memory Bank system based on the [cursor-memory-bank](https://github.com/vanzan01/cursor-memory-bank) custom modes.
<a href="https://glama.ai/mcp/servers/@nicavcrm/memory-bank-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@nicavcrm/memory-bank-mcp/badge" alt="Memory Bank Server MCP server" />
</a>
## Overview
This MCP server provides structured workflow tools for managing software development projects through different complexity levels and phases:
- **VAN Mode**: Project initialization and complexity assessment
- **PLAN Mode**: Detailed implementation planning
- **CREATIVE Mode**: Design and architecture decisions
- **IMPLEMENT Mode**: Code implementation and execution
- **REFLECT+ARCHIVE Mode**: Project reflection and documentation archiving
## Features
### 🎯 **VAN Mode** (Entry Point)
- Initialize new projects with complexity levels 1-4
- Set up Memory Bank file structure
- Determine appropriate next mode based on complexity
### 📋 **PLAN Mode** (Planning)
- Generate implementation plans based on complexity level
- Create detailed step-by-step approaches
- Identify components requiring creative phases
### 🎨 **CREATIVE Mode** (Design)
- Architecture design with multiple options analysis
- Algorithm design with complexity considerations
- UI/UX design with accessibility and usability focus
- Structured documentation of design decisions
### ⚒️ **IMPLEMENT Mode** (Execution)
- Phase-based implementation for complex projects
- Integration testing and documentation
- Progress tracking and status updates
### 🤔 **REFLECT+ARCHIVE Mode** (Completion)
- Implementation reflection and lessons learned
- Complete project archiving
- Preparation for next task initialization
## Installation
```bash
npm install
npm run build
```
## Usage
### Running the Server
```bash
npm start
```
### Available Tools
#### 1. `van_mode`
Initialize a project with complexity assessment.
**Parameters:**
- `complexity` (required): "1" | "2" | "3" | "4"
- Level 1: Quick bug fix
- Level 2: Simple enhancement
- Level 3: Complex feature
- Level 4: Major feature/refactor
- `task_description` (optional): Description of the task
**Example:**
```json
{
"complexity": "3",
"task_description": "Implement user authentication system"
}
```
#### 2. `plan_mode`
Create detailed implementation plan.
**Parameters:**
- `complexity` (optional): Complexity level (reads from tasks.md if not provided)
#### 3. `creative_mode`
Perform design and architecture work.
**Parameters:**
- `component_name` (required): Name of component requiring design
- `creative_type` (required): "architecture" | "algorithm" | "uiux"
- `requirements` (required): Requirements and constraints
**Example:**
```json
{
"component_name": "user_auth_system",
"creative_type": "architecture",
"requirements": "Secure authentication with JWT tokens, OAuth integration, and role-based access control"
}
```
#### 4. `implement_mode`
Execute implementation based on plan.
**Parameters:**
- `phase` (optional): Implementation phase for complex projects
- `complexity` (optional): Complexity level (reads from tasks.md if not provided)
#### 5. `reflect_archive_mode`
Reflect on implementation and archive documentation.
**Parameters:**
- `action` (required): "reflect" | "archive"
- "reflect": Review and document implementation experience
- "archive": Create final documentation archive
## Memory Bank Files
The server creates and manages several files in the `.memory_bank` directory:
- `tasks.md`: Main task tracking and status
- `activeContext.md`: Current context and focus
- `progress.md`: Implementation progress tracking
- `implementation-plan.md`: Detailed implementation plan
- `reflection.md`: Post-implementation reflection
- `creative-{component}.md`: Creative phase documentation
- `docs/archive/project-archive.md`: Final project archive
## Workflow Example
```bash
# 1. Initialize project
van_mode(complexity="3", task_description="Build REST API")
# 2. Create implementation plan
plan_mode()
# 3. Design complex components (if Level 3-4)
creative_mode(component_name="api_architecture", creative_type="architecture", requirements="...")
# 4. Implement the solution
implement_mode(phase="core_components")
# 5. Reflect and archive
reflect_archive_mode(action="reflect")
reflect_archive_mode(action="archive")
```
## Complexity Levels
- **Level 1**: Quick bug fixes - Direct implementation, minimal planning
- **Level 2**: Simple enhancements - Streamlined planning, straightforward implementation
- **Level 3**: Complex features - Comprehensive planning, creative phases may be required
- **Level 4**: Major features/refactors - Detailed architecture, phased implementation, creative design required
## Development
```bash
# Development mode with auto-reload
npm run dev
# Build TypeScript
npm run build
# Run compiled server
npm start
```
## Troubleshooting
### Module Resolution Errors
If you encounter `ERR_MODULE_NOT_FOUND` errors when running the server, ensure:
1. **Build First**: Always run `npm run build` before `npm start`
2. **ES Module Imports**: All imports in source files use `.js` extensions
3. **TypeScript Config**: The `tsconfig.json` is configured for ES modules with `"module": "ESNext"`
```bash
# Clean build if issues persist
rm -rf dist/
npm run build
npm start
```
### Memory Bank Directory Permissions
If the server can't create the `.memory_bank` directory:
```bash
# Ensure write permissions in the working directory
chmod 755 .
```
## Integration
This MCP server can be integrated with:
- **Claude Desktop**: Add to MCP server configuration
- **Cursor IDE**: Use with MCP client capabilities
- **VS Code**: Through MCP extensions
- **Custom clients**: Any MCP-compatible application
## Based On
This implementation is based on the excellent [cursor-memory-bank](https://github.com/vanzan01/cursor-memory-bank) project by vanzan01, adapted for use as an MCP server.
## License
MIT