Primer MCP

Name: Primer MCP
Author: ivanlai

by ivanlaiversion 0.1.8i★ –iRuns on your computer

Registry nameio.github.ivanlai/primer-mcp

Install

Overview

Description from the maker (original English)

A Jira-lite MCP server that guides planning-first workflows for AI-assisted development.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Developer tools

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
The registry lists no key to fill in.

You need

PyPIPython’s uv installed (for the uvx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

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

Run this in your terminal

claude mcp add primer -- uvx primer-mcp

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "primer": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "primer-mcp"
      ]
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account ivanlai, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Developer toolsi

More stars than 0% of the other 1395 servers in this category
Published to the registry more recently than 59% of the other 1395 servers in this category
Basic checks equal to or better than 100% of the other 1395 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Primer MCP safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.1.8) reached the registry 38 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: GitHub, Desktop Commander, Cloudflare MCP

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

GitHub

by github

GitHub’s official server lets AI read and manage code, issues and pull requests in your account. Use GitHub’s hosted version or run it locally with Docker.

Computer or cloud★ 34,245MITUpdated 4 days ago

Install

Desktop Commander

by wonderwhy-er

MCP server for terminal commands, file operations, and process management

Runs on your computer★ 10,225MITUpdated 16 days ago

Install

Cloudflare MCP

by cloudflare

Cloudflare MCP servers

Runs in the cloud★ 4,446Apache-2.0Updated 14 months ago

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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.

Does it work? An eval of 108 runs found it took planning-before-coding from 0/15 to 15/15 on features and open-ended requests. But one line in CLAUDE.md got a saved plan too, so what primer-mcp adds is the structure of the record. Details below.

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 the work into stories and tasks
check the plan with you before coding
complete and verify each one

The tickets are plain markdown with YAML frontmatter, committed alongside your code. There's no external service and no database. Everything is visible in your repo and easy to browse 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):

"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):

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:

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:

JWT with refresh tokens — stateless, good for mobile/SPAs
Server-side sessions — simple, but needs sticky storage
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:

*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:

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

`export_jira` pushes tickets to Jira through any Jira MCP server. Each ticket's external_ref field tracks its 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.

Does it work?

primer-mcp-eval tests whether primer-mcp changes how an AI coding agent works. It gives headless Claude Code the same 12 change requests three ways:

plain
with primer-mcp
with one line in CLAUDE.md asking for a plan saved in docs/ before coding

That's 108 isolated runs, scored from transcripts with no LLM judge.

What it found:

primer-mcp took a written plan before coding from 0 of 15 runs to 15 of 15 on features and open-ended requests. It changed little on bug fixes and refactors, where its guidance lets the agent skip planning.
The one-line instruction got a saved plan on all 36 runs, for about 7% extra cost against primer-mcp's 50%.
Outcomes: none of the three made a measurable difference.

So primer-mcp isn't needed to get a plan written. What it adds is the shape of the record, which the plan files lacked:

goals kept apart from implementation steps
decisions with the options that were rejected
a status for each piece of work

Whether that structure pays off in later sessions is untested.

Overhead. Wherever the agent planned with primer-mcp, it took about 15–25 extra turns. That grew with the number of tickets created, not with the size of the code change, so it should be a smaller share of larger work (untested).

The methodology and full results are in that repo.

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.

Development

DEVELOPMENT.md covers setting up a checkout, running the checks, pointing an MCP client at unreleased code, and how the code is put together — from a tool call arriving over MCP to the ticket file being written.

License

MIT

Primer MCP

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Developer toolsi

Common questions

Alternatives

GitHub

Desktop Commander

Cloudflare MCP

README from the maker

primer-mcp

Why

Quick start

Manual install (optional)

Update to latest

Uninstall

What it looks like

Tools

Setup

Planning

Execution

Query

Export

Prompts

Agent instructions

Graduating to Jira (experimental)

Does it work?

This repo dogfoods itself

Development

License