@spec-flow/mcp

IDE의 코딩 에이전트(Cursor / Claude Code / Codex CLI 등)를 SpecFlow 프로젝트에 연결하는 stdio 기반 MCP 서버입니다. 브리지 모델로 동작합니다 — 실제 코드 작성/테스트는 IDE 에이전트가, 컨텍스트 공급·상태/결과 회수는 이 서버가 담당합니다.

npm에 배포되어 있어 별도 설치 없이 npx로 실행됩니다.

설정 (실행 인자 또는 환경변수)

CLI 인자가 환경변수보다 우선합니다.

| 인자 | 환경변수 | 필수 | 설명 | |---|---|---|---| | --api-key= | SPECFLOW_API_KEY | ✅ | 프로젝트별 sf_mcp_ 연동키 (SpecFlow 웹 > 테스크 현황 > "MCP 연동"에서 발급) | | --backend-url= | BACKEND_URL | | SpecFlow 백엔드 주소 (기본 http://localhost:8080) |

에이전트별 연결 방법

Claude Code / Codex CLI — 터미널 1줄:

claude mcp add specflow -- npx -y --package=@spec-flow/mcp@latest specflow --api-key=sf_mcp_... --backend-url=http://localhost:8080
codex  mcp add specflow -- npx -y --package=@spec-flow/mcp@latest specflow --api-key=sf_mcp_... --backend-url=http://localhost:8080

Cursor / 기타 — MCP 설정(mcpServers)에 추가:

{
  "mcpServers": {
    "specflow": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@spec-flow/mcp@latest",
        "specflow",
        "--api-key=sf_mcp_...",
        "--backend-url=http://localhost:8080"
      ]
    }
  }
}

제공 도구 (Tools)

| tool | 설명 | |---|---| | setup_project | 키에 바인딩된 프로젝트에 연결하고, 자동 진행 프로토콜·개발 규칙이 담긴 온보딩 가이드를 반환 | | get_next_task | 선행 작업이 완료된 TODO 중 우선순위(P0>P1>P2) 최상위 작업 1건 | | get_task_prompt | 특정 태스크의 개발 지시서(명세·규칙·연관정보 조립) 반환 | | list_tasks | 태스크 목록(우선순위 정렬, status 필터) | | update_task_status | 태스크 상태 변경 (TODO/IN_PROGRESS/TESTING/SONAR_SCAN/DONE) | | submit_task_result | 검증 결과(성공/실패·커밋해시·요약) 제출 + 상태 갱신 | | get_specs | 프로젝트 최신 PRD/TRD 명세 + ERD 조회 (넓은 맥락용) | | create_task | 작업 중 발견한 새 할 일을 태스크로 역등록 | | add_task_note | 태스크에 진행 메모/결정 근거 기록 | | add_task_blocker | 진행 불가 상황을 태스크에 블로커로 기록 | | get_task_history | 태스크의 지난 이력(검증 리포트 + 노트/블로커) 최신순 조회 |

전형적 사용 흐름: setup_project → (get_next_task → get_task_prompt → 구현 → submit_task_result) 반복.

CLI로 직접 실행 (터미널·스크립트·CI)

위 tool들을 IDE의 MCP 에이전트 없이 터미널에서 직접 실행할 수 있습니다. 서버 모드와 같은 bin(specflow) 이 위치 인자(서브커맨드)를 받으면 CLI로 동작합니다.

• 명령명 = tool 이름의 언더스코어를 하이픈으로 (get_next_task → get-next-task)
• 플래그 = tool 인자를 kebab-case로 (taskId → --task-id, commit_hash → --commit-hash)
• 인증 = --api-key= / --backend-url= (또는 env)

# 설치 (최초 1회) — 또는 npx로 매번 실행 가능
npm i -g @spec-flow/mcp@latest

# 전체 명령·플래그 목록
specflow list

# 예시
specflow get-next-task --api-key=sf_mcp_... --backend-url=http://localhost:8080
specflow list-tasks --status TODO --api-key=sf_mcp_... --backend-url=http://localhost:8080
specflow submit-task-result --task-id <ID> --passed --commit-hash abc123 --status DONE --api-key=sf_mcp_... --backend-url=...
specflow add-task-blocker --task-id <ID> --reason "환경변수 누락" --api-key=sf_mcp_... --backend-url=...

# 설치 없이 npx로
npx -y --package=@spec-flow/mcp@latest specflow get-next-task --api-key=sf_mcp_... --backend-url=...

• 불리언 인자는 플래그 존재로 참(--passed), 배열은 콤마 구분(--dependencies a,b)입니다.
• 결과는 stdout으로 출력되고, 필수 플래그 누락·에러 시 종료코드 1을 반환합니다.
• 위치 인자 없이 실행(specflow 또는 specflow serve)하면 기존 stdio MCP 서버로 동작합니다.

새 tool 추가하기 (확장 가이드)

tool은 index.js의 TOOLS 레지스트리 배열로 관리됩니다. { definition, handler } 항목 하나만 추가하면 ListTools/CallTool 배선이 자동 반영됩니다.

const TOOLS = [
  // ...기존 tool들...
  {
    definition: {
      name: "my_new_tool",
      description: "이 tool이 하는 일 (에이전트가 언제 호출할지 판단하는 근거이므로 명확히)",
      inputSchema: {
        type: "object",
        properties: { foo: { type: "string", description: "설명" } },
        required: ["foo"],
      },
    },
    handler: async (args) => {
      // 여러 번 호출해도 결과가 같은 조회(GET)는 withRetry로 감싸 일시 오류에 대비합니다.
      const { data } = await withRetry(() => http.get(`/mcp/...`));
      // 상태 변경·결과 제출(POST/PATCH)은 재시도 시 중복이 생길 수 있어 감싸지 않습니다.
      return json(data); // 또는 return text("...")
    },
  },
];

규칙:

• 인증: http 인스턴스가 모든 요청에 연동키를 자동 주입합니다.
• projectId 불필요: 백엔드 /mcp/* 엔드포인트가 키에서 프로젝트를 유추합니다.
• 재시도: 여러 번 호출해도 안전한 조회(GET)에만 withRetry(...) 적용.
• 반환: 구조화 데이터는 json(obj), 에이전트가 그대로 읽을 텍스트는 text(str).

로컬 개발 실행

cd mcp
npm install
SPECFLOW_API_KEY=sf_mcp_... BACKEND_URL=http://localhost:8080 npm start
# 또는
node index.js --api-key=sf_mcp_... --backend-url=http://localhost:8080

npm 배포

@spec-flow/mcp는 스코프 패키지이므로 npm에 **spec-flow 조직(organization)**이 있어야 합니다.

# 1) npmjs.com에서 조직 "spec-flow" 생성 (Add Organization, Free 플랜)
# 2) CLI 로그인
npm login
# 3) 배포 (publishConfig.access=public 이 설정돼 있어 공개 배포)
cd mcp
npm publish
# 계정에 2FA가 켜져 있으면 인증앱 6자리 코드로:
# npm publish --otp=123456

조직명 spec-flow가 이미 점유돼 있으면 사용 가능한 스코프(예: @specflow-ai/mcp)로 바꾸고 package.json의 name과 프론트엔드 모달의 NPM_PACKAGE 상수를 함께 변경하세요. 버전을 올려 재배포하려면 package.json의 version을 증가시킨 뒤 npm publish 하세요.