Memory Bank MCP Server

A Model Context Protocol (MCP) server implementing the Memory Bank system based on the cursor-memory-bank custom modes.

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

npm install
npm run build

Usage

Running the Server

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:

{
  "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:

{
  "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

# 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

# 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"

# 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:

# 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 project by vanzan01, adapted for use as an MCP server.

License

ISC