mcp-trellis

Не зависящие от хоста MCP + OAuth порты — вы выбираете рантайм и IdP, а библиотека отвечает за протокол коннектора.

Веб‑стандартные Request → Response. Один и тот же обработчик работает на Cloudflare Workers, в Next.js App Router, Deno, Bun и Node HTTP через mcp-trellis/node. Ноль зависимостей рантайма.

Почему mcp-trellis

Весь стек коннектора в одном пакете — обработчик MCP и авторизационный сервер OAuth 2.1 — без базы данных и без регистрации у вендора. Вы владеете логином, выпуском токенов и хранилищем; библиотека владеет протоколом.

Предпочитайте официальный SDK, если у вас уже есть отдельный AS. Предпочитайте workers-oauth-provider, если вам нужна реализация Cloudflare только для Workers. Предпочитайте управляемый IdP, если вы скорее заплатите, чем будете обслуживать его сами.

Именованные альтернативы в том же пространстве задач:

• @mcpauth/auth / getmcpauth / mcp-auth — OAuth для MCP, обычно с БД или иными допущениями о рантайме/стеке. mcp-trellis — вариант с нулевой зависимостью, который поставляет обработчик MCP и сервер авторизации OAuth 2.1 в одном пакете.

• fastmcp-oauth — хелперы OAuth для FastMCP. mcp-trellis не зависит от хоста (Request/Response) и не привязан к конкретному MCP-фреймворку.

Related MCP server: Remote MCP Server on Cloudflare

Требования

• Node ≥ 20 для Node-хостов (глобальный WebCrypto в ESM)

• Или любой рантайм с WebCrypto + fetch (Workers, Deno, Bun)

Установка

npm install mcp-trellis

Быстрый старт

Один вызов монтирует эндпоинт MCP, авторизационный сервер OAuth и оба discovery-документа:

import { createMcpApp } from "mcp-trellis";

const app = createMcpApp({
  serverInfo: { name: "demo", version: "1.0.0" },
  clients: ["claude"],
  tools: [
    {
      name: "echo",
      description: "Echo text back",
      inputSchema: {
        type: "object",
        properties: { text: { type: "string" } },
        required: ["text"],
      },
      scope: "mcp",
      handler: (_ctx, args) => String(args.text ?? ""),
    },
  ],
  auth: {
    codeSecret: process.env.OAUTH_CODE_SECRET!,
    resolveUser: async (req) => getSession(req),
    loginUrl: (_req, next) => `/login?next=${encodeURIComponent(next)}`,
    mintAccessToken: async ({ userId, scope, resource }) => ({
      // Embed `resource` as the token audience (RFC 8707).
      accessToken: await issueUserToken(userId, { aud: resource, scope }),
      expiresIn: 3600,
    }),
    verifyToken: async (token) => {
      const claims = await readUserToken(token);
      if (!claims) return null;
      return {
        userId: claims.sub,
        scopes: claims.scope.split(" "),
        audience: claims.aud,
      };
    },
  },
});

export default { fetch: (req: Request) => app.fetch(req) };

Вы возвращаете audience токена; библиотека отклоняет токены, выпущенные для другого ресурса, ещё до запуска любого инструмента. Подробнее: docs/security.md.

Реальный путь /authorize включает шаг подтверждения: подтвержденная сессия не перенаправляет сразу с кодом — сначала отображается экран согласия (встроенный или собственный через consent). Интеграторы, проходящие сценарий вручную, должны ожидать HTML-страницу, а не немедленный редирект — см. Consent.

Салмон с curl через initialize:

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"demo","version":"1.0.0"},"instructions":""}}

Клименты

Предзарегистрированные клиенты, принудительный DCR и подключение clientStore: docs/guide.md#clients.

Архитектура

createMcpApp связывает MCP и OAuth и маршрутизирует между ними:

Рецепты хостов, порты, инструменты и мультитенантность: docs/guide.md.

Документация

Примеры: examples/ — HTTP-сервис, Worker, мультитенант, хранилища, аудит.

Участие

PR приветствуются — см. CONTRIBUTING.md.

npm test
npm run build
npm run typecheck

Лицензия

MIT