primer-mcp 0.1.0__tar.gz

primer_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy
+      - run: uv run pytest

primer_mcp-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# primer-mcp generated output
+primer/graph.html
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

primer_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

primer_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,104 @@
+# primer-mcp
+
+A Jira-lite MCP server that enforces planning-first workflows for AI-assisted development. Tickets are markdown files on the user's local disk. The AI agent is the interface.
+
+## Project docs (read these first)
+
+- `docs/planning.md` — goals, constraints, non-goals, success criteria
+- `docs/architecture.md` — all key decisions, ticket schema, graph protocol, body templates
+- `docs/epic-001.md` — prose descriptions of the stories; `primer/` is the live backlog
+
+## Key conventions
+
+- **Language:** Python, packaged with `uv`, distributed via `uvx`
+- **Data store:** Markdown + YAML frontmatter in `primer/` (visible, not dot-hidden, and committed — this repo dogfoods its own store)
+- **No provider-specific code** — server must be MCP-protocol-only, no Anthropic/OpenAI SDK calls
+- **Ticket body templates** are defined in `docs/architecture.md` — follow them exactly when generating ticket files
+- **Graph edges**: `blocked_by` is a base field on ALL ticket types, not just tasks. It is the only stored edge — "A blocks B" is recorded on B (ADR-004)
+- **Two-phase completion:** `complete_task` then `verify_task` — do not collapse into one step
+
+## Workflow gates (enforced by the server — never bypass)
+
+1. Cannot create an ADR without a valid parent Epic
+2. Cannot create a Task without a valid parent Story
+
+Two-phase completion (`complete_task` then `verify_task`) is recommended and the tools will nudge you if you skip a step, but it is not enforced — `verify_task` proceeds from any pre-terminal state.
+
+## Development workflow
+
+- Dogfood wherever possible — plan and track this project's own work with primer-mcp's own tools, and fix what that exposes. If we don't trust our own process, why should anyone else?
+- Always enter plan mode before implementing a new story
+- Every story from ST-002 onward lands with its unit tests in the same PR — acceptance criteria are proven by tests, not deferred to ST-010
+- No filler tests. Every test must verify a real behaviour or acceptance criterion and be able to fail for a real reason — never add tests for coverage's or quantity's sake
+- Tasks must be completable in a single session (~3 files max)
+- One PR per task
+- When a commit is for a ticket, prefix the message with the ticket ID (`TK-030: Rename get_next_action...`). This closes the loop: `git log --grep TK-030` finds the commit, and `verified_evidence` on the ticket points back at the hash. Standalone chores (CLAUDE.md tweaks, typo fixes) need no prefix.
+- Ask before committing and before pushing — the user reviews the working diff, not the PR page
+- Improvements and simplifications wait until after v0 ships. This is a compact project that showcases the workflow, not an enterprise system; a heavier primer-mcp has no reason to exist when Jira already does
+- Completion is two-phase: `complete_task` with notes, then `verify_task` with evidence. Both are recommended
+- **Tickets hold what git cannot; they never restate it.** Intent before the work — `testable_outcome`, acceptance criteria, an ADR's rejected alternatives — has no other home. What happened, and how, is git's job. So keep ticket bodies at overview level: the goal, not the implementation. Evidence stays one line and points at the commit (`"218 passed, mypy clean — c4ac39f"`). Completion notes have two layers: the frontmatter `completed_notes` field is a terse one-liner for scanning; the `## Completion Notes` body section holds a fuller summary — approach taken, key changes, decisions made — the narrative that would otherwise vanish with the chat session. Duplicating git is what makes Jira miserable, and detail written before the work is what makes tickets lie: TK-007 listed the functions it would add, the real implementation added others, and `verified` is terminal so it says so permanently
+- Detail is safe where the content describes a moment rather than a state, which is why ADRs are the exception: a rejected alternative stays true forever, and a reversal is a new ADR superseding the old one, not an edit
+
+## Plagiarism policy
+
+Do NOT read or reference `groundwork-mcp` or any similar existing repo. All design decisions must come from first principles. The architecture is fully documented in `docs/architecture.md`.
+
+## Stack
+
+```
+mcp                  # MCP server SDK
+pydantic             # schema validation
+python-frontmatter   # markdown + YAML frontmatter parsing
+pyyaml               # direct YAML dumping (custom no-alias dumper, stable key order)
+networkx             # graph traversal and cycle detection
+uv                   # packaging and distribution (dev pinned to Python 3.13, requires-python >=3.12)
+pytest               # unit tests (use tmp_path fixture, no filesystem mocking)
+ruff                 # lint + format (dev)
+mypy                 # type checking (dev)
+```
+
+## Where things stand
+
+**Start by running `uv run primer-mcp list-actionable`**, then:
+
+1. Copy the command's entire output into your response as-is. The output
+   is already formatted for the user — do not rewrite, summarise, or
+   build your own table from it.
+2. Below that output, add your recommendation for what to work on next
+   and why.
+
+The live backlog is `primer/`; `docs/epic-001.md` keeps the prose descriptions.
+Story IDs match across both — ST-007 means the query and graph tools story
+everywhere.
+
+Decisions live in `primer/adrs/` (ADR-001 to ADR-007) with the alternatives
+that were rejected. Read those before reopening a settled question — several
+were argued through at length and the reasoning is not in the code.
+
+## 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. The recommended flow is Epic → ADR → Story → Task,
+  but the tools suggest rather than enforce — skip steps when it makes
+  sense for the work at hand.
+- Unsure what to do next? Run `uv run primer-mcp 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 creating tickets, completing tasks, or verifying tasks, offer to
+  regenerate the project graph with `export_graph` so the user can see
+  the updated picture.
+- Before committing, check whether any tickets completed or verified in
+  this session have completion notes that still reflect the actual work.
+  If the implementation evolved after the notes were written, update
+  both layers before staging: the frontmatter `completed_notes` (terse
+  one-liner) and the `## Completion Notes` body section (fuller summary
+  — approach taken, key changes, decisions made).
+- When the user reports a bug or small fix, check for a standing bug-fix
+  story under the epic before creating a new story. Small fixes (1–2
+  tasks) go as tasks under that story; larger efforts (3+ tasks) get
+  their own story. If no bug-fix story exists yet, suggest creating one.

primer_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

primer_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: primer-mcp
+Version: 0.1.0
+Summary: A Jira-lite MCP server that guides planning-first workflows for AI-assisted development — tickets as markdown files, your AI agent as the interface.
+Project-URL: Homepage, https://github.com/ivanlai/primer-mcp
+Project-URL: Repository, https://github.com/ivanlai/primer-mcp
+Project-URL: Issues, https://github.com/ivanlai/primer-mcp/issues
+Author: Ivan Lai
+License: MIT License
+        
+        Copyright (c) 2026 Ivan Lai
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,markdown,mcp,planning,tickets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: mcp
+Requires-Dist: networkx
+Requires-Dist: pydantic
+Requires-Dist: python-frontmatter
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# 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
+
+AI coding agents jump straight to implementation. primer-mcp makes them plan first: state why the work matters, record decisions, 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.
+
+## Install
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+# Run directly (recommended for MCP)
+uvx primer-mcp
+
+# Or install permanently
+uv tool install primer-mcp
+
+# Update to latest
+uv tool upgrade primer-mcp
+
+# Uninstall
+uv tool uninstall primer-mcp
+```
+
+## Quick start
+
+Add to your MCP client config (e.g. Claude Code `settings.json`, Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "primer-mcp": {
+      "command": "uvx",
+      "args": ["primer-mcp"]
+    }
+  }
+}
+```
+
+Then ask your AI agent to plan some work. The recommended flow is:
+
+```
+init_project  →  plan_epic  →  record_adr  →  create_story  →  create_task
+```
+
+The tools suggest this order but don't block you from skipping steps — if the work is straightforward, go straight from epic to stories. You'll get a helpful nudge if the tools think you might want to record a decision first.
+
+Once tasks exist, the execution cycle is:
+
+```
+start_task  →  complete_task (with notes)  →  verify_task (with evidence)
+```
+
+Not sure what to do next? `get_next_action` reads the current state and returns exactly one instruction.
+
+## Tools
+
+### 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 |
+|------|-------------|
+| `get_next_action` | Ask what to do next — returns exactly one instruction |
+| `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 |
+
+## CLAUDE.md snippet
+
+`init_project` appends this to your project's CLAUDE.md automatically. 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. The recommended flow is Epic -> ADR -> Story -> Task,
+  but the tools suggest rather than enforce — skip steps when it makes
+  sense for the work at hand.
+- Unsure what to do next? Call `get_next_action`.
+- 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 creating tickets, completing tasks, or verifying tasks, offer to
+  regenerate the project graph with `export_graph` so the user can see
+  the updated picture.
+- When the user reports a bug or small fix, check for a standing bug-fix
+  story under the epic before creating a new story. Small fixes (1-2
+  tasks) go as tasks under that story; larger efforts (3+ tasks) get
+  their own story. If no bug-fix story exists yet, suggest creating one.
+```
+
+## Graduating to Jira
+
+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.
+
+## This repo dogfoods itself
+
+The `primer/` directory is this 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. It doubles as a worked example: browse it to see what a real store looks like before installing anything.
+
+- `primer/adrs/` — why the design is what it is, including the alternatives that were rejected and why
+- `primer/stories/` and `primer/tasks/` — what is done, what is next, and the evidence each completed task was verified against
+
+**It is project management, not part of the package.** The wheel ships `src/primer_mcp` only, and `primer/` is excluded from the source distribution. When you install primer-mcp, `init_project` creates *your* `primer/` — this one never reaches your machine.
+
+## License
+
+MIT