primer-mcp

primer-mcp

Beta ——核心工作流稳定且经过测试，但这款工具还很新。使用时可能会遇到一些小问题。

一款 Jira-lite MCP 服务，为 AI 辅助开发提供规划优先的工作流指导——工单以 Markdown 文件的形式保存，你的 AI Agent 则是交互界面。

有效吗？一项包含 108 次运行的评测发现，在功能需求和开放式请求中，它将先规划再编码的执行率从 0/15 提高到了 15/15。不过，在 CLAUDE.md 中加上一行内容也能保存计划，因此 primer-mcp 的额外价值在于记录的结构。详情见下文。

为什么要使用它

要真正发挥 AI 编码 Agent 的价值，光靠提示词还不够。你还需要明确它们要构建什么，为它们设计工作流，并部署经实践检验的成果。

如果任由 Agent 自行其是，它们会直接开始实现。Primer-mcp 让它们先做规划：

• 说明这项工作的意义
• 记录决策并权衡利弊
• 将工作拆分为故事和任务
• 编码前与你一起检查计划
• 完成并验证每项任务

工单是带有 YAML frontmatter 的纯 Markdown 文件，与代码一同提交。不需要外部服务，也不需要数据库。所有内容在代码库中一目了然，并且可以轻松使用 Obsidian 等工具浏览。

primer-mcp 面向独立开发者和小型项目——由一个人（和其 AI Agent）逐步处理待办事项。它不提供任务指派、通知或多用户协作功能，这是有意为之：它是 AI 工作流的轻量补充，而不是 Jira 的替代品。

快速开始

需要 Python 3.12+ 和 uv。

将其添加到 MCP 客户端配置中（例如 Claude Code 的 settings.json、Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "primer-mcp": {
      "command": "uvx",
      "args": ["primer-mcp"]
    }
  }
}

就是这样——你的 MCP 客户端会自动下载并运行 primer-mcp。你无需手动安装任何内容。

告诉你的 AI Agent 想构建什么——剩下的交给它处理。该服务会引导 Agent 完成规划优先的工作流：说明工作意义、制定决策、拆分故事和任务，并完成工作。不知道接下来该做什么？询问你的 Agent——它会读取当前状态并判断下一步。

手动安装（可选）

如果你更希望将 primer-mcp 安装为独立工具（例如，用于运行 list-actionable CLI 命令）：

uv tool install primer-mcp

# Update to latest
uv tool upgrade primer-mcp

# Uninstall
uv tool uninstall primer-mcp

效果展示

典型的使用过程——你描述要做的工作，Agent 负责规划：

You:  I want to add user authentication.

Agent: You have EP-001: "Launch the app" — auth fits under that.
       Or I can create a separate epic if this is a bigger initiative.

You:  EP-001 is fine.

Agent: Before we build, we should decide on the auth approach.
       A few common options:

         1. JWT with refresh tokens — stateless, good for mobile/SPAs
         2. Server-side sessions — simple, but needs sticky storage
         3. OAuth2 only — delegates to a provider, less to maintain
            ...

You:  Option 1 — we need mobile support.

Agent: I'll record that decision so we don't revisit it later.
       → Recorded ADR-003: "Use JWT with refresh tokens"
         Rejected: server-side sessions (no mobile support),
                   OAuth2 only (need local accounts too)

       Breaking this into stories.
       → Created ST-005: "Login and registration endpoints"
       → Created ST-006: "Token refresh and revocation"

       And tasks for the first story:
       → Created TK-010: "Add /register endpoint with validation"
       → Created TK-011: "Add /login endpoint returning JWT pair"
       → Created TK-012: "Write integration tests for auth flow"

You:  Let's start with TK-010.

Agent: → Started TK-010

       [implements the register endpoint]

       Done — added POST /register with email/password validation,
       password hashing, and duplicate-email check.
       → Completed TK-010

You:  Looks good, verify it.

Agent: → Verified TK-010 (evidence: "all tests pass — a1b2c3d")

       TK-011 is next. Want me to continue?

每张工单都是 primer/ 中的 Markdown 文件，与代码一同提交。export_graph 工具可以将它们之间的关联可视化：

克隆代码库并打开 assets/demo-graph.html，即可查看交互版本——点击任意节点即可查看完整工单。

由于工单是带有 wikilinks 的纯 Markdown，你也可以将 primer/ 作为 Obsidian 知识库打开，查看会随工单变化而实时更新的图谱——无需重新导出。

工具

你的 AI Agent 会自动调用这些工具——你无需直接调用。若想获得更多控制，也可以让 Agent 调用特定工具。

设置

工具	功能
init_project	创建 primer/ 工单存储目录，并将工作流部分添加到 CLAUDE.md

规划

工具	功能
plan_epic	创建一个史诗项——一项工作内容的顶层容器
record_adr	记录一项架构决策：背景、决策、被否决的替代方案和后果
create_story	在史诗项下创建一个故事——包含验收标准的交付内容
create_task	在故事下创建一个任务——具有可测试结果的具体工作单元
create_spike	创建一个 spike——在限定时间内进行调查，以回答某个问题

执行

工具	功能
start_task	将任务转为进行中
complete_task	将任务标记为已完成，并注明完成的内容
verify_task	使用证据验证已完成的任务（指向提交）
complete_spike	总结调查结果并关闭 spike

查询

工具	功能
list_actionable	列出当前可执行的事项，并提供史诗项背景和建议
get_ticket	按 ID 查看工单及其完整内容
list_tickets	列出工单，可按类型或状态筛选
update_ticket	修改工单的状态、依赖项、正文部分或外部引用

导出

工具	功能
export_graph	生成一个独立的 HTML 文件，以交互式图表呈现项目

提示词

提示词	功能
plan_story	在创建故事前，引导完成规划对话
export_jira	通过 Jira MCP 服务将 primer-mcp 工单导出到 Jira
import_jira	将 Jira 史诗项及其层级结构导入 primer-mcp

Agent 说明

初始化项目时（首次使用时自动初始化，或通过 init_project 初始化），本节会附加到 Agent 配置文件（CLAUDE.md、AGENTS.md）中，为 Agent 提供指引。如果你更愿意手动添加：

## primer-mcp

This project uses primer-mcp for planning-first development.
Tickets are markdown files under `primer/` — they are yours to read and edit. 
Prefer the tools for creating and updating them: they allocate IDs, follow the templates
and guide the workflow. Hand-edit where the tools fall short.

- Plan before code. Recommended flow: Epic -> ADR -> Story -> Task,
  suggest rather than enforce — skip steps when it makes sense.
- Unsure what to do next? Call `list_actionable`.
- Completion is two-phase: `complete_task` with notes, then `verify_task`
  with evidence (point at the commit, not the output). Both are
  recommended — the tools will nudge you if you skip a step.
- After tickets creation or changes, offer to regenerate the project graph with `export_graph`.
- Before committing, check that completion notes on finished tickets
  still reflect the actual work — update both the frontmatter
  `completed_notes` and the `## Completion Notes` section if needed.
- Before implementing new work, propose a ticket and parent. Small fixes (1–2
  tasks) go under the standing bug-fix story; larger efforts get their
  own story. The user can decline.

升级到 Jira（实验性）

primer-mcp 工单可直接映射到 Jira 概念（Epic、Story、Task、ADR）。当项目不再适合使用本地 Markdown 文件时：

• export_jira 通过任意 Jira MCP 服务将工单推送到 Jira。每个工单的 external_ref 字段会记录其 Jira 键，因此重新导出时会更新已有问题，而不是创建重复项。
• import_jira 则执行相反方向的操作。

这两个提示词均为实验性功能，尚未经过端到端测试。

效果如何？

primer-mcp-eval 会测试 primer-mcp 是否会改变 AI 编码 Agent 的工作方式。它让无头 Claude Code 以三种方式处理相同的 12 个变更请求：

• 直接处理
• 使用 primer-mcp
• 在 CLAUDE.md 中添加一行，要求编码前先将计划保存到 docs/

共进行了 108 次相互隔离的运行，根据对话记录评分，不使用大模型裁判。

测试发现：

• primer-mcp 将功能和开放式请求中，编码前编写书面计划的运行次数从 0/15 提高到了 15/15。在 bug 修复和重构方面变化不大，因为它提供的指导允许 Agent 跳过规划。
• 一行指令让全部 36 次运行都保存了计划；相比 primer-mcp 高出约 7% 的成本（primer-mcp 的成本为 50%）。
• **结果：**三种方式都没有带来可衡量的差异。

因此，要写出计划并不需要 primer-mcp。它带来的价值在于记录的结构，而计划文件缺少这种结构：

• 将目标与实施步骤分开
• 记录决策以及被否决的选项
• 为每项工作设置状态

这种结构在后续会话中是否有益，目前尚未经过测试。

额外开销。 Agent 使用 primer-mcp 进行规划时，约多花 15–25 轮。这一开销随创建的工单数量增加，而非随代码变更规模增加，因此在规模更大的工作中占比应该会更小（尚未测试）。

方法和完整结果见该代码库。

本仓库用自身工具管理自身

本仓库中的 primer/ 目录是项目自己的待办事项，由 src/ 中的工具创建并有意提交——一个会提醒你提交工单存储的工具，也应该提交自己的工单存储。安装前，可以在 GitHub 上浏览它，看看真实的存储是什么样的：

• primer/adrs/ — 设计决策，包括被否决的替代方案及原因
• primer/stories/ 和 primer/tasks/ — 已完成的事项、接下来的事项以及验证证据

这是项目管理内容，不属于软件包的一部分。 wheel 只包含 src/primer_mcp，primer/ 不会包含在发行包中。开始规划后，系统会自动创建你自己的 primer/。

开发

DEVELOPMENT.md 介绍如何设置代码检出、运行检查、让 MCP 客户端连接尚未发布的代码，以及代码的组织方式——从通过 MCP 到达的工具调用，到工单文件写入的整个过程。

许可证

MIT