内容
[](https://glama.ai/mcp/servers/desikai-lab/Marrow)
# Marrow
> **为 AI 编程代理提供持久、多项目的智能后台。**
Marrow 为 AI 代理提供结构化、长久的内存，涵盖整个代码库和项目 — 通过 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 提供服务。它公开了一个统一的 API 接口，涵盖任务管理、版本化文档存储、语义代码导航、会话状态和构建管道。
在其核心，一个后台守护进程实时监视源代码文件，使用语言感知语法提取结构骨架，生成向量嵌入，并保持语义索引始终同步。结果是：代理可以通过*含义*而不仅仅是文件名来导航代码。
---
## 为什么选择 Marrow？
AI 编程代理本质上是无状态的。每个新会话都从头开始 — 没有记忆之前的内容，没有构建记录，也不知道当前状态。Marrow 通过充当持久、结构化的工作空间来解决这个问题，任何代理都可以通过 MCP 连接并立即定位。
| 没有 Marrow | 有 Marrow |
|---|---|
| 代理在会话之间忘记上下文 | 完整的会话状态已持久化和可恢复 |
| 代理通过文件名搜索代码 | 代理通过语义含义搜索代码 |
| 笔记和计划存在于聊天记录中 | 版本化制品存储，带有历史记录和回滚 |
| 任务在外部工具中跟踪 | 原生任务积压，带有语义搜索 |
| 构建上下文手动组装 | 声明式构建清单自动组装上下文 |
---
## 用例：多代理交接
Marrow 充当异构代理工作流的单一真相来源。
您可以使用 Claude 进行大规模架构设计，让它将状态保存到 Marrow，然后启动一个更便宜的本地模型来编写单元测试。第二个代理立即使用 `get_session_context` 和语义任务积压来定位。
---
## 架构
Marrow 由三个软件包组成：
```
marrow_server/ — MCP + REST API 服务器（主要服务）
marrow_worker/ — 后台文件监视器和骨架索引器
marrow_common/ — 共享模式（skeleton_schema.py）
```
### marrow_server
一个 FastAPI + FastMCP 应用程序，暴露了 23 个结构化的 MCP 工具和用于工作器的 REST API。存储使用 **LanceDB** 进行向量嵌入和元数据，使用 **Markdown 块** 进行任务和制品内容。传输使用 Streamable HTTP MCP（协议版本 2025-03-26）。
### marrow_worker
一个独立的后台守护进程：
1. 使用文件系统事件监视源代码文件
2. 去抖动快速更改
3. 使用 **tree-sitter** 语法（多语言）解析修改后的文件
4. 提取结构骨架：类、方法、命名空间、属性
5. 通过延迟加载的编码器生成向量嵌入
6. 通过具有重试逻辑的弹性批处理出站队列将骨架块交付给 `marrow_server`
### marrow_common
共享的 Pydantic 模式（`SkeletonChunk`、`SCHEMA_VERSION`）用作工作器和服务器之间的数据契约。
---
## MCP 工具参考
所有工具都可供任何 MCP 兼容的客户端（Claude、Cursor、自定义代理等）使用。
### 🗒️ 任务工具
| 工具 | 描述 |
|---|---|
| `add_tasks` | 将任务列表添加到项目积压 |
| `search_tasks` | 任务的语义搜索 |
| `get_task_details` | 按 ID 返回完整任务详情 |
| `update_task` | 更新任务字段（状态、优先级等） |
| `complete_tasks` | 原子关闭任务并自动取消依赖 |
### 📄 制品工具
| 工具 | 描述 |
|---|---|
| `read_project_artifacts` | 读取一个或多个 Markdown 制品 |
| `save_project_artifacts` | 创建或更新制品（修补、替换、追加） |
| `list_project_artifacts` | 列出制品存储中的文件 |
| `move_project_artifact` | 移动或重命名制品 |
| `delete_project_artifact` | 安全删除制品 |
| `search_project_artifacts` | 跨所有制品的全局语义搜索 |
| `get_project_artifact_outline` | 从 Markdown 文件中提取目录 |
| `list_artifact_history` | 列出制品的版本历史 |
| `restore_project_artifact` | 恢复以前的制品版本 |
### 🧠 代码智能工具
| 工具 | 描述 |
|---|---|
| `search_code_skeletons` | 索引源代码骨架的语义搜索 |
| `get_file_skeleton` | 检索文件的标记优化结构轮廓 |
| `view_file_source` | 从实时源代码仓库中读取精确的行范围 |
| `get_project_map` | 返回所有索引文件的实时目录树 |
### 📁 会话和项目工具
| 工具 | 描述 |
|---|---|
| `list_projects` | 返回所有可用项目的列表 |
| `init_project` | 从内置模板创建新的项目工作空间 — 在 Glama 或任何无 shell 访问权限的部署上使用 |
| `get_session_context` | 读取会话状态并为活动代理角色返回阶段适当的指南 |
| `get_guideline` | 为任何命名代理角色组装并返回完整的上下文包（指南 + ADR）— 用于会话中间的角色切换而不会扰乱管道状态 |
### 🛠️ 构建工具
| 工具 | 描述 |
|---|---|
| `run_project_build` | 执行 YAML 构建清单以组装上下文有效载荷 |
---
## 要求
- Python 3.12+
- [LanceDB](https://lancedb.github.io/lancedb/)（通过 pip 安装）
- [tree-sitter](https://tree-sitter.github.io/) 带有语言轮（参见 ADR-0022）
- 兼容句子转换器的嵌入模型
---
## 快速入门
### 选项 A — Docker（推荐）
**先决条件：** [Docker](https://docs.docker.com/get-docker/) 和 Docker Compose
**1. 获取 compose 文件**
从仓库下载 `docker-compose.yml`（无需完整克隆）：
```bash
curl -O https://raw.githubusercontent.com/desikai-lab/Marrow/main/docker-compose.yml
```
或克隆，如果您更喜欢：
```bash
git clone https://github.com/desikai-lab/Marrow.git
cd Marrow
```
**2. 配置**
在与 `docker-compose.yml` 相同的目录中创建一个 `.env` 文件：
```env
SECRET_TOKEN=您的强大随机密钥
# 首次运行时自动创建的第一个项目的名称
DEFAULT_PROJECT=我的项目
# 主机上包含所有源代码仓库的绝对路径。
# 整个文件夹以只读方式挂载在服务器和工作器的 /projects 中。
SOURCE_PATHS=C:\Users\you\sources # Windows
# SOURCE_PATHS=/home/you/sources # Linux / macOS
# 第一个工作器的源代码路径和项目名称。
# PROJECT_1_PATH 相对于 SOURCE_PATHS — 它成为容器内的 /projects/PROJECT_1_PATH。
# 它必须与该项目的 .settings 文件中的 SOURCE_ROOT 完全匹配。
PROJECT_1_NAME=我的项目
PROJECT_1_PATH=我的应用/src
```
**3. 为每个项目配置源代码连接**
首次启动后，在每个项目工作空间中创建 `.settings` 文件：
```
TASKS_DIR/projects/我的项目/.settings
```
```ini
# 从服务器容器内部看到的路径 — 必须与上面的 PROJECT_1_PATH 匹配。
SOURCE_ROOT=/projects/我的应用/src
```
有关完整说明，请参见 [项目设置（.settings）](#项目设置-settings)。
**4. 启动**
```bash
docker compose up
```
Marrow 拉取预构建的镜像，自动初始化您的第一个项目，然后启动服务器和工作器。在第一次运行时，允许大约 20 秒的时间来下载嵌入模型。
MCP 端点：`http://localhost:8000/mcp`
**5. 连接您的代理**
将 Marrow 添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"marrow": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer 您的强大随机密钥"
}
}
}
}
```
对于 Cursor：在 `~/.cursor/mcp.json` 中的 `mcp` 下添加相同的块。
---
### 选项 B — Glama（托管，无 shell 访问）
Marrow 在 [Glama 市场](https://glama.ai/mcp/servers/desikai-lab/Marrow) 上作为托管的 MCP 服务器提供。Glama 管理容器 — 无需 Docker 或 shell 访问。
**1.** 从 Glama 市场安装 Marrow 服务器，并在环境设置中设置 `SECRET_TOKEN`。
**2.** 打开 Glama 检查器并调用 `init_project` 以创建您的第一个项目：
```json
{ "tool": "init_project", "arguments": { "project": "default" } }
```
**3.** 连接您的代理并调用 `get_session_context` 以验证工作空间已就绪。
对于其他项目，请再次调用 `init_project` 并使用新的名称。
> **注意：** 代码智能工具（`search_code_skeletons`、`view_file_source` 等）
> 需要一个运行中的 `marrow-worker`，并且需要访问您的源代码。这些工具在 Glama 上不可用，除非您运行一个单独的工作器指向 Glama 服务器 URL。
---
### 选项 C — 手动/开发设置
<details>
<summary>展开以获取手动设置说明</summary>
#### 1. 克隆仓库
```bash
git clone https://github.com/desikai-lab/Marrow.git
cd Marrow
```
#### 2. 设置 marrow_server
```bash
cd marrow_server
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
```
复制并配置环境文件：
```bash
cp .env.example .env
# 编辑 .env — 设置 SECRET_TOKEN 和 TASKS_DIR（必填）
```
启动服务器：
```bash
python src/marrow_server.py
```
MCP 服务器将在 `http://localhost:8000/mcp` 默认可用。
#### 2b. 初始化您的第一个项目
```bash
marrow-admin project-init --project 我的项目
```
这会将内置的项目模板复制到您的 `TASKS_DIR/projects/我的项目/` 工作空间中。打开 `spec.md` 并在第一个代理会话之前填写您的技术栈。
#### 2c. 配置源代码连接
在项目工作空间中创建 `.settings` 文件：
```ini
# TASKS_DIR/projects/我的项目/.settings
SOURCE_ROOT=/绝对路径/到您的源代码
```
#### 3. 设置 marrow_worker
在单独的终端中，启动指向您的源代码的工作器：
```bash
cd marrow_worker
pip install -e .
python main.py \
--repo-dir /绝对路径/到您的源代码 \
--project-name 我的项目 \
--target-url http://localhost:8000 \
--secret-token 您的强大随机密钥 \
--init
```
`--init` 触发启动时的完整扫描；后续运行省略它。
#### 4. 连接您的代理
```json
{
"mcpServers": {
"marrow": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer 您的强大随机密钥"
}
}
}
}
```
</details>
---
## 项目设置（.settings）
每个 Marrow 项目工作空间都包含一个 `.settings` 文件，用于告诉服务器相应的源代码在磁盘上的位置。没有它，代码智能工具
（`search_code_skeletons`、`get_file_skeleton`、`view_file_source`、`get_project_map`）对于该项目处于禁用状态。
**位置：** `TASKS_DIR/projects/{project_name}/.settings`
**格式：**
```ini
# 服务器容器内部看到的源代码根目录的绝对路径。
SOURCE_ROOT=/projects/我的应用/src
```
**关键约束 — 服务器、工作器和 .settings 必须就同一路径达成一致。**
Marrow 使用单个共享卷（主机上的 `SOURCE_PATHS`，在两个容器中挂载为 `/projects`）
为服务器和每个工作器提供所有源代码仓库的访问权限。然后，每个项目的 `.settings` 将 `SOURCE_ROOT` 指向其自己的子文件夹，并且相应的工作器监视确切的相同路径：
```
主机：
C:\Sources\ ← .env 中的 SOURCE_PATHS
├── 我的应用\src\
└── 其他应用\src\
服务器和工作器容器内部：
/projects/ ← 相同卷，相同路径
├── 我的应用/src/
└── 其他应用/src/
TASKS_DIR/projects/
├── 我的应用/
│ └── .settings → SOURCE_ROOT=/projects/我的应用/src
└── 其他应用/
└── .settings → SOURCE_ROOT=/projects/其他应用/src
工作器适用于我的应用： --repo-dir /projects/我的应用/src --project-name 我的应用
工作器适用于其他应用： --repo-dir /projects/其他应用/src --project-name 其他应用
```
**多个项目** 每个项目都有自己的 `.settings` 文件和自己的 `docker-compose.yml` 服务（注释模板块包含在 compose 文件中）。
---
## 配置
两个服务都通过环境变量（`.env` 文件）进行配置。
### marrow_server
| 变量 | 描述 | 默认值 |
|---|---|---|
| `SECRET_TOKEN` | MCP 和 REST API 身份验证的 Bearer 令牌 | 必需 |
| `TASKS_DIR` | 存储项目工作空间的绝对路径 | 必需 |
| `DEFAULT_PROJECT` | 首次运行时自动创建的项目名称（仅限 Docker） | `default` |
| `EMBEDDING_MODEL_CODE` | 代码骨架嵌入的句子转换器模型 | `BAAI/bge-small-en-v1.5` |
| `EMBEDDING_MODEL_TEXT` | 文本/制品嵌入的句子转换器模型 | `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` |
| `EMBEDDING_DIMENSIONS` | 嵌入向量维度 — 必须与选择的模型匹配 | `384` |
| `MAX_EMBED_CHARS` | 每个块的最大字符数 | `2000` |
| `VECT_DEBOUNCE_SECONDS` | 更改的文件的矢量化延迟 | `0.5` |
| `PORT` | HTTP 服务器端口 | `8000` |
### marrow_worker（命令行参数）
| 参数 | 描述 | 默认值 |
|---|---|---|
| `--repo-dir` | 要监视的源代码的绝对路径 — 必须与 `.settings` 中的 `SOURCE_ROOT` 匹配 | `os.getcwd()` |
| `--project-name` | Marrow 项目此工作器索引到 | `DefaultProject` |
| `--target-url` | 运行的 `marrow_server` 的 URL | `http://localhost:8000` |
| `--secret-token` | 必须与服务器上的 `SECRET_TOKEN` 匹配 | — |
| `--init` | 启动时运行完整的存储库扫描 | 关闭 |
| `--polling-interval` | 文件系统轮询间隔（秒）— 越低响应越快，越大 CPU 在大存储库上越高 | `1.0` |
### .env（Docker Compose）
| 变量 | 描述 |
|---|---|
| `SECRET_TOKEN` | 跨所有服务的共享密钥 |
| `SOURCE_PATHS` | 主机路径，挂载为服务器和所有工作器的 `/projects` |
| `DEFAULT_PROJECT` | 首次运行时自动创建的第一个项目名称 |
| `PROJECT_1_NAME` | 第一个工作器的 Marrow 项目名称 |
| `PROJECT_1_PATH` | `SOURCE_PATHS` 内子文件夹，第一个工作器监视 |
| `PROJECT_2_NAME` | 第二个工作器的项目名称（如果使用） |
| `PROJECT_2_PATH` | 第二个工作器的子文件夹 |
| `EMBEDDING_MODEL_CODE` | 覆盖代码骨架嵌入模型（传递给服务器和工作器）— 默认 `BAAI/bge-small-en-v1.5` |
| `HF_HUB_OFFLINE` | 设置为 `1` 以在首次运行后阻止所有 HuggingFace 网络调用，仅使用本地缓存 — 默认 `0` |
| `POLLING_INTERVAL` | 工作器的文件轮询间隔（秒）— 增加以减少 CPU 在大存储库上 | `1.0` |
---
## 项目结构（代理工作空间）
Marrow 管理的每个项目在 `TASKS_DIR/projects/` 中都有一个结构化的工作空间：
```
{project_name}/
├── .db # 矢量数据库和任务 Blob
├── .history # 文件历史文件夹
├── .recycle_bin
├── .settings # 附加项目配置，如 SOURCE_ROOT - 定义到代码库的路径
└── artifacts # 项目的根文件夹，代理可以访问
├── session.md # 会话状态 — 当前焦点、管道阶段
├── spec.md # 项目规范和架构常数
├── builds/ # YAML 构建清单
└── docs/
├── decisions/adr/ # 架构决策记录
├── features/
│ ├── active/ # 当前开发的功能
│ └── archive/ # 已完成的工作历史
├── manuals/ # 操作指南和文档
└── templates/ # 标准化蓝图
```
---
## 构建引擎
Marrow 包含一个声明式构建系统，用于从多个制品源组装复杂上下文有效载荷。定义 YAML 清单并通过 MCP 运行：
```yaml
# builds/my_context.yaml
name: feature_context
version: "1.0.0"
output:
format: single_file
filename: "context_{{DATE}}.md"
steps:
- action: include_artifact
path: session.md
mode: full
- action: include_artifact
path: docs/decisions/adr/0034-product-name-marrow.md
mode: section
section_name: "Decision"
```
通过 MCP 工具 `run_project_build` 运行，或在本地运行：
```bash
python run_build.py --project 我的项目 --build my_context
```
---
## 路线图
### ✅ v1.0.0 — 基础
核心 MCP 服务器、LanceDB 存储、制品管理、任务积压、代码骨架索引、构建引擎、会话连续性。
### 🟡 v1.1.0 — 沙盒和同步（活跃中）
工作流强化、动态重新索引、阶段感知代理指南、交接优化。
### 🔴 v2.0.0 — AI 协调器（计划中）
声明式交接、上下文净化、分支感知索引、差异智能、多代理协调。
---
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置、编码标准和拉取请求流程。
---
## 许可
MIT — 请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器