AI导哈

MCP协议服务器

一个基于TypeScript和Streamable HTTP传输构建的MCP服务器，支持OAuth代理和第三方授权服务器如Auth0，用于实现MCP协议的完整功能。

  • by chrisleekr
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 chrisleekr/mcp-server-boilerplate

使用说明

MCP服务器游乐场

一个使用TypeScript和Streamable HTTP传输构建的模型上下文协议（MCP）服务器的游乐场，带有用于Auth0等第三方授权服务器的OAuth代理。

特性

  • 符合MCP 2025-06-18标准：完全符合最新的MCP规范，包括SSE可恢复性、工具注释和结构化内容。
  • MCP服务器实现：基于HTTP的流式传输使用 @modelcontextprotocol/sdk HTTP传输、会话管理和工具执行。
  • SSE可恢复性：客户端可以重新连接 Last-Event-ID header用于在连接中断后恢复接收事件，由EventStore提供支持。
  • OAuth身份验证/第三方授权：使用RFC 8707资源指示器和RFC 9728授权发现为MCP客户端实现OAuth服务器，委托给Auth0。
  • 存储：使用EventStore进行可插拔存储抽象（内存/Valkey），用于SSE事件持久化和重放。
  • 会话管理：通过使用分布式部署的初始请求的回放来支持有状态会话。
  • 安全：严格的源验证以防止DNS重新绑定攻击，WWW-Authenticate标头用于授权发现。
  • 工具：
    • aws-ecs：使用AWS ECS、cloudwatch日志和Bedrock调查ECS服务、任务和cloudwatch日志
    • aws-s3：获取S3存储桶和对象的列表
    • system-time：通过时区支持以各种格式获取当前系统时间
    • echo：通过转换、重复来回复消息
    • streaming：通过实时更新模拟实时流数据
    • project：在当前项目目录中查找关键字
  • 资源：
    • echo://documentation：回声工具的文档（静态资源）
    • echo://result/{resultId}：访问回显操作结果（资源模板）
  • 提示： echo

文档

为什么这个项目存在？

  • 模型上下文协议规范 需要动态应用程序注册 因为它为MCP客户端提供了一种标准化的方式，可以在没有用户交互的情况下自动向新服务器注册并获取OAuth客户端ID。这种机制的主要原因是MCP客户端无法提前知道所有可能的服务，手动注册会给用户带来巨大的工作量，而且不可扩展。如果不支持动态应用程序注册，那么MCP客户端需要向服务器提供OAuth客户端ID和密钥，这既不安全也不可扩展。
  • 但是，启用动态应用程序注册（如果支持）将成为 安全风险 因为端点是任何人都可以创建OAuth客户端的公共端点。它很容易被滥用，例如被不想要的客户端注册淹没。因此，Auth0已禁用动态应用程序注册
  • 因此，该项目提供了一种通过使用OAuth代理为MCP服务器启用动态应用程序注册的方法，但将授权委托给Auth0、Github、Google等第三方授权服务器。

端点

端点 描述
GET/ping ping服务器
POST/mcp mcp协议请求与身份验证
DELETE/mcp 会话终止
GET/.nearned/oauth授权服务器 oauth授权服务器元数据
GET/.wearned/oauth保护的资源 oauth保护的资源元数据
POST/oauth/register 注册新的MCP客户端
GET/oauth/authority 处理授权请求
POST/oauth/token 处理令牌请求
POST/oauth/revoke 处理令牌吊销
GET/oauth/stats 获取oauth服务统计信息
GET/oauth/auth0回调 处理auth0回调

入门指南

安装

  1. 克隆存储库：

    git clone <your-repo>
cd mcp-server-playground

  2. 安装Bun（如果尚未安装）：

    curl -fsSL https://bun.sh/install | bash

  3. 安装依赖项：

    bun install

  4. 设置环境变量：

    cp .env.example .env

  5. 设置MCP服务器以进行本地开发

    bun run dev:setup

Helm 图表

helm repo add chrisleekr https://chrisleekr.github.io/helm-charts/
helm repo update
helm install mcp-server-playground chrisleekr/mcp-server-playground

为Cursor设置MCP服务器

  1. 为本地构建创建MCP配置文件

    创建 .cursor/mcp.json 项目目录中的文件（用于项目特定的设置）或 ~/.cursor/mcp.json 在您的主目录中（用于全局设置）：

    {
  "mcpServers": {
    "mcp-server-playground-cursor": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

使用MCP检查器测试服务器

  1. 复制 mcp-config.example.json 到 mcp-config.json

  2. 编辑 mcp-config.json 指向正确的MCP服务器

  3. 运行检查器

    docker compose up -d

# Then run the inspector
bunx @modelcontextprotocol/inspector -y --config ./mcp-config.json --server mcp-server-playground-inspector

    或

    docker compose up -d

bun run test:inspector

设置Auth0以进行授权

  1. 在Auth0中创建新应用程序

    • 首选 Auth0仪表板
    • 点击“应用程序”
    • 点击“创建应用程序”
      • 名称：MCP服务器游乐场
      • 应用程序类型：常规Web应用程序
    • 点击“创建”

  2. 设置应用程序

    • 点击“设置”
    • 设置以下设置：
      • 允许的回调URL： http://localhost:3000/oauth/auth0-callback
      • 允许的网络来源： http://localhost:3000

  3. 创建新的API

    • 点击“API”
    • 点击“创建API”
      • 名称：MCP服务器游乐场
      • 标识符： urn:mcp-server-playground
      • JSON Web令牌（JWT）配置文件：Auth0
      • JSON Web令牌（JWT）签名算法：RS256
    • 点击“创建”

如何与多个MCP服务器实例进行有状态会话？

当MCP服务器部署为集群时，由于设计上没有在实例之间共享传输，因此无法使其具有多个MCP服务器实例的状态。

为了使其真正有状态，我使用Valkey将会话id与初始请求一起存储。

当请求进入备用MCP服务器实例时，它将检查会话id是否在Valkey中。如果是，它将重放初始请求并将传输连接到服务器。

灵感来自 https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/102

看 架构-有状态会话管理 查看详细的序列图。

待办事项

  • []流媒体无法按预期工作。它返回最终结果，而不是流式传输数据。

截图

元数据发现 客户端注册 准备授权
第三方服务器授权 请求授权并获取授权码 令牌请求和身份验证完成

参考文献

相关 MCP