Servidor MCP backlog-mcp

backlog-mcp

Un servidor MCP que proporciona a los agentes de IA acceso estructurado de lectura/escritura a un backlog de proyectos basado en historias. Los agentes pueden listar historias, leer contenido, actualizar estados y añadir notas, todo respaldado por archivos markdown simples que residen dentro del repositorio de tu proyecto.

Cómo funciona la colaboración

No hay un servidor compartido. Los archivos del backlog residen en tu repositorio bajo requirements/, confirmados y versionados junto con tu código. La colaboración entre agentes, o entre un agente y un humano, funciona exactamente igual que el resto de tu base de código: a través de git. Si dos agentes actualizan historias diferentes simultáneamente, git los fusiona. Si tocan la misma línea, la resuelves como cualquier otro conflicto de fusión.

El servidor MCP es un proceso local que cada agente ejecuta por sí mismo. Lee y escribe archivos; git se encarga del resto.

Instalación

Descarga el binario más reciente para tu plataforma desde la página de Releases y colócalo en algún lugar de tu $PATH.

O, si tienes Go instalado:

go install github.com/corbym/backlog-mcp@latest

Construir desde el código fuente

go mod tidy
go build -o backlog-mcp .

Configuración

Inicializa una carpeta requirements/ en la raíz de tu proyecto:

./backlog-mcp init /path/to/your/project/requirements

Esto crea:

requirements/
  requirements-index.md   # master index — source of truth for epics and story status
  backlog.md              # priority-ordered list of not-done stories
  epic-001-example/
    story-001.md          # example story file

Confirma la carpeta requirements/ en tu repositorio. Edita los archivos para añadir tus propias épicas e historias.

Ejecución

./backlog-mcp

El servidor busca un directorio requirements/ relativo al directorio de trabajo desde el que se inicia. Claude Code establece el directorio de trabajo en la raíz del proyecto, por lo que no se necesita configuración.

Configuración de Claude Code (.claude/settings.json en tu proyecto, o ~/.claude/settings.json globalmente):

{
  "mcpServers": {
    "backlog-mcp": {
      "command": "/path/to/backlog-mcp"
    }
  }
}

Herramientas

Herramienta	Descripción
`list_stories`	Lista historias, opcionalmente filtradas por `epic_id` o `status`
`get_story`	Obtiene el contenido markdown completo y los metadatos de una historia
`set_story_status`	Actualiza el estado de la historia en el índice y el backlog
`add_story_note`	Añade una nota con marca de tiempo a un archivo de historia
`complete_story`	Marca una historia como terminada y añade un resumen de finalización obligatorio en una sola llamada
`create_epic`	Crea una nueva épica: asigna el siguiente ID EPIC-NNN, escribe el archivo de la épica, registra en el índice
`create_story`	Crea una nueva historia bajo una épica: asigna el siguiente ID STORY-NNN, registra en el índice y el backlog
`set_acceptance_criteria`	Reemplaza la sección de criterios de aceptación de una historia (idempotente)
`get_index_summary`	Recuento de alto nivel de épicas/historias por estado

Variables de entorno

Variable	Requerido	Predeterminado	Descripción
`BACKLOG_ROOT`	no	`requirements`	Sobrescribe la ruta al directorio de requisitos
`BACKLOG_TRANSPORT`	no	`stdio`	Establecer en `http` para el modo HTTP/SSE
`BACKLOG_HTTP_ADDR`	no	`0.0.0.0:8080`	Dirección de escucha para el modo HTTP

Formato de archivo

requirements-index.md — una sección de épica por encabezado, una historia por fila de tabla:

## EPIC-001: Combat System — `draft`

| Story | Title | Status |
|-------|-------|--------|
| [STORY-001](./epic-001-combat-system/story-001.md) | Basic combat | draft |

backlog.md — lista numerada ordenada por prioridad:

1. **STORY-001** — Basic combat
2. **STORY-002** — Enemy AI *(in-progress)*

Los archivos de historia residen en epic-NNN-slug/story-NNN.md bajo BACKLOG_ROOT.

Valores de estado: draft, in-progress, done, blocked

Notas

Las escrituras de archivos son atómicas (archivo temporal + renombrar): un bloqueo a mitad de la escritura no puede corromper tus archivos.
El sistema de archivos es la fuente de verdad. El servidor MCP nunca es propietario de los datos.