# my-mcp-server

Next.js + [`mcp-handler`](https://github.com/vercel/mcp-handler) 기반 Streamable HTTP MCP 서버입니다. Vercel에 배포할 수 있습니다.

## 구조

```
app/
  api/[transport]/route.ts   # HTTP MCP 엔드포인트 (/api/mcp)
  page.tsx
  layout.tsx
lib/mcp/
  server.ts                  # 도구·프롬프트·리소스 등록
  helpers.ts
  request-context.ts         # x-hf-token 요청 컨텍스트
```

## 로컬 실행

```bash
npm install
npm run dev
```

MCP 엔드포인트: `http://localhost:3000/api/mcp`

### MCP Inspector로 테스트

```bash
npx @modelcontextprotocol/inspector
```

- Transport: **Streamable HTTP**
- URL: `http://localhost:3000/api/mcp`

## Cursor 연결

로컬:

```json
{
  "mcpServers": {
    "my-mcp-server": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "x-hf-token": "hf_your_token_here"
      }
    }
  }
}
```

Vercel 배포 후:

```json
{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://YOUR_PROJECT.vercel.app/api/mcp",
      "headers": {
        "x-hf-token": "hf_your_token_here"
      }
    }
  }
}
```

## HF 토큰 (`x-hf-token`)

`generate-image` 도구는 Hugging Face Inference API를 사용합니다. 토큰 우선순위:

1. 요청 커스텀 헤더 `x-hf-token` (클라이언트별 입력)
2. 서버 환경변수 `HF_TOKEN` (선택적 폴백)

클라이언트에서 헤더로 넘기면 서버에 토큰을 고정 저장하지 않아도 됩니다.

## Vercel 배포

```bash
npx vercel
```

또는 GitHub 연동 후 Vercel 대시보드에서 Import.

선택적으로 서버 공통 폴백 토큰을 쓰려면 Vercel 프로젝트에 `HF_TOKEN`을 설정하세요.

참고:

- [Deploy MCP servers to Vercel](https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel)
- [vercel/mcp-handler](https://github.com/vercel/mcp-handler)

## 제공 기능

| 종류 | 이름 | 설명 |
|------|------|------|
| Tool | `greet` | 인사말 |
| Tool | `calculator` | 사칙연산 |
| Tool | `get-time` | 타임존 현재 시간 |
| Tool | `geocode` | 도시 → 좌표 |
| Tool | `get-weather` | 날씨/예보 |
| Tool | `generate-image` | FLUX.1-schnell 이미지 생성 |
| Resource | `info://server` | 서버 정보 |
| Prompt | `code-review` | 코드 리뷰 프롬프트 |

## 스크립트

- `npm run dev` — 로컬 개발 서버
- `npm run build` — 프로덕션 빌드
- `npm start` — 프로덕션 서버

## 라이선스

MIT