Metadata-Version: 2.4
Name: intenttrack-mcp
Version: 0.2.0
Summary: IntentTrack MCP server — stdio bridge to the hosted /mcp endpoint
Author: dchain-enterprise
License: Proprietary
Keywords: intenttrack,mcp,qa,spec,stdio
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4.0,>=3.12
Requires-Dist: fastmcp<4,>=3.4.0
Description-Content-Type: text/markdown

# 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://github.com/dchain-enterprise/intent-tracking-system/blob/main/docs/mcp-guide.md)
에 있다. 아래 예시의 `https://intenttrack.example.com` 은 자리표시자다.

## 등록

### uvx (이 패키지)

```bash
claude mcp add intenttrack \
  --env INTENTTRACK_API_URL=https://intenttrack.example.com \
  --env INTENTTRACK_API_TOKEN=itk_... \
  -- uvx intenttrack-mcp
```

또는 `.mcp.json`:

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

| env | 필수 | 기본값 | 설명 |
|---|---|---|---|
| `INTENTTRACK_API_TOKEN` | ✅ | — | 개인 MCP 토큰 (`itk_…`) |
| `INTENTTRACK_API_URL` | | `http://localhost:8000` | api 주소. `/mcp/` 는 자동으로 붙는다 |
| `INTENTTRACK_MCP_URL` | | — | MCP 경로를 통째로 덮어쓴다 (`/mcp/` 가 아닌 배포용) |

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

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

```json
{
  "mcpServers": {
    "intenttrack": {
      "type": "http",
      "url": "https://intenttrack.example.com/mcp/",
      "headers": { "Authorization": "Bearer itk_..." }
    }
  }
}
```

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

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

```bash
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절](https://github.com/dchain-enterprise/intent-tracking-system/blob/main/docs/mcp-guide.md#8-브리지-패키지-릴리스-메인테이너)
에 있다.

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