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 참고.

등록

uvx (이 패키지)

claude mcp add intenttrack \
  --env INTENTTRACK_API_URL=https://intent-tracking-system-stage.bucks.dchain-connect.com \
  --env INTENTTRACK_API_TOKEN=itk_... \
  -- uvx intenttrack-mcp

또는 .mcp.json:

{
  "mcpServers": {
    "intenttrack": {
      "command": "uvx",
      "args": ["intenttrack-mcp"],
      "env": {
        "INTENTTRACK_API_URL": "https://intent-tracking-system-stage.bucks.dchain-connect.com",
        "INTENTTRACK_API_TOKEN": "itk_..."
      }
    }
  }
}

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

{
  "mcpServers": {
    "intenttrack": {
      "type": "http",
      "url": "https://intent-tracking-system-stage.bucks.dchain-connect.com/mcp/",
      "headers": { "Authorization": "Bearer itk_..." }
    }
  }
}

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

게시 전 / 로컬 개발 버전

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

스모크 테스트

cd apps/mcp && uv sync --dev
INTENTTRACK_API_URL=http://localhost:8000 INTENTTRACK_API_TOKEN=itk_... \
  uv run python -c "
import anyio
from fastmcp import Client
from intenttrack_mcp.server import build_proxy
async def go():
    async with Client(build_proxy()) as c:
        print(await c.call_tool('whoami'))
anyio.run(go)"

검증

make check-mcp   # ruff + mypy + pytest

릴리스 (PyPI 게시)

mcp-v* 태그를 push 하면 .github/workflows/mcp-release.yml 이 검증 후 PyPI 에 게시한다.

1. apps/mcp/pyproject.toml 의 version 을 올린다 (예: 0.1.0 → 0.2.0).

2. 커밋 후 태그를 버전과 정확히 일치시켜 push:

   git commit -am "chore(mcp): bump version to 0.2.0"
   git tag mcp-v0.2.0
   git push origin mcp-v0.2.0
   

3. 워크플로가 ruff → mypy → pytest → 버전 일치 확인 → uv build → uv publish.

전제조건: repo(또는 org) secret PYPI_API_TOKEN. PyPI 는 같은 버전 재게시가 안 되므로 실패했으면 버전을 올려 다시 태그한다.

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