backlog-mcp

AI 에이전트에게 스토리 기반 프로젝트 백로그에 대한 구조화된 읽기/쓰기 액세스 권한을 제공하는 MCP 서버입니다. 에이전트는 프로젝트 저장소 내의 일반 마크다운 파일로 관리되는 스토리를 나열하고, 내용을 읽고, 상태를 업데이트하고, 메모를 추가할 수 있습니다.

협업 방식

공유 서버는 없습니다. 백로그 파일은 귀하의 저장소 내 requirements/ 폴더에 위치하며, 코드와 함께 커밋되고 버전 관리됩니다. 에이전트 간, 또는 에이전트와 사람 간의 협업은 코드베이스의 나머지 부분과 동일하게 git을 통해 이루어집니다. 두 에이전트가 서로 다른 스토리를 동시에 업데이트하면 git이 이를 병합합니다. 같은 줄을 수정하는 경우, 다른 병합 충돌과 마찬가지로 해결하면 됩니다.

이 MCP 서버는 각 에이전트가 스스로 실행하는 로컬 프로세스입니다. 서버는 파일을 읽고 쓰며, 나머지는 git이 처리합니다.

설치

Releases 페이지에서 플랫폼에 맞는 최신 바이너리를 다운로드하여 $PATH에 추가하세요.

또는 Go가 설치되어 있다면:

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

소스에서 빌드

go mod tidy
go build -o backlog-mcp .

설정

프로젝트 루트에 requirements/ 폴더를 초기화합니다:

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

이 작업은 다음을 생성합니다:

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

requirements/ 폴더를 저장소에 커밋하세요. 파일을 편집하여 나만의 에픽과 스토리를 추가하세요.

실행

./backlog-mcp

서버는 실행된 작업 디렉토리를 기준으로 requirements/ 디렉토리를 찾습니다. Claude Code는 작업 디렉토리를 프로젝트 루트로 설정하므로 별도의 설정이 필요하지 않습니다.

Claude Code 설정 (프로젝트 내 .claude/settings.json 또는 전역 ~/.claude/settings.json):

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

도구

환경 변수

파일 형식

requirements-index.md — 헤딩당 하나의 에픽 섹션, 테이블 행당 하나의 스토리:

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

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

backlog.md — 우선순위가 지정된 번호 매기기 목록:

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

스토리 파일은 BACKLOG_ROOT 아래의 epic-NNN-slug/story-NNN.md에 위치합니다.

상태 값: draft, in-progress, done, blocked

참고

• 파일 쓰기는 원자적(임시 파일 생성 + 이름 변경)으로 이루어지므로, 쓰기 도중 충돌이 발생해도 파일이 손상되지 않습니다.

• 파일 시스템이 진실의 원천(source of truth)입니다. MCP 서버는 데이터를 소유하지 않습니다.