intenttrack-mcp

IntentTrack 의 기획 스펙(화면설계서)·QA 시나리오를 다른 저장소에서 MCP 로 읽고 쓰는 stdio 브리지.

저장소를 클론하지 않고 uvx intenttrack-mcp 로 붙는다.

어떻게 생겼나 — 도구는 여기 없다

도구 정의는 api 프로세스의 apps/api/api/mcp_server.py 한 곳에만 있고 /mcp/ 로 서비스된다. 이 패키지는 그 엔드포인트를 stdio 로 중계하는 프록시(fastmcp.server.create_proxy)다.

다른 프로젝트의 MCP 클라이언트 ──stdio──▶ intenttrack-mcp ──HTTP+Bearer──▶ api /mcp/

• 서버에 도구가 늘거나 인자가 바뀌어도 이 패키지를 다시 배포할 필요가 없다.
• 권한 검사는 서버에서 그대로 돈다. 토큰은 발급자 권한의 부분집합이라 MCP 로 권한이 넓어지지 않는다.

HTTP MCP 를 직접 지원하는 클라이언트(Claude Code 등)는 이 패키지가 필요 없다 — 아래 "직접 HTTP" 설정이 더 짧고 홉이 하나 적다. 이 브리지는 stdio 만 쓰거나 커스텀 헤더를 못 넣는 클라이언트용이다.

준비

웹 우측 상단 MCP 토큰 → 토큰 발급. 평문 itk_… 는 발급 직후 한 번만 보인다. scope 표준과 실제 배포 주소는 저장소의 docs/mcp-guide.md 에 있다. 아래 예시의 https://intenttrack.example.com 은 자리표시자다.

등록

uvx (이 패키지)

claude mcp add intenttrack \
  --env INTENTTRACK_API_URL=https://intenttrack.example.com \
  --env INTENTTRACK_API_TOKEN=itk_... \
  --env INTENTTRACK_SERVICE=my-project \
  -- uvx intenttrack-mcp

또는 .mcp.json:

{
  "mcpServers": {
    "intenttrack": {
      "command": "uvx",
      "args": ["intenttrack-mcp"],
      "env": {
        "INTENTTRACK_API_URL": "https://intenttrack.example.com",
        "INTENTTRACK_API_TOKEN": "itk_...",
        "INTENTTRACK_SERVICE": "my-project"
      }
    }
  }
}

INTENTTRACK_SERVICE 는 X-IntentTrack-Service 헤더로 붙는다. 잠금이 아니라 기본값이라 도구에 service 를 명시하면 그쪽이 이기고, 지금 무엇에 고정돼 있는지는 whoami() 의 service_pin 에서 확인한다. 안 주면 도구마다 service 를 지정해야 한다.

⚠️ INTENTTRACK_API_URL 에는 /mcp/ 를 붙이지 않는다 — api 주소만 준다. 붙이면 /mcp/mcp/ 가 되어 404 다. 경로 자체를 바꿔야 하면 INTENTTRACK_MCP_URL 을 쓴다.

직접 HTTP (클라이언트가 지원하면 이쪽)

{
  "mcpServers": {
    "intenttrack": {
      "type": "http",
      "url": "https://intenttrack.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer itk_...",
        "X-IntentTrack-Service": "my-project"
      }
    }
  }
}

⚠️ 실제 토큰이 든 .mcp.json 은 커밋하지 않는다. 개인 설정(~/.claude.json, claude mcp add)을 쓴다.

로컬 개발 버전 (게시본 대신 작업 트리로 붙는다)

uv run --directory /path/to/intent-tracking-system/apps/mcp intenttrack-mcp

메인테이너

검증(make check-mcp)·게시 산출물 스모크(apps/mcp/smoke-wheel.sh)·릴리스 절차(mcp-v* 태그)는 저장소 문서 docs/mcp-guide.md 8절 에 있다.

버전을 올려야 하는 변경은 이 패키지(브리지) 자체가 바뀔 때뿐이다. 도구 추가·변경은 api 배포만으로 모든 사용자에게 즉시 반영된다.