primer-mcp

Beta — the core workflow is stable and tested, but the tool is new. Expect rough edges.

A Jira-lite MCP server that guides planning-first workflows for AI-assisted development — tickets as markdown files, your AI agent as the interface.

Why

Getting real value from AI coding agents takes more than prompting — it takes shaping what they build, engineering the workflow around them, and deploying something that holds up in practice. Left to their own devices, agents jump straight to implementation. Primer-mcp makes them plan first: state why the work matters, record decisions and weigh trade-offs, break it into stories and tasks, then complete and verify each one. The tickets are plain markdown with YAML frontmatter, committed alongside your code — no external service, no database, fully visible in your repo and conveniently browsable with tools like Obsidian.

primer-mcp is designed for solo developers and small projects — one person (and their AI agent) working through a backlog. It doesn't have assignment, notifications, or multi-user coordination, and that's deliberate: it's a lightweight complement to the AI workflow, not a replacement for Jira.

Quick start

Requires Python 3.12+ and uv.

Add to your MCP client config (e.g. Claude Code settings.json, Claude Desktop claude_desktop_config.json):

config.json

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

That's it — your MCP client downloads and runs primer-mcp automatically. You don't need to install anything manually.

Tell your AI agent what you want to build — it handles the rest. The server guides the agent through a planning-first workflow: why the work matters, decisions, stories, tasks, completion. Not sure what to do next? Ask your agent — it reads the current state and knows what comes next.

Manual install (optional)

If you prefer to install primer-mcp as a standalone tool (e.g. for the list-actionable CLI command):

bash

uv tool install primer-mcp

# Update to latest
uv tool upgrade primer-mcp

# Uninstall
uv tool uninstall primer-mcp

What it looks like

A typical session — you describe the work, the agent handles the planning:

Code

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?

Every ticket is a markdown file in primer/, committed alongside your code. The export_graph tool visualises how they connect:

Demo project graph

Clone the repo and open assets/demo-graph.html for the interactive version — click any node to see its full ticket.

Since tickets are plain markdown with wikilinks, you can also open primer/ as an Obsidian vault for a live graph that updates as tickets change — no need to re-export.

Tools

Your AI agent calls these tools automatically — you don't need to invoke them directly. You can also ask your agent to call a specific tool if you want more control.

Setup

Tool	What it does
`init_project`	Create the `primer/` ticket store and add the workflow section to CLAUDE.md

Planning

Tool	What it does
`plan_epic`	Create an epic — the top-level container for a body of work
`record_adr`	Record an architecture decision: context, decision, rejected alternatives, consequences
`create_story`	Create a story under an epic — a deliverable with acceptance criteria
`create_task`	Create a task under a story — a concrete unit of work with a testable outcome
`create_spike`	Create a spike — a timeboxed investigation to answer a question

Execution

Tool	What it does
`start_task`	Move a task to in-progress
`complete_task`	Mark a task completed with notes on what was done
`verify_task`	Verify a completed task with evidence (point at the commit)
`complete_spike`	Close a spike with findings

Query

Tool	What it does
`list_actionable`	List what can be acted on right now, with epic context and recommendations
`get_ticket`	Read a ticket by ID with its full body
`list_tickets`	List tickets, filterable by type or status
`update_ticket`	Amend a ticket's status, dependencies, body sections, or external refs

Export

Tool	What it does
`export_graph`	Generate a self-contained HTML file visualising the project as an interactive graph

Prompts

Prompt	What it does
`plan_story`	Walk through a planning conversation before creating a story
`export_jira`	Export primer-mcp tickets to Jira via a Jira MCP server
`import_jira`	Import a Jira epic and its hierarchy into primer-mcp

Agent instructions

When your project is initialized (automatically on first use, or via init_project), this section is appended to your agent config file (CLAUDE.md, AGENTS.md) to guide the agent. If you prefer to add it manually:

markdown

## 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.

Graduating to Jira (experimental)

primer-mcp tickets map directly to Jira concepts (Epic, Story, Task, ADR). When a project outgrows local markdown files, use the export_jira prompt with any Jira MCP server to push tickets to Jira. The external_ref field on each ticket tracks the Jira key, so re-exports update existing issues instead of creating duplicates. import_jira goes the other direction. Both prompts are experimental and have not been tested end-to-end.

This repo dogfoods itself

The primer/ directory in this repo is the project's own backlog, created with the tools in src/ and committed deliberately — a tool that tells you to commit your ticket store should commit its own. Browse it on GitHub to see what a real store looks like before installing:

primer/adrs/ — design decisions, including rejected alternatives and why
primer/stories/ and primer/tasks/ — what is done, what is next, and verification evidence

It is project management, not part of the package. The wheel ships src/primer_mcp only, and primer/ is excluded from the distribution. Your own primer/ is created automatically when you start planning.

License

MIT