convez.ai
MCP ServerAutomaçãoIntermediário
oholsen

Backlog MCP Server

oholsen/backlog-mcp

Backlog em markdown + MCP tools para agentes consultarem itens prontos

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe um backlog em formato markdown-table para agentes de IA, permitindo consultas estruturadas sobre itens prontos e priorizados. Integra opcionalmente um CSV de scoring (complexidade, valor, status) e mantém o markdown como fonte única de verdade, compatível com git e ferramentas padrão.

Instalação

$npx convez-ai oholsen/backlog-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.5.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes consultarem itens prontos e de alto valor sem carregar arquivo inteiro
  • Triagem automática por complexidade, valor e status de bloqueio
  • Manter histórico git e referências cruzadas no backlog markdown

Veredito

Solução prática para integrar backlogs markdown com agentes Claude/Gemini via MCP. Design minimalista que preserva git como workflow — ideal para times que já usam markdown em versionamento.

README

A tradução para o português deste README ainda está na fila.

backlog-mcp

MCP server that exposes a markdown-table backlog — and an optional CSV scoring sidecar — to MCP-aware agents (Claude Code, Gemini CLI, Codex, Kiro, etc.). Lets an agent answer "what's ready and high-value?" via tool calls instead of dragging the whole Backlog.md into context.

Why

If your project tracks work as markdown table rows in a single Backlog.md, two problems show up at scale:

  • Reading the whole file into agent context is wasteful.
  • Triage queries ("ready items, complexity ≤ 2, value ≥ 4") are brittle as ad-hoc grep.

backlog-mcp wraps that file with a small MCP server. The markdown stays the source of truth — direct edits, git history, and git grep cross-references all keep working. Agents call structured tools instead of regex-editing prose.

Backlog format

Plain markdown table rows with this column shape:

| # | File | Description |
|---|---|---|
| 12 | src/auth/session.py | **Session token not rotated after privilege escalation.** Rotate on role change. |
| ~~3~~ | ~~src/api/routes.py~~ | **DONE (PR #41, 2026-03-15).** Rate-limit login endpoint. |

Conventions the server understands:

  • Open: | <id> | <files> | <description> |
  • In progress: description starts with **IN PROGRESS (branch-name)**
  • Done: id/files strikethroughed (~~…~~), description starts with **DONE …**
  • Archive: rows under a ## Done — archive heading (configurable prefix)

Sections are ## headings; subsections are ### .

Optional scoring sidecar

Backlog-Scores.csv next to Backlog.md:

id,complexity,value,ready,blocked_by,tags,notes
# complexity and value: 1 (low) – 5 (high); net priority ≈ value / complexity
12,2,4,Y,,auth;security,session not rotated after privilege escalation
  • complexity, value: 1–5
  • ready: Y / N / partial
  • blocked_by: comma-separated IDs
  • tags: semicolon-separated free-form

Lines starting with # are comments. The server runs without the CSV — score filters just match nothing if it's absent.

Install

pip install git+https://github.com/oholsen/backlog-mcp

(Once published to PyPI: pip install backlog-mcp.)

This installs three console scripts:

  • backlog-mcp — the stdio MCP server (one process per session)
  • backlog-agent — the HTTP MCP server (shared, single-writer; see below)
  • backlog-lint — the hygiene CLI

For the query tool install the agent extra:

pip install 'git+https://github.com/oholsen/backlog-mcp[agent]'

Configuration

All paths are environment-driven so the server can serve any project's backlog without code changes:

Env varDefaultPurpose
BACKLOG_PATHBacklog.mdMarkdown backlog
BACKLOG_SCORESBacklog-Scores.csv next to BACKLOG_PATHScoring CSV (optional; tools no-op if missing)
BACKLOG_REPO_ROOTgit rev-parse --show-toplevelRepo root for git grep / branch checks
BACKLOG_ARCHIVE_PREFIXDonePrefix matching the archive ## heading

Multi-agent workflow

                       git repository
                       ──────────────
         ┌─────────────────────────────────────────────────┐
         │                                                 │
         │  worktree: main        worktree: feat/auth      │
         │  ┌──────────────┐      ┌──────────────────┐     │
         │  │ Backlog.md   │      │ src/auth/…       │     │
         │  │ Backlog-     │      │ tests/auth/…     │     │
         │  │  Scores.csv  │      └──────────────────┘     │
         │  └──────┬───────┘                               │
         │         │              worktree: feat/api        │
         │         │              ┌──────────────────┐     │
         │         │              │ src/api/…        │     │
         │         │              │ tests/api/…      │     │
         └─────────┼──────────────┴──────────────────┴─────┘
                   │ reads / writes
                   ▼
         ┌─────────────────────┐
         │    backlog-agent    │   HTTP :8765
         │    (single writer,  │   ◄──────────────────────┐
         │     auto-commit)    │                          │
         └─────────────────────┘                   MCP tool calls

              Agent A                 Agent B                 Agent C
          ┌───────────────┐      ┌───────────────┐      ┌───────────────┐
          │ session: main │      │ feat/auth     │      │ feat/api      │
          │               │      │               │      │               │
          │ context:      │      │ context:      │      │ context:      │
          │ • full repo   │      │ • auth files  │      │ • api files   │
          │ • backlog     │      │ • backlog     │      │ • backlog     │
          │ • scores CSV  │      │ • scores CSV  │      │ • scores CSV  │
          │               │      │               │      │               │
          │ asks:         │      │ asks:         │      │ asks:         │
          │ • top priority│      │ • next item   │      │ • sequencing  │
          │ • value /     │      │   touching    │      │   — which     │
          │   complexity  │      │   auth files  │      │   items share │
          │   ranking     │      │ • blocked_by  │      │   api files?  │
          │ • what's      │      │   resolution  │      │ • file-level  │
          │   ready now?  │      │   order       │      │   conflict    │
          └───────┬───────┘      └───────┬───────┘      └───────┬───────┘
                  └──────────────────────┴──────────────────────┘
                                         │
                                    HTTP :8765

backlog-agent — shared HTTP server

For teams or when multiple agent sessions share the same backlog repo, backlog-agent runs as a single long-running process:

  • Single writer — an asyncio lock serialises all writes; no file races.
  • Auto-commit — each successful write is committed and pushed.
  • query tool — natural-language questions answered by an embedded Claude call with the full backlog in context (e.g. "what are the top auth items?").
BACKLOG_PATH=Backlog.md \
BACKLOG_REPO_ROOT=. \
ANTHROPIC_API_KEY=sk-... \
backlog-agent          # listens on 127.0.0.1:8765 by default
Env varDefaultPurpose
BACKLOG_AGENT_HOST127.0.0.1Bind address
BACKLOG_AGENT_PORT8765Bind port
BACKLOG_AGENT_AUTOCOMMITunsetSet to 1 to git-commit and push after each successful write
ANTHROPIC_API_KEY—Required for the query tool only
BACKLOG_AGENT_MODELclaude-sonnet-4-6Claude model for query

Wire each session to it instead of spawning per-session stdio processes. Two files per worktree:

.mcp.json at the worktree root — declares the server:

{
  "mcpServers": {
    "backlog": {
      "type": "http",
      "url": "http://localhost:8765/mcp/"
    }
  }
}

.claude/settings.json — opts the project in to the HTTP server (Claude Code requires explicit activation for HTTP MCP servers):

{
  "enabledMcpjsonServers": ["backlog"]
}

Without enabledMcpjsonServers the .mcp.json entry is ignored even when the agent is running.

Wire to Claude Code / Gemini CLI (stdio)

Drop a .mcp.json at your project root:

{
  "mcpServers": {
    "backlog": {
      "command": "backlog-mcp",
      "env": {
        "BACKLOG_PATH": "Backlog.md"
      }
    }
  }
}

Claude Code picks this up on session start; it'll prompt to approve the server the first time.

Sample CLAUDE.md

Tell Claude Code how to use the backlog by adding a CLAUDE.md at your repo root. A real-world example from a multi-worktree Rust project:

## Documentation Policy

Backlog.md lives at the repo root. It is managed exclusively on `main` — never
on worktrees or feature branches. Full rules (ID assignment, CHANGELOG flow,
docs/ audience buckets, customer-facing doc lifecycle):
**[`docs/process/Docs-Policy.md`](docs/process/Docs-Policy.md)**.

**Backlog keeper agent:** Use the `backlog-keeper` subagent
(`.claude/agents/backlog-keeper.md`) for all mechanical Backlog.md edits —
new items, IN PROGRESS flips, DONE flips, and CHANGELOG-INBOX entries. Invoke
it via the Agent tool with a plain-English instruction (e.g. "mark #677 DONE,
PR #264, 2026-04-29"). The agent handles ID assignment, collision checks, and
CHANGELOG-INBOX appends. It only operates on `main` — never on
feature branches.

## Worktree Pre-Flight (before `EnterWorktree`)

Always run the pre-flight checklist before creating a worktree.

Short version:
1. Check for conflicts: `grep "IN PROGRESS" Backlog.md`.
2. Mark your items `**IN PROGRESS (branch-name)**` on `main` (unstaged) — or
   invoke the `backlog-keeper` agent: "mark #NNN in progress on branch-name".
3. Create the worktree at `~/src/worktrees/<branch-name>` (not inside the
   workspace).

## Worktree Lifecycle

After merge:
1. `gh pr merge <N> --squash`
2. `git worktree remove ~/src/worktrees/<branch>`
3. `git branch -d <branch-name> && git pull`
4. Flip IN PROGRESS → DONE via the backlog-keeper agent.

The key patterns this illustrates:

  • Dedicated subagent for backlog edits keeps mechanical writes off the main session context.
  • main-only rule — Backlog.md lives on main; worktree sessions query via MCP but never edit the file directly.
  • Pre-flight + lifecycle hooks baked into CLAUDE.md so the agent enforces the workflow without user prompting.

Tools

Read (Phase 1)

ToolWhat it does
list_itemsFilter open items by status / section / score / tag / files (substring match against the files column)
get_itemFull description + score + status for one item
get_scoreScore row only (cheap pre-filter)
find_refsgit grep for #<id> across the whole repo
list_sectionsEnumerate sections + open-item counts
lintRun hygiene checks, return findings

Write

ToolWhat it does
add_itemCreate a new item; auto-assign next free ID; defaults to the ## Inbox section. Pass section to target a specific topical section. Verifies via lint and rolls back on failure.
update_statusFlip in_progress / done / open; requires branch for in_progress
set_scoreInsert or update a row in the scoring CSV

Reasoning (backlog-agent only)

ToolWhat it does
queryNatural-language question answered by Claude with the full backlog in context. Requires ANTHROPIC_API_KEY.

add_item expects a ## Inbox section in the backlog (above ## Done — archive) when no explicit section is given. Mirrors the CHANGELOG-INBOX → CHANGELOG buffer pattern: file fast, curate periodically. If you don't want this flow, pass an explicit section argument on every call.

CLI: backlog-lint

backlog-lint                          # uses BACKLOG_PATH or Backlog.md
backlog-lint --backlog path/to/X.md
backlog-lint --skip-branch-check      # no network; skip stale-marker check

Three checks (each fails the run with exit 1):

  1. Duplicate IDs across the whole file (open + archive).
  2. Unresolved git merge-conflict markers.
  3. Stale IN PROGRESS (branch-name) markers — branches not on origin (typically a merged-and-deleted PR; flip the marker to DONE or reset it).

CI usage (GitHub Actions):

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- run: pip install git+https://github.com/oholsen/backlog-mcp
- run: backlog-lint

Limitations

  • Concurrent edits (stdio). Two backlog-mcp stdio processes writing simultaneously will race. Use backlog-agent (HTTP) for shared access.
  • Cross-reference checking. Currently deferred — prose mixes "(PRs #X, #Y)" groups, "Agents.md #6" anchors, and "the #1 finding" with real refs; needs a smarter parser than is currently warranted.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados