fastmcp

FastMCP - TypeScript MCP 서버 프레임워크

프로젝트 개요

FastMCP는 Model Context Protocol (MCP) 서버 구축을 위해 특별히 설계된 TypeScript 프레임워크입니다. 클라이언트 세션을 처리할 수 있는 고성능 MCP 서버를 빠르게 만들 수 있도록 완벽한 도구와 기능을 제공합니다.

프로젝트 주소: https://github.com/punkpeye/fastmcp

핵심 기능

기본 기능

• 간단한 도구, 리소스 및 프롬프트 정의: 서버 기능을 정의하기 위한 직관적인 API 제공
• 인증 지원: 안전한 접근을 보장하는 내장 인증 메커니즘
• 세션 관리: 클라이언트 세션 처리 및 상태 관리 지원
• 멀티미디어 콘텐츠 지원: 이미지 및 오디오 콘텐츠 반환 지원
• 로그 기록: 디버깅 및 모니터링을 위한 완벽한 로그 시스템
• 오류 처리: 통합된 오류 처리 메커니즘
• Server-Sent Events (SSE): 실시간 데이터 푸시 지원
• CORS 지원: 기본적으로 활성화된 교차 출처 리소스 공유

고급 기능

• 진행률 알림: 도구 실행 과정 중 실시간 진행률 피드백
• 타입화된 서버 이벤트: TypeScript 타입 안전 이벤트 시스템
• 프롬프트 매개변수 자동 완성: 스마트 매개변수 자동 완성 기능
• 샘플링 요청: AI 모델 샘플링 요청 지원
• 자동화된 SSE 하트비트: 연결 안정성 유지
• 루트 디렉토리 관리: 파일 시스템 루트 디렉토리 구성
• CLI 도구: 테스트 및 디버깅 명령줄 도구 제공

설치 및 사용

설치

npm install fastmcp

기본 예제

import { FastMCP } from "fastmcp";
import { z } from "zod"; 

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

server.start({
  transportType: "stdio",
});

주요 기능 모듈

1. 도구 정의 (Tools)

도구를 통해 서버는 클라이언트가 실행할 수 있는 함수를 공개할 수 있으며, 이러한 함수는 클라이언트에서 호출하고 LLM에서 작업을 실행하는 데 사용할 수 있습니다.

지원되는 스키마 검증 라이브러리

• Zod: 가장 인기 있는 TypeScript 스키마 검증 라이브러리
• ArkType: 현대적인 타입 검증 라이브러리
• Valibot: 경량 스키마 검증 라이브러리

Zod 예제

import { z } from "zod";

server.addTool({
  name: "fetch-zod",
  description: "Fetch the content of a url (using Zod)",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

도구 어노테이션

도구는 어노테이션을 포함하여 더 풍부한 컨텍스트와 제어 정보를 제공할 수 있습니다.

server.addTool({
  name: "fetch-content",
  description: "Fetch content from a URL",
  parameters: z.object({
    url: z.string(),
  }),
  annotations: {
    title: "Web Content Fetcher", 
    readOnlyHint: true, 
    openWorldHint: true,
  },
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

2. 리소스 관리 (Resources)

리소스는 MCP 서버가 클라이언트에 제공하고자 하는 모든 유형의 데이터를 나타냅니다.

• 파일 내용
• 스크린샷 및 이미지
• 로그 파일
• 기타 데이터

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

리소스 템플릿

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "Application Logs",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "Name of the log",
      required: true,
    },
  ],
  async load({ name }) {
    return {
      text: `Example log content for ${name}`,
    };
  },
});

3. 프롬프트 관리 (Prompts)

프롬프트를 통해 서버는 재사용 가능한 프롬프트 템플릿과 워크플로우를 정의할 수 있습니다.

server.addPrompt({
  name: "git-commit",
  description: "Generate a Git commit message",
  arguments: [
    {
      name: "changes",
      description: "Git diff or description of changes",
      required: true,
    },
  ],
  load: async (args) => {
    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
  },
});

4. 인증

FastMCP는 사용자 정의 인증 기능을 지원합니다.

import { AuthError } from "fastmcp";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: ({ request }) => {
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== "123") {
      throw new Response(null, {
        status: 401,
        statusText: "Unauthorized",
      });
    }
    return {
      id: 1,
    };
  },
});

5. Server-Sent Events (SSE)

실시간 통신을 지원하는 SSE 기능:

server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse",
    port: 8080,
  },
});

6. 세션 관리

FastMCP는 각 클라이언트 연결에 새로운 서버 인스턴스를 할당하여 1:1 통신을 구현합니다.

server.on("connect", (event) => {
  console.log("Client connected:", event.session);
});

server.on("disconnect", (event) => {
  console.log("Client disconnected:", event.session);
});

개발 도구

테스트 및 디버깅

npx fastmcp dev src/examples/addition.ts


npx fastmcp inspect src/examples/addition.ts

Claude Desktop 통합

Claude Desktop에 다음 구성을 추가합니다.

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/PATH/TO/YOUR_PROJECT/src/index.ts"],
      "env": {
        "YOUR_ENV_VAR": "value"
      }
    }
  }
}

실제 적용 사례

FastMCP는 다음을 포함한 여러 프로젝트에서 채택되었습니다.

• apinetwork/piapi-mcp-server: Midjourney/Flux/Kling 등을 사용하여 미디어 콘텐츠 생성
• domdomegg/computer-use-mcp: 컴퓨터 제어 도구
• Meeting-Baas/meeting-mcp: 회의 로봇 및 전사 관리
• drumnation/unsplash-smart-mcp-server: Unsplash 이미지 검색 통합
• aiamblichus/mcp-chat-adapter: LLM 채팅 완료 인터페이스

기술적 장점

1. 타입 안전: 완벽한 TypeScript 지원으로 코드 품질 보장
2. 유연한 스키마: 다양한 검증 라이브러리 지원으로 다양한 요구 충족
3. 현대적인 아키텍처: 최신 웹 표준 및 모범 사례 기반
4. 풍부한 기능: 기본 기능부터 고급 기능까지 포괄적인 지원
5. 쉬운 확장: 모듈식 설계로 기능 확장 용이
6. 개발 친화적: 완벽한 CLI 도구 및 디버깅 지원

요약

FastMCP는 강력하고 사용하기 쉬운 TypeScript 프레임워크로, MCP 서버 구축을 위한 완벽한 솔루션을 제공합니다. 간단한 도구 통합이든 복잡한 AI 서비스 구축이든 FastMCP는 필요한 기능과 유연성을 제공할 수 있습니다. 풍부한 기능 세트와 훌륭한 개발자 경험은 MCP 생태계에서 중요한 도구로 만듭니다.