@mempalace/mcp-dev

一个 MCP (Model Context Protocol) 服务器，为 AI 编码助手提供关于代码库的、基于分支范围的扎实上下文。它通过 MemPalace 提供语义代码搜索、Git 变更跟踪、持久化变更分类账、TypeScript/Jest 开发生命周期工具，以及用于结构化功能工作的内置 Project Tracks (Conductor) 方法论。

功能特性

功能	描述
语义代码搜索	通过 MemPalace 嵌入对已索引代码库进行自然语言查询
分支上下文	当前分支、SHA、最近提交 — 始终保持同步
变更分类账	每次 AI 辅助变更的仅追加 JSONL 日志，包含完整来源
开发生命周期	在 MCP 客户端内运行 `tsc` 类型检查和 Jest 测试
Git diff	完整或文件范围的 diff 输出
Project Tracks	创建并管理基于 Markdown 的功能跟踪（计划/规范/索引/元数据）

前置要求

Node.js ≥ 18
Python ≥ 3.9，并安装了 MemPalace
一个指向的 Git 仓库

安装 MemPalace

pip install mempalace
# or from the fork with exclude-patterns support:
pip install git+https://github.com/2loch-ness6/mempalace@feat/exclude-patterns-config

快速开始

1. 安装 MCP 服务器

npm install -g @mempalace/mcp-dev

或者通过 npx 在不安装的情况下使用：

npx @mempalace/mcp-dev

2. 配置环境变量

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=python3                # python binary with mempalace installed

3. 索引你的代码库

mempalace --palace ~/.mempalace/active mine /path/to/your/repo --wing code --mode projects

4. 添加到你的 MCP 客户端配置

针对 Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "mempalace-mcp-dev": {
      "command": "npx",
      "args": ["@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"
      }
    }
  }
}

环境变量

变量	默认值	描述
`MCP_REPO_DIR`	`process.cwd()`	Git 仓库根目录的绝对路径
`MCP_PALACE_DIR`	`~/.mempalace/active`	MemPalace 数据目录
`MCP_PALACE_WING`	`code`	Palace 内的 Wing（命名空间）名称
`MCP_LEDGER_PATH`	`<repo>/.mcp-dev/ledger.jsonl`	变更分类账文件路径
`MCP_TRACKS_DIR`	`<repo>/conductor/tracks`	包含项目跟踪文件夹的目录
`MEMPALACE_PYTHON`	`python3`	Python 二进制文件（必须安装 `mempalace`）

MCP 工具参考

代码搜索

工具	描述
`search_code`	对已索引代码库进行语义搜索。接受 `query`（字符串）以及可选的 `scope`（房间名称）和 `limit`（整数，默认 10）
`mine_changed_files`	重新索引自上次 Git 提交以来更改的文件。编辑后调用以保持搜索最新

分支与 Git

工具	描述
`get_branch_context`	返回当前分支、SHA、短 SHA 和最近 5 条提交信息
`get_changed_files`	相对于 `HEAD~1`（或指定的基准引用）更改的文件，包含添加/修改/删除状态
`get_git_diff`	完整 diff 输出。可选 `base` 引用和 `filePath` 用于范围限定

变更分类账

工具	描述
`record_change`	向分类账追加一条记录（受影响的文件、描述、原因、标签、可选的跟踪链接）
`read_ledger`	读取最近的分类账条目。可选 `limit`（默认 20）和 `branch` 过滤器

开发生命周期

工具	描述
`run_typecheck`	在服务目录中运行 `tsc --noEmit`。返回包含文件/行/列/代码的结构化错误
`run_tests`	在服务目录中运行 Jest。返回通过/失败计数和结构化的失败详情

项目跟踪 (Conductor)

工具	描述
`list_tracks`	列出所有活动跟踪（包含 `plan.md` 的目录）
`get_track_plan`	读取跟踪的 `plan.md`
`update_track_plan`	覆盖跟踪的 `plan.md`
`get_track_spec`	读取跟踪的 `spec.md`
`update_track_spec`	覆盖跟踪的 `spec.md`
`get_track_index`	读取跟踪的 `index.md`
`update_track_index`	覆盖跟踪的 `index.md`
`create_track`	使用所有四个文件搭建一个新的跟踪目录

项目跟踪方法论 (Conductor)

Project Tracks 是一个轻量级的、基于文件的功能管理系统。每个 track（跟踪）都是一个包含最多四个文件的目录：

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)

规则：

只有包含 plan.md 的目录才是活动跟踪。
plan.md 始终从磁盘实时读取/写入（从不通过 MemPalace — 无陈旧数据）。
跟踪标识符（slug）必须匹配 [a-zA-Z0-9][a-zA-Z0-9_-]*（最多 100 个字符）。

在新项目中引导跟踪：

# Create the tracks directory
mkdir -p conductor/tracks

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

templates/track/ 中包含模板文件，用于手动搭建。

MemPalace 配置 (`mempalace.yaml`)

在 MCP_REPO_DIR 的根目录下放置一个 mempalace.yaml 以控制文件的索引方式。mempalace.yaml.example 中提供了一个通用示例。

关键部分：

wing — 必须匹配 MCP_PALACE_WING
exclude_patterns — 挖掘过程中要跳过的 gitignore 语法模式
rooms — 用于搜索范围限定的语义路由规则（关键字 → 房间名称）

开发

git clone https://github.com/your-org/mempalace-mcp-dev
cd mempalace-mcp-dev
npm install
npm run build
npm test

请参阅 CONTRIBUTING.md 获取贡献指南。

许可证

MIT — 请参阅 LICENSE。

@mempalace/mcp-dev

@mempalace/mcp-dev

功能特性

前置要求

安装 MemPalace

快速开始

1. 安装 MCP 服务器

2. 配置环境变量

3. 索引你的代码库

4. 添加到你的 MCP 客户端配置

环境变量

MCP 工具参考

代码搜索

分支与 Git

变更分类账

开发生命周期

项目跟踪 (Conductor)

项目跟踪方法论 (Conductor)

MemPalace 配置 (`mempalace.yaml`)

开发

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

@mempalace/mcp-dev

功能特性

前置要求

安装 MemPalace

快速开始

1. 安装 MCP 服务器

2. 配置环境变量

3. 索引你的代码库

4. 添加到你的 MCP 客户端配置

环境变量

MCP 工具参考

代码搜索

分支与 Git

变更分类账

开发生命周期

项目跟踪 (Conductor)

项目跟踪方法论 (Conductor)

MemPalace 配置 (mempalace.yaml)

开发

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

MemPalace 配置 (`mempalace.yaml`)