Skip to main content
Glama
lhseokool

typescript-mcp-server-boilerplate

by lhseokool
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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 토큰이 필요합니다.

  1. 클라이언트 헤더 (권장): 요청마다 x-hf-token: hf_xxx 전달

  2. 서버 환경변수 (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 배포

  1. Vercel에 프로젝트를 연결합니다.

  2. Environment Variables에 HF_TOKEN을 추가합니다 (선택, 클라이언트 헤더만 쓸 경우 생략 가능).

  3. 배포 후 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"
            }
        }
    }
}

개발 가이드

MCP 도구 추가하기

src/mcp/register.ts의 registerMcp 함수 안에 server.tool(...) 을 추가합니다.

요청 컨텍스트 사용하기

src/mcp/context.ts의 resolveHfToken()으로 현재 요청의 HF 토큰을 읽을 수 있습니다. Route Handler에서 x-hf-token 헤더를 AsyncLocalStorage에 주입합니다.

주요 의존성

  • next: App Router 및 Vercel 배포

  • mcp-handler: Vercel용 MCP HTTP 어댑터

  • @modelcontextprotocol/sdk: MCP 프로토콜 SDK (1.26.0+)

  • @huggingface/inference: 이미지 생성

  • zod: 스키마 검증

스크립트

명령

설명

npm run dev

Next.js 개발 서버

npm run build

프로덕션 빌드

npm run start

프로덕션 서버 실행

npm run lint

Next.js 린트

참고 자료

라이선스

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lhseokool/my-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server