mempalace-mcp-dev

An MCP (Model Context Protocol) server that gives AI coding assistants grounded, branch-scoped context about your codebase. It provides semantic code search via my MemPalace fork, git change tracking, a persistent change ledger, TypeScript/Jest dev lifecycle tools, and a built-in Project Tracks (Conductor) methodology for structured feature work.

Features

Prerequisites

• Node.js ≥ 18

• Python ≥ 3.9

• A git repository to point at

Important: MemPalace Fork Required

⚠️ This MCP server requires a custom fork of MemPalace with multi-branch exclude-patterns support. The official pip install mempalace package will not work — you must use my fork (branch feat/exclude-patterns-config).

The easiest way to get this set up is the setup script (see Quick Start).

Quick Start

1. Run the setup script (recommended)

The fastest way to get up and running is the bootstrap script at scripts/setup-mempalace.sh. It handles the entire MemPalace setup:

• Clones my fork with the required exclude-patterns support

• Creates a Python virtual environment

• Installs the fork in editable mode

• Symlinks the mempalace CLI to ~/.local/bin

• Prepares the palace data directory

• Optionally runs the initial codebase index

# From the repo root:
./scripts/setup-mempalace.sh

# To also index your codebase right away:
./scripts/setup-mempalace.sh --mine

The script is fully configurable via environment variables:

After the script finishes, check that everything works:

mempalace --version
mempalace --palace ~/.mempalace/active status

2. Clone and build the MCP server

This is not published to npm. Clone and build locally:

git clone https://github.com/2loch-ness6/mempalace-mcp-dev
cd mempalace-mcp-dev
npm install
npm run build

After building, you can use npm link to make mempalace-mcp-dev available globally:

npm link
# Now this works from anywhere:
mempalace-mcp-dev

3. Configure environment variables

export MCP_REPO_DIR=/path/to/your/repo        # defaults to process.cwd()
export MCP_PALACE_DIR=~/.mempalace/active      # MemPalace data directory
export MCP_PALACE_WING=code                    # wing name (namespace) for your repo
export MEMPALACE_PYTHON=/path/to/venv/bin/python3  # python with fork installed

If you used the setup script, set MEMPALACE_PYTHON to $HOME/.mempalace/bin/python3 (or wherever MEMPALACE_VENV_DIR points).

4. Add to your MCP client config

For Claude Desktop and other MCP clients:

{
  "mcpServers": {
    "mempalace-mcp-dev": {
      "command": "node",
      "args": ["/path/to/mempalace-mcp-dev/dist/index.js"],
      "env": {
        "MCP_REPO_DIR": "/path/to/your/repo",
        "MCP_PALACE_DIR": "/home/you/.mempalace/active",
        "MCP_PALACE_WING": "code",
        "MEMPALACE_PYTHON": "/home/you/.mempalace/bin/python3"
      }
    }
  }
}

If you ran npm link, you can also use the shorter form:

{
  "mcpServers": {
    "mempalace-mcp-dev": {
      "command": "mempalace-mcp-dev",
      "env": {
        "MCP_REPO_DIR": "/path/to/your/repo",
        "MCP_PALACE_DIR": "/home/you/.mempalace/active",
        "MCP_PALACE_WING": "code",
        "MEMPALACE_PYTHON": "python3"
      }
    }
  }
}

Environment Variables

MCP Tools Reference

Code Search

Branch & Git

Change Ledger

Dev Lifecycle

Project Tracks (Conductor)

Project Tracks Methodology (Conductor)

Project Tracks is a lightweight, file-based feature management system. Each track is a directory containing up to four files:

conductor/tracks/
└── my-feature-20260501/
    ├── plan.md       ← living task list; the status source of truth
    ├── spec.md       ← technical spec, design decisions, acceptance criteria
    ├── index.md      ← short summary and linked resources
    └── metadata.json ← machine-readable metadata (id, owner, status, dates)

Rules:

• A directory is a live track only if it contains plan.md.

• plan.md is always read/written live from disk (never via MemPalace — no staleness).

• Track slugs must match [a-zA-Z0-9][a-zA-Z0-9_-]* (max 100 chars).

Bootstrapping tracks in a new project:

# Create the tracks directory
mkdir -p conductor/tracks

# Use the MCP tool to scaffold a track
# (or copy from templates/track/ in this package)

Template files are included in templates/track/ for manual scaffolding.

MemPalace Configuration (mempalace.yaml)

Place a mempalace.yaml at the root of MCP_REPO_DIR to control how files are indexed. A generic example is provided in mempalace.yaml.example.

Key sections:

• wing — must match MCP_PALACE_WING

• exclude_patterns — gitignore-syntax patterns to skip during mining

• rooms — semantic routing rules (keyword → room name) for search scoping

Development

git clone https://github.com/2loch-ness6/mempalace-mcp-dev
cd mempalace-mcp-dev
npm install
npm run build
npm test

See CONTRIBUTING.md for contribution guidelines.

License

MIT — see LICENSE.