npm package: @nicavcrm/memory-bank-mcp
Description: Memory Bank MCP Server with VAN, PLAN, CREATIVE, IMPLEMENT, and REFLECT+ARCHIVE modes
Author: Nick Cao
Latest version: 1.0.1

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

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

### Option 1: Use with npx (Recommended)

No installation required! Use directly with npx:

```bash
npx -y @nicavcrm/memory-bank-mcp
```

### Option 2: Install globally

```bash
npm install -g @nicavcrm/memory-bank-mcp
```

### Option 3: Install locally for development

```bash
git clone <your-repo-url>
cd memory-bank-mcp
npm install
npm run build
```

## MCP Client Configuration

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}
```

### Cursor IDE

Add to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}
```

### VS Code

Install an MCP extension for VS Code and add this to your settings:

```json
{
  "mcp.servers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}
```

### Other MCP Clients

Use the npx command with your MCP client:
- **Command**: `npx`
- **Args**: `["-y", "@nicavcrm/memory-bank-mcp"]`

## Quick Start

1. **Add to your MCP client** using the configuration examples above
2. **Start a new project** using the `van_mode` tool:
   ```json
   {
     "name": "van_mode",
     "arguments": {
       "complexity": "2",
       "task_description": "Fix login bug in user authentication"
     }
   }
   ```
3. **Follow the suggested workflow** - the tool will guide you through PLAN → IMPLEMENT → REFLECT+ARCHIVE modes
4. **Access your Memory Bank files** in the `.memory_bank/` directory for documentation and progress tracking

See the [DEMO.md](DEMO.md) file for complete workflow examples.

## Usage

### With MCP Clients

The Memory Bank server is designed to work with MCP (Model Context Protocol) clients like Claude Desktop, Cursor IDE, or custom MCP implementations. Once configured (see installation section above), the tools will be available in your MCP client.

### Development Mode (Local)

If you're developing or running locally:

```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

ISC