MCP 服务器

typescript-mcp-server-boilerplate

A boilerplate for building and deploying MCP servers on Vercel, featuring example tools like greeting, calculator, weather, and Hugging Face image generation.

README

TypeScript MCP Server 보일러플레이트

TypeScript MCP SDK와 mcp-handler를 활용하여 Model Context Protocol (MCP) 서버를 빠르게 개발하고 Vercel에 배포할 수 있는 보일러플레이트 프로젝트입니다.

전송 방식은 Streamable HTTP (/api/mcp)이며, Stdio 대신 Next.js App Router Route Handler로 동작합니다.

프로젝트 구조

typescript-mcp-server-boilerplate/
├── app/
│   ├── api/
│   │   └── [transport]/
│   │       └── route.ts      # MCP HTTP 엔드포인트 (GET/POST/DELETE)
│   ├── layout.tsx
│   └── page.tsx
├── src/
│   └── mcp/
│       ├── context.ts          # x-hf-token 요청 컨텍스트 (AsyncLocalStorage)
│       ├── register.ts         # 도구/리소스/프롬프트 등록
│       └── prompts/
│           └── code-review.ts
├── next.config.ts
├── vercel.json
├── package.json
└── .cursor/mcp.json            # Cursor MCP 연결 예시

시작하기

1. 의존성 설치

npm install

2. 환경 변수 (선택)

로컬에서 서버 측 HF 토큰 fallback을 쓰려면 .env 파일을 만듭니다:

cp .env.example .env
# HF_TOKEN=hf_xxx

클라이언트가 x-hf-token 헤더를내면 헤더 값이 우선되고, 없을 때만 HF_TOKEN 환경변수를 사용합니다.

3. 개발 서버 실행

npm run dev

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

4. 프로덕션 빌드

npm run build
npm run start

등록된 기능

종류	이름	설명
Tool	`greeting`	이름으로 인사
Tool	`calculator`	사칙연산 (add/subtract/multiply/divide)
Tool	`calculate`	연산자 기호 사칙연산
Tool	`get_time`	시간대별 현재 시각
Tool	`generate_image`	Hugging Face FLUX 이미지 생성
Tool	`geocode`	OpenStreetMap Nominatim 지오코딩
Tool	`get_weather`	Open-Meteo 날씨 조회
Resource	`server-info`	서버 메타데이터 JSON
Prompt	`code_review`	코드 리뷰 프롬프트 템플릿

x-hf-token 헤더 (이미지 생성)

generate_image 도구는 Hugging Face API 토큰이 필요합니다.

클라이언트 헤더 (권장): 요청마다 x-hf-token: hf_xxx 전달
서버 환경변수 (fallback): Vercel/로컬에 HF_TOKEN 설정

우선순위: x-hf-token 헤더 → HF_TOKEN 환경변수

Cursor MCP 연결

npm run dev 실행 후 .cursor/mcp.json을 참고하세요:

{
    "mcpServers": {
        "typescript-mcp-server": {
            "url": "http://localhost:3000/api/mcp",
            "headers": {
                "x-hf-token": "YOUR_HUGGING_FACE_TOKEN_HERE"
            }
        }
    }
}

Cursor 0.48+ 에서는 Streamable HTTP URL을 직접 지원합니다.

Stdio 전용 클라이언트 (Claude Desktop 등)

mcp-remote로 HTTP 서버에 프록시합니다:

{
    "mcpServers": {
        "typescript-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:3000/api/mcp",
                "--header",
                "x-hf-token:YOUR_HUGGING_FACE_TOKEN_HERE"
            ]
        }
    }
}

Vercel 배포

Vercel에 프로젝트를 연결합니다.
Environment Variables에 HF_TOKEN을 추가합니다 (선택, 클라이언트 헤더만 쓸 경우 생략 가능).
배포 후 MCP URL: https://<your-project>.vercel.app/api/mcp

vercel.json에서 MCP Route Handler의 maxDuration을 60초로 설정해 두었습니다. Pro 플랜 이상에서 더 긴 이미지 생성이 필요하면 값을 조정하세요.

배포 후 Cursor 연결 예시

{
    "mcpServers": {
        "typescript-mcp-server": {
            "url": "https://<your-project>.vercel.app/api/mcp",
            "headers": {
                "x-hf-token": "YOUR_HUGGING_FACE_TOKEN_HERE"
            }
        }
    }
}