punkpeye/fastmcp

FastMCP – 빠른 개요

무엇인가요 – FastMCP는 Model Context Protocol (MCP)를 지원하는 서버를 빌드하기 위한 TypeScript 프레임워크입니다. MCP는 LLM(또는 기타 AI 에이전트)이 도구를 호출하고 리소스를 가져오며 백엔드 서버와 구조화된 데이터를 교환할 수 있게 해주는 프로토콜입니다. FastMCP는 공식 MCP SDK를 래핑하고, 도구, 리소스, 프롬프트 등을 정의하는 데 집중할 수 있도록 많은 내부 처리를 제공합니다.

주요 기능

Zod, ArkType, Valibot 또는 원시 JSON Schema를 지원하는 간단하고 타입 안전한 API로 도구, 리소스, 프롬프트 정의.
내장된 인증, 세션 및 요청 ID 추적, 에러 처리.
여러 가지 전송 옵션:
- stdio (로컬 CLI 사용용)
- HTTP 스트리밍 (효율적인 바이너리 친화적 스트리밍, SSE 백업 제공)
- 사용자 지정 인증서, CORS 설정, 헬스체크 엔드포인트를 갖춘 HTTPS.
기반 Hono 앱을 통한 사용자 정의 HTTP 라우트 – MCP 엔드포인트와 함께 REST API, 웹훅, 관리 페이지 등을 노출할 수 있습니다.
에지 런타임 지원 – 가벼운 EdgeFastMCP 클래스를 통해 Cloudflare Workers, Deno Deploy 등에서 동일한 서버를 실행할 수 있습니다 (에지에서는 상태 없음 모드만 지원).
상태 없음 모드 – 서버리스 배포용. 각 요청마다 일시적인 세션이 생성되며, 지속적인 상태는 유지되지 않습니다.
편의 기능: 진행률 알림, 스트리밍 출력, 타입 안전한 서버 이벤트, 프롬프트 인수 자동 완성, 샘플링/유도 제어, 설정 가능한 핑, 메모리 내 전송(단위 테스트용), CLI(fastmcp dev, fastmcp inspect).

사용할 시기 – 공식 SDK가 요구하는 저수준 소켓 처리를 작성하고 싶지 않다면 FastMCP를 선택하세요. 빠른 프로토타이핑이나 인증, HTTPS, 사용자 정의 라우트, 에지 배포가 필요한 프로덕션 서비스에 이상적입니다. 모든 세부 사항을 완전히 제어하고 싶다면 원시 SDK가 여전히 선호될 수 있습니다.

일반적인 워크플로우

npm install fastmcp
기본 메타데이터로 FastMCP 인스턴스 생성.
server.addTool(...) 등으로 도구/리소스 추가. 스키마(Zod 등)와 비동기 execute 함수 제공.
server.start({ transportType: "httpStream", httpStream: { port: 8080 } }) 호출 (CLI용은 stdio 사용).
선택적으로 server.getApp()를 통해 사용자 정의 Hono 라우트 추가 (REST 엔드포인트 또는 웹훅용).
배포 – Node 서버에서 실행하거나 EdgeFastMCP로 전환하여 Cloudflare Workers에 배포.

예시 스니펫 (README에서)는 npx fastmcp dev src/examples/addition.ts로 로컬에서 실행 가능한 작은 덧셈 도구를 보여줍니다.

빠른 참조

패키지: fastmcp (npm)
언어: TypeScript
주요 런타임: Node.js (Cloudflare Workers, Deno Deploy용은 EdgeFastMCP)
전송 옵션: stdio, httpStream (옵션으로 HTTPS), SSE 백업
인증: 플러그인 가능한 authenticate 콜백; API 키, OAuth 등과 호환.
테스트: 메모리 내 전송, CLI 개발 모드, 인스펙터 UI.

결론 – FastMCP는 MCP 기반 AI 서비스 백엔드를 구축하기 위한 진정한 프로덕션 준비된 프레임워크로, 프로토콜 세부 사항, 보안, 배포 문제를 처리하여 개발자가 AI 전용 로직에 집중할 수 있도록 합니다.

punkpeye/fastmcp

FastMCP – 빠른 개요

빠른 참조

관련