FastMCP

MCP sunucuları oluşturmak için MCP istemci oturumlarını işleyebilen bir TypeScript çerçevesi.

[!NOTE]

Python uygulaması için bkz. FastMCP.

Özellikler

Basit Tool, Resource, Prompt tanımı
Kimlik Doğrulama
Header'ları context üzerinden iletme
Oturum ID'si ve Request ID'si izleme
Oturumlar
Görüntü içeriği
Ses içeriği
Gömülü Kaynaklar
Günlükleme
Hata işleme
HTTP Akışı (SSE uyumluluğu ile)
HTTPS Desteği güvenli bağlantılar için
Özel HTTP rotaları REST API'ları, webhook'ları ve yönetici arayüzleri için
Edge Runtime Desteği Cloudflare Workers, Deno Deploy vb. için
Stateless modu sunucusuz dağıtımlar için
CORS (varsayılan olarak etkin)
İlerleme bildirimleri
Akış çıkışı
Yazılı sunucu olayları
Prompt argümanı otomatik tamamlama
Örnekleme
Yapılandırılabilir ping davranışı
Sağlık kontrol uç noktası
Kökler
Test ve hata ayıklama için CLI

FastMCP'yi resmi SDK yerine ne zaman kullanmalısınız?

FastMCP resmi SDK'nın üzerine inşa edilmiştir.

Resmi SDK, MCP'ler oluşturmak için temel bloklar sağlar ancak birçok uygulama detayını size bırakır:

Tüm sunucu bileşenlerini başlatma ve yapılandırma
Bağlantıları işleme
Tool'ları işleme
Yanıtları işleme
Kaynakları işleme
Prompt'ları, kaynakları, kaynak şablonlarını ekleme
Kaynakları, görüntü ve ses içerik bloklarını gömme

FastMCP bu karmaşıklığı, sunulan bir çerçeve sağlayarak ortadan kaldırır:

Tüm boilerplate'i otomatik olarak işler
Yaygın görevler için basit, sezgisel API'lar sağlar
Yerleşik en iyi uygulamalar ve hata işleme içerir
MCP'nizin temel işlevselliğine odaklanmanızı sağlar

FastMCP'yi seçin: MCP sunucularını düşük seviye uygulama detaylarıyla uğraşmadan hızlıca oluşturmak istiyorsunuz.

Resmi SDK'yı kullanın: Maksimum kontrol gerektirir veya belirli mimari gereksinimleri vardır. Bu durumda, yaygın tuzakları önlemek için FastMCP'nin uygulamasına referans olarak bakmanızı teşvik ederiz.

Kurulum

npm install fastmcp

Hızlı Başlangıç

[!NOTE]

FastMCP'nin gerçek dünya örnekleri birçok yerde bulunmaktadır. Örnekler için Vitrin bölümüne bakın.

import { FastMCP } from "fastmcp";
import { z } from "zod"; // Veya Standard Schema'yı destekleyen herhangi bir doğrulama kütüphanesi

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",
});

Bu kadar! Çalışan bir MCP sunucunuz var.

Sunucuyu terminal'de test edebilirsiniz:

git clone https://github.com/punkpeye/fastmcp.git
cd fastmcp

pnpm install
pnpm build

# CLI kullanarak toplama sunucusu örneğini test edin:
npx fastmcp dev src/examples/addition.ts
# MCP Inspector kullanarak toplama sunucusu örneğini test edin:
npx fastmcp inspect src/examples/addition.ts

Kendi MCP sunucunuzu oluşturmak için bir boilerplate deposu arıyorsanız, fastmcp-boilerplate kontrol edin.

Uzak Sunucu Seçenekleri

FastMCP, uzak iletişim için birden çok transport seçeneğini destekleyerek, uzak bir makinede barındırılan bir MCP'nin ağ üzerinden erişilmesini sağlar.

HTTP Akışı

HTTP akışı bunu destekleyen ortamlarda SSE'ye daha verimli bir alternatif sağlar ve daha büyük payloads için potansiyel olarak daha iyi performans sunar.

HTTP akışı desteği ile sunucuyu çalıştırabilirsiniz:

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8080,
  },
});

Bu, sunucuyu başlatacak ve http://localhost:8080/mcp adresindeki HTTP akışı bağlantılarını dinleyecektir.

Not: httpStream.endpoint seçeneğini kullanarak endpoint yolunu özelleştirebilirsiniz (varsayılan /mcp'dir).

Not: Bu aynı zamanda http://localhost:8080/sse adresinde bir SSE sunucusu başlatır.

Bu sunuculara uygun client transport kullanarak bağlanabilirsiniz.

HTTP akışı bağlantıları için:

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new StreamableHTTPClientTransport(
  new URL(`http://localhost:8080/mcp`),
);

await client.connect(transport);

SSE bağlantıları için:

import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));

await client.connect(transport);

HTTPS Desteği

FastMCP, SSL sertifika seçenekleri sağlayarak HTTPS'yi güvenli bağlantılar için destekler:

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8443,
    sslCert: "./path/to/cert.pem",
    sslKey: "./path/to/key.pem",
    sslCa: "./path/to/ca.pem", // İsteğe bağlı: istemci sertifikası kimlik doğrulaması için
  },
});

Bu, https://localhost:8443/mcp adresinde sunucuyu HTTPS ile başlatacaktır.

SSL Seçenekleri:

sslCert - SSL sertifikası dosyasının yolu
sslKey - SSL özel anahtar dosyasının yolu
sslCa - (İsteğe bağlı) Karşılıklı TLS kimlik doğrulaması için CA sertifikasının yolu

Test için, kendi imzalı sertifikalar oluşturabilirsiniz:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

Üretim için, Let's Encrypt gibi güvenilir bir CA'dan sertifikalar alın.

Tam bir örnek için https-server örneğine bakın.

Özel HTTP Rotaları

FastMCP, MCP uç noktalarının yanında özel HTTP rotaları eklemenize izin vererek, aynı sunucu süreci içinde REST API'ları, webhook'ları, yönetici arayüzlerini ve daha fazlasını içeren kapsamlı HTTP hizmetleri oluşturmanızı sağlar.

// REST API uç noktaları ekleme
server.addRoute("GET", "/api/users", async (req, res) => {
  res.json({ users: [] });
});

// Yol parametrelerini işleme
server.addRoute("GET", "/api/users/:id", async (req, res) => {
  res.json({
    userId: req.params.id,
    query: req.query, // Sorgu parametrelerine erişim
  });
});

// POST isteklerini gövde ayrıştırması ile işleme
server.addRoute("POST", "/api/users", async (req, res) => {
  const body = await req.json();
  res.status(201).json({ created: body });
});

// HTML içeriğini sunma
server.addRoute("GET", "/admin", async (req, res) => {
  res.send("<html><body><h1>Admin Panel</h1></body></html>");
});

// Webhook'ları işleme
server.addRoute("POST", "/webhook/github", async (req, res) => {
  const payload = await req.json();
  const event = req.headers["x-github-event"];

  // Webhook işleme...
  res.json({ received: true });
});

Özel rotalar şunları destekler:

Tüm HTTP yöntemleri: GET, POST, PUT, DELETE, PATCH, OPTIONS
Yol parametreleri (:param) ve wildcard'lar (*)
Sorgu dizesi ayrıştırması
JSON ve metin gövde ayrıştırması
Özel durum kodları ve başlıkları
MCP ile aynı authenticate işlevini kullanarak kimlik doğrulaması
Kimlik doğrulamayı atlayan genel rotalar

Rotalar kayıt sırasına göre eşleştirilir ve belirli rotaları catch-all desenlerinden önce tanımlamanıza izin verir.

Genel Rotalar

Varsayılan olarak, özel rotalar kimlik doğrulama gerektirir (yapılandırılmışsa). { public: true } seçeneğini ekleyerek rotaları genel hale getirebilirsiniz:

// Genel rota - kimlik doğrulama gerekli değil
server.addRoute(
  "GET",
  "/.well-known/openid-configuration",
  async (req, res) => {
    res.json({
      issuer: "https://example.com",
      authorization_endpoint: "https://example.com/auth",
      token_endpoint: "https://example.com/token",
    });
  },
  { public: true },
);

// Özel rota - kimlik doğrulama gerekli
server.addRoute("GET", "/api/users", async (req, res) => {
  // req.auth kimlik doğrulanmış kullanıcı verisi içerir
  res.json({ users: [] });
});

// Genel statik dosyalar
server.addRoute(
  "GET",
  "/public/*",
  async (req, res) => {
    // Statik dosyaları kimlik doğrulaması olmadan sunma
    res.send(`File: ${req.url}`);
  },
  { public: true },
);

Genel rotalar şunlar için mükemmeldir:

OAuth discovery uç noktaları (.well-known/*)
Sağlık kontrolleri ve durum sayfaları
Statik varlıklar ve belgeler
Dış hizmetlerden webhook uç noktaları
Kullanıcı kimlik doğrulaması gerektirmeyen genel API'lar

Tam bir örnek için custom-routes örneğine bakın.

Edge Runtime Desteği

FastMCP, Cloudflare Workers gibi edge runtime'ları destekleyerek MCP sunucularını dünya çapında minimum gecikme ile edge'e dağıtmayı sağlar.

FastMCP ve EdgeFastMCP Arasında Seçim

Kullanım Durumu	Sınıf	Import
Node.js, Express, Bun	`FastMCP`	`import { FastMCP } from "fastmcp"`
Cloudflare Workers, Deno Deploy	`EdgeFastMCP`	`import { EdgeFastMCP } from "fastmcp/edge"`

Özellik	FastMCP	EdgeFastMCP
Runtime	Node.js	Edge (V8 isolates)
Start yöntemi	`server.start({ port })`	`export default server`
Transport	stdio, httpStream, SSE	Yalnızca HTTP Streamable
Oturumlar	Stateful veya stateless	Yalnızca stateless
Dosya sistemi	Evet	Hayır
OAuth/Kimlik Doğrulama	Yerleşik `authenticate` seçeneği	Hono middleware'i kullanın (planlanmış)
Özel rotalar	`server.getApp()`	`server.getApp()`

Not: EdgeFastMCP için yerleşik kimlik doğrulama bir gelecek sürüm için planlanmıştır. Hem FastMCP hem de EdgeFastMCP dahili olarak Hono kullanır, bu nedenle teknik bir engel yoktur—EdgeFastMCP sadece OAuth FastMCP'ye eklenmeden önce yazılmıştır. Node.js http.IncomingMessage yerine web Request'i kabul eden bir authenticate seçeneği eklemek için PR'ler memnuniyetle karşılanır.

Şimdilik Hono middleware'ini kullanın:
const app = server.getApp();
app.use("/api/*", async (c, next) => {
  if (c.req.header("authorization") !== "Bearer secret") {
    return c.json({ error: "Unauthorized" }, 401);
  }
  await next();
});

Cloudflare Workers

FastMCP'yi Cloudflare Workers'a dağıtmak için /edge alt yolundan EdgeFastMCP sınıfını kullanın:

import { EdgeFastMCP } from "fastmcp/edge";
import { z } from "zod";

const server = new EdgeFastMCP({
  name: "My Edge Server",
  version: "1.0.0",
  description: "MCP server running on Cloudflare Workers",
});

// Araçları, kaynakları, prompt'ları her zamanki gibi ekleyin
server.addTool({
  name: "greet",
  description: "Greet someone",
  parameters: z.object({
    name: z.string(),
  }),
  execute: async ({ name }) => {
    return `Hello, ${name}! Served from the edge.`;
  },
});

// Sunucuyu varsayılan olarak dışa aktarın (Cloudflare Workers için gerekli)
export default server;

Edge Runtime Farkları

Edge runtime'larda çalışırken:

Varsayılan olarak Stateless: Her istek bağımsız olarak işlenir
Dosya sistemi erişimi yok: Dış veriler için fetch API'larını kullanın
V8 Isolates: Hızlı soğuk başlangıçlar ve verimli kaynak kullanımı
Küresel dağıtım: Edge lokasyonlarına otomatik dağıtım

Edge'de Özel Rotalar

Özel HTTP rotaları eklemek için temel Hono uygulamasına erişebilirsiniz:

const app = server.getApp();

// Açılış sayfası ekleme
app.get("/", (c) => c.html("<h1>Welcome to my MCP server</h1>"));

// REST API uç noktaları ekleme
app.get("/api/status", (c) => c.json({ status: "ok" }));

Dağıtım

wrangler.toml dosyasını yapılandırın:

name = "my-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-01-01"

Şu komutu kullanarak dağıtın:

wrangler deploy

Tam bir örnek için edge-cloudflare-worker örneğine bakın.

Stateless Modu

FastMCP, HTTP akışı için stateless işletimi destekleyerek her istek kalıcı oturumlar korulamadan bağımsız olarak işlenir. Bu, sunucusuz ortamlar, yük dengeli dağıtımlar veya oturum durumunun gerekli olmadığı durumlarda idealdir.

Stateless modunda:

Sunucuda oturum takip edilmez
Her istek, yanıttan sonra atılan geçici bir oturum oluşturur
Azaltılmış bellek kullanımı ve daha iyi ölçeklenebilirlik
Stateless dağıtım ortamları için mükemmel

stateless: true seçeneğini ekleyerek stateless modu etkinleştirebilirsiniz:

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8080,
    stateless: true,
  },
});

Not: Stateless modu yalnızca HTTP akışı transport'unda mevcuttur. Kalıcı oturumlara bağlı özellikler (oturuma özgü durum gibi) stateless modunda kullanılmayacaktır.

CLI argümanlarını veya ortam değişkenlerini kullanarak da stateless modu etkinleştirebilirsiniz:

# CLI argümanı üzerinden
npx fastmcp dev src/server.ts --transport http-stream --port 8080 --stateless true

# Ortam değişkeni üzerinden
FASTMCP_STATELESS=true npx fastmcp dev src/server.ts

/ready sağlık kontrolü uç noktası, sunucunun stateless modunda çalıştığını gösterir:

{
  "mode": "stateless",
  "ready": 1,
  "status": "ready",
  "total": 1
}

Temel Kavramlar

Araçlar

MCP'deki Araçlar, sunucuların istemciler tarafından çağrılabilen ve LLM'ler tarafından eylemleri gerçekleştirmek için kullanılabilen yürütülebilir işlevleri ortaya çıkarmalarını sağlar.

FastMCP, araç parametrelerini tanımlamak için Standard Schema belirtimini kullanır. Bu, Zod, ArkType veya Valibot gibi tercih ettiğiniz şema doğrulama kütüphanesini (belirtimi uygulayan) kullanmanıza izin verir.

Zod Örneği:

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);
  },
});

ArkType Örneği:

import { type } from "arktype";

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

Valibot Örneği:

Valibot, @valibot/to-json-schema peer dependency'sini gerektirir.

import * as v from "valibot";

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

Parametresiz Araçlar

Parametre gerektirmeyen araçlar oluştururken iki seçeneğiniz var:

Parameters özelliğini tamamen atlamak:

server.addTool({
  name: "sayHello",
  description: "Say hello",
  // Parameters özelliği yok
  execute: async () => {
    return "Hello, world!";
  },
});

Açıkça boş parametreleri tanımlamak:

import { z } from "zod";

server.addTool({
  name: "sayHello",
  description: "Say hello",
  parameters: z.object({}), // Boş nesne
  execute: async () => {
    return "Hello, world!";
  },
});

[!NOTE]

Her iki yaklaşım da Cursor dahil tüm MCP istemcileri ile tamamen uyumludur. FastMCP her iki durumda da uygun şemayı otomatik olarak oluşturur.

Araç Yetkilendirmesi

Bir aracın tanımına isteğe bağlı bir canAccess işlevini ekleyerek, kimlik doğrulanmış kullanıcılar için kullanılabilir araçları kontrol edebilirsiniz. Bu işlev, kimlik doğrulama bağlamını alır ve kullanıcı araca erişmesine izin verilirse true döndürmelidir.

server.addTool({
  name: "admin-tool",
  description: "An admin-only tool",
  canAccess: (auth) => auth?.role === "admin",
  execute: async () => "Welcome, admin!",
});

Dize döndürme

execute bir dize döndürebilir:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return "Hello, world!";
  },
});

Yukarıdaki aşağıdaki ile eşdeğerdir:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "text",
          text: "Hello, world!",
        },
      ],
    };
  },
});

Liste döndürme

Mesaj listesi döndürmek istiyorsanız, content özelliğine sahip bir nesne döndürebilirsiniz:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        { type: "text", text: "First message" },
        { type: "text", text: "Second message" },
      ],
    };
  },
});

Görüntü döndürme

Bir görüntünün içerik nesnesini oluşturmak için imageContent'i kullanın:

import { imageContent } from "fastmcp";

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return imageContent({
      url: "https://example.com/image.png",
    });

    // veya...
    // return imageContent({
    //   path: "/path/to/image.png",
    // });

    // veya...
    // return imageContent({
    //   buffer: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"),
    // });

    // veya...
    // return {
    //   content: [
    //     await imageContent(...)
    //   ],
    // };
  },
});

imageContent işlevi şu seçenekleri alır:

url: Görüntünün URL'si.
path: Görüntü dosyasının yolu.
buffer: Bir buffer olarak görüntü verisi.

Yalnızca url, path veya buffer birinin bel

punkpeye/fastmcp

Bu MCP sunucusu hakkında