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

MIT