JinDaGe - overseer MCP Details

article

README

🚀 Overseer

Overseer 是一个通过 MCP 实现 AI 代理任务编排的工具。它由 SQLite 提供支持，并使用原生版本控制系统（jj-lib + gix）。

🚀 快速开始

你可以通过以下方式安装 Overseer：

📦 安装指南

通过 npm 安装

npm install -g @dmmulroy/overseer

通过 skills.sh 为代理安装

npx skills add dmmulroy/overseer

💻 使用示例

MCP 服务器

将以下配置添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["@dmmulroy/overseer", "mcp"]
    }
  }
}

命令行界面（CLI）

os task create -d "Implement auth"
os task list --ready
os task start <task-id>
os task complete <task-id>

🔧 技术细节

架构

┌─────────────────────────────────────┐
│     Overseer MCP (Node.js)          │
│  - Single "execute" tool (codemode) │
│  - VM sandbox with tasks/learnings  │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│         os CLI (Rust)               │
│  - SQLite storage                   │
│  - jj-lib (primary VCS)             │
│  - gix (git fallback)               │
└─────────────────────────────────────┘

代码模式

使用单一的 execute 工具，代理编写 JavaScript 代码，服务器运行代码：

const milestone = await tasks.create({
  description: "User auth system",
  context: "JWT + refresh tokens"
});

const login = await tasks.create({
  description: "Login endpoint",
  parentId: milestone.id
});

await tasks.start(login.id);  // VCS required: creates bookmark, records start commit
// ... do work ...
await tasks.complete(login.id, {  // VCS required: commits changes, bubbles learnings to parent
  result: "Implemented with bcrypt",
  learnings: ["bcrypt rounds should be 12+ for production"]
});

return { milestone, login };

任务层次结构

里程碑（深度 0） - 根任务，没有父任务
任务（深度 1） - 父任务是里程碑
子任务（深度 2） - 最大深度，父任务是任务

API 文档

tasks

tasks.create({ description, context?, parentId?, priority?, blockedBy? })
tasks.get(id)           // Returns TaskWithContext
tasks.list({ parentId?, ready?, completed?, depth?, type? })  // type: "milestone"|"task"|"subtask"
tasks.update(id, { description?, context?, priority?, parentId? })
tasks.start(id)
tasks.complete(id, { result?, learnings? })  // Learnings bubble to immediate parent
tasks.reopen(id)
tasks.delete(id)
tasks.block(taskId, blockerId)
tasks.unblock(taskId, blockerId)
tasks.nextReady(milestoneId?)
tasks.tree(rootId?)     // Returns TaskTree or TaskTree[] (all milestones if no ID)
tasks.search(query)     // Search by description/context/result
tasks.progress(rootId?) // Returns { total, completed, ready, blocked }

learnings

learnings.list(taskId)  // Learnings are added via tasks.complete()

版本控制系统（VCS，工作流必需）

VCS 操作集成到任务工作流中，没有直接的 API： | 操作 | VCS 效果 | |-----------|-----------| | tasks.start(id) | 需要 VCS - 创建书签 task/<id>，记录开始提交 | | tasks.complete(id) | 需要 VCS - 提交更改，删除书签（尽力而为） | | tasks.complete(milestone) | 还会清理所有后代书签（深度 1 和深度 2） | | tasks.delete(id) | 尽力清理书签（无需 VCS 也可工作） |

VCS（jj 或 git）对于开始/完成任务必需。CRUD 操作无需 VCS 也可工作。

渐进式上下文

任务从祖先继承上下文。完成任务时，学习成果会冒泡到直接父任务（保留原始 sourceTaskId）：

const subtask = await tasks.get(subtaskId);
// subtask.context.own       - 此任务的上下文
// subtask.context.parent    - 父任务上下文（深度 > 0）
// subtask.context.milestone - 根里程碑上下文（深度 > 1）
// subtask.learnings.own     - 此任务的学习成果（完成子任务时添加）

CLI 参考

# 任务操作
os task create -d "description" [--context "..."] [--parent ID] [--priority 1-5]
os task get <id>
os task list [--parent ID] [--ready] [--completed]
os task update <id> [-d "..."] [--context "..."] [--priority N] [--parent ID]
os task start <id>
os task complete <id> [--result "..."] [--learning "..."]...
os task reopen <id>
os task delete <id>
os task block <id> --by <blocker-id>
os task unblock <id> --by <blocker-id>
os task next-ready [--milestone ID]
os task tree [ID]           # 无 ID 表示所有里程碑树
os task search "query"
os task progress [ID]       # 汇总计数：总数、已完成、就绪、阻塞

# 学习成果（通过 task complete --learning 添加）
os learning list <task-id>

# VCS（仅 CLI - MCP 中自动处理）
os vcs detect
os vcs status
os vcs log [--limit N]
os vcs diff [BASE_REV]
os vcs commit -m "message"
os vcs cleanup [--delete]  # 列出/删除孤立的任务分支

# 数据导出
os data export [-o file.json]

任务查看器

用于查看任务的 Web UI：

# 通过 CLI（安装后）
os ui

# 或从仓库（开发模式）
cd ui && npm install && npm run dev
# 打开 http://localhost:5173

有三种视图：

图形 - 带有阻塞关系的有向无环图可视化
列表 - 可过滤的任务列表
看板 - 按完成状态展示的看板

键盘操作：g=图形，l=列表，k=看板，?=帮助

开发

# Rust CLI
cd overseer && cargo build --release
cd overseer && cargo test

# Node MCP
cd mcp && npm install
cd mcp && npm run build
cd mcp && npm test

# UI（开发服务器）
cd ui && npm install && npm run dev

存储

SQLite 数据库位置（按优先级排序）：

OVERSEER_DB_PATH 环境变量（如果设置）
VCS_ROOT/.overseer/tasks.db（如果在 jj/git 仓库中）
$CWD/.overseer/tasks.db（备用）

首次执行命令时自动创建。

VCS 检测

从当前工作目录向上查找 .jj/ → 使用 jj-lib
如果未找到，查找 .git/ → 使用 gix
都未找到 → VcsType::None

优先使用 jj：有 jj 时总是优先使用。

📚 详细文档

架构 - 系统设计和不变量
CLI 参考 - 完整的命令文档
MCP 指南 - 代理使用模式

📄 许可证

本项目采用 MIT 许可证。

overseer