# MG6 MCP Server

Next.js(App Router) 위에서 **Streamable HTTP**로 동작하는 MCP 서버입니다. Vercel에 그대로 배포할 수 있습니다.

기존 `StdioServerTransport` 기반 로컬 서버를 [`mcp-handler`](https://github.com/vercel/mcp-handler) 기반 HTTP 라우트로 옮긴 구조입니다.

## 구조

```
app/
  api/mcp/route.ts          MCP 엔드포인트 (GET/POST/DELETE)
  layout.tsx, page.tsx      서버 정보를 보여주는 안내 페이지
src/mcp/
  register.ts               도구·리소스·프롬프트 등록 진입점
  server-info.ts            서버 이름/버전, 커스텀 헤더 이름
  helpers.ts                공용 헬퍼 (fetch, 결과 포맷, 에러 변환 등)
  hf-token.ts               요청 헤더 → 환경변수 순으로 HF 토큰 결정
  tools/                    도구 5종
  resources/                리소스
  prompts/                  프롬프트
```

## 실행

```bash
npm install
npm run dev     # http://localhost:3000/api/mcp
```

빌드 및 프로덕션 실행:

```bash
npm run build
npm run start
```

## 제공 기능

| 도구 | 설명 |
| --- | --- |
| `greet` | 이름과 언어로 인사말 생성 |
| `calculate` | 두 숫자와 연산자로 사칙연산 |
| `geocode` | 도시명 → 위도·경도 (Open-Meteo Geocoding) |
| `get_weather` | 좌표 → 현재 날씨·일별 예보 (Open-Meteo Forecast) |
| `generate-image` | 프롬프트 → 이미지 (HuggingFace FLUX.1-schnell) |

리소스 `mg6://server-info`, 프롬프트 `code-review`도 함께 제공합니다.

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

`generate-image`는 다음 순서로 토큰을 찾습니다.

1. 요청의 **`x-hf-token` 헤더** — 클라이언트가 자기 토큰을 직접 전달
2. 서버의 **`HF_TOKEN` 환경변수** — 헤더가 없을 때의 기본값

공개 배포라면 `HF_TOKEN`을 비워 두고 각 클라이언트가 자기 토큰을 헤더로 보내게 하는 편이 안전합니다. 토큰은 요청 처리 중에만 사용되고 저장되지 않습니다.

토큰 발급: <https://huggingface.co/settings/tokens>

## MCP 클라이언트 설정

`.cursor/mcp.json`:

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

배포 후에는 `url`을 `https://<your-project>.vercel.app/api/mcp`로 바꿉니다.

Streamable HTTP를 지원하지 않는 stdio 전용 클라이언트는 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)로 연결합니다.

```json
{
    "mcpServers": {
        "MG6_Server": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
        }
    }
}
```

## Vercel 배포

1. 저장소를 Vercel 프로젝트로 import 합니다. (프레임워크 자동 감지: Next.js)
2. 서버 기본 토큰을 쓸 경우에만 환경변수 `HF_TOKEN`을 등록합니다.
3. 배포 후 엔드포인트는 `https://<your-project>.vercel.app/api/mcp` 입니다.

이미지 생성은 수십 초가 걸릴 수 있어 라우트에 `maxDuration = 60`을 지정해 두었습니다. 더 긴 실행이 필요하면 Fluid compute를 켜고 값을 올리세요.

## 인스펙터로 확인하기

```bash
npm run inspector
```

인스펙터에서 Transport를 **Streamable HTTP**로, URL을 `http://localhost:3000/api/mcp`로 지정합니다. `generate-image`를 테스트하려면 Configuration에서 `x-hf-token` 헤더를 추가하세요.

## 도구 추가하기

`src/mcp/tools/`에 등록 함수를 만들고 `src/mcp/register.ts`에서 호출하면 됩니다.

```ts
import type { McpServer } from '@modelcontextprotocol/server'
import { z } from 'zod'

import { textOutputSchema, textResult } from '../helpers'

export function registerEcho(server: McpServer) {
    server.registerTool(
        'echo',
        {
            title: '에코',
            description: '입력을 그대로 돌려줍니다.',
            inputSchema: z.object({ message: z.string() }),
            outputSchema: textOutputSchema('에코 결과')
        },
        async ({ message }) => textResult(message)
    )
}
```

핸들러의 두 번째 인자 `ctx`로 원본 HTTP 요청에 접근할 수 있습니다. (`ctx.http?.req?.headers`)

## 참고

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

Weather data by [Open-Meteo.com](https://open-meteo.com/) (CC BY 4.0)