关键词

AI助手工具外部服务集成LLM上下文认证API天气查询图片处理日历管理健康营养

项目简介

Descope AI 仓库是一个多语言、多框架的 Model Context Protocol (MCP) 服务器实现示例集合。它展示了如何构建和部署 MCP 服务器，以标准化的方式向大型语言模型 (LLM) 客户端提供上下文信息和外部功能。该仓库的示例涵盖 Node.js (Express, Hono), Python (FastAPI) 和 Java (Spring/Jetty) 等技术栈，并重点演示了与 Descope 认证服务的无缝集成。

主要功能点

  • 工具注册与执行: 示例 MCP 服务器注册了多种工具，例如天气查询（获取预警、预报）、图片处理（OCR、条形码扫描）、Google 日历管理（获取日程、创建事件）和健康营养查询（食物营养、运动消耗）等。LLM 客户端可以根据需要调用这些工具来扩展其能力。
  • 上下文管理: 服务器能够托管和管理与 LLM 交互所需的动态上下文信息，确保 LLM 获得准确且相关的背景数据。
  • 安全认证集成: 所有示例均集成了 Descope 认证服务，通过 OAuth 2.0 协议确保只有经过授权的 MCP 客户端和用户才能访问服务器提供的工具和资源，增强了安全性。
  • 多传输协议支持: 示例展示了通过 Server-Sent Events (SSE) 和 Streamable HTTP 等多种传输协议进行 MCP 消息通信，以适应不同的部署环境和客户端需求。
  • 跨平台与多技术栈: 提供 Node.js、Python 和 Java 等主流开发语言的实现，并结合了 Express、Hono、FastAPI、Spring/Jetty 等流行框架，方便开发者选择和集成。

安装步骤

由于该仓库包含多个示例，具体安装步骤取决于您选择运行的示例。以下以 Node.js Express 天气 MCP 服务器 ('examples/remote-mcp-server-express-fly') 为例：

  1. 克隆仓库: 
    git clone https://github.com/descope/ai.git
  2. 进入示例目录: 
    cd ai/examples/remote-mcp-server-express-fly
  3. 安装依赖: 请确保您已安装 'pnpm' 包管理器。如果未安装，请先运行 'npm install -g pnpm'。 
    pnpm i
  4. 配置环境变量: 在当前目录 ('examples/remote-mcp-server-express-fly') 下创建一个名为 '.env' 的文件，并填入以下内容。请将 '<YOUR_DESCOPE_PROJECT_ID>' 和 '<YOUR_DESCOPE_MANAGEMENT_KEY>' 替换为您的实际 Descope 项目ID和管理密钥。'SERVER_URL' 应设置为您的服务器可访问的公共地址（例如 'http://localhost:3000'）。 
    DESCOPE_PROJECT_ID=<YOUR_DESCOPE_PROJECT_ID>
DESCOPE_MANAGEMENT_KEY=<YOUR_DESCOPE_MANAGEMENT_KEY>
SERVER_URL=http://localhost:3000
PORT=3000
  5. 启动服务器: 
    pnpm start
    服务器启动后，您将在控制台看到类似 "MCP Streamable HTTP Server listening on port 3000" 的输出。

其他示例说明:

  • Hono/Cloudflare Workers ('examples/remote-mcp-server-hono-cloudflare', 'examples/weather-mcp-server', 'examples/brave-search-mcp-server'): 这些示例适用于 Cloudflare Workers 环境。请参考对应目录下的 'README.md' 文件了解部署细节和环境变量配置（通常通过 Wrangler CLI 或 Cloudflare 控制台进行）。
  • Python FastAPI ('examples/fastapi-mcp-server'): 适用于 Python 环境。请参考 'examples/fastapi-mcp-server' 目录下的说明进行环境搭建和运行。
  • Java Spring/Jetty ('examples/java-spring-mcp'): 适用于 Java 环境。请参考 'examples/java-spring-mcp' 目录下的说明进行构建和运行。

服务器配置 (供 MCP 客户端参考的 JSON 格式)

以下是一个 MCP 客户端连接 Node.js Express 天气 MCP 服务器的配置示例。MCP 客户端通常通过 JSON 配置来连接并与 MCP 服务器交互。

{
  "serverName": "weather",
  "command": "node",
  "args": ["dist/index.js"],
  "workingDirectory": "./examples/remote-mcp-server-express-fly",
  "env": {
    "PORT": "3000",
    "DESCOPE_PROJECT_ID": "<YOUR_DESCOPE_PROJECT_ID>",
    "DESCOPE_MANAGEMENT_KEY": "<YOUR_DESCOPE_MANAGEMENT_KEY>",
    "SERVER_URL": "http://localhost:3000"
  },
  "transport": {
    "type": "http",
    "endpoint": "/mcp"
  },
  "auth": {
    "clientId": "<YOUR_MCP_CLIENT_ID>",
    "clientSecret": "<YOUR_MCP_CLIENT_SECRET>",
    "tokenUrl": "http://localhost:3000/.well-known/oauth-authorization-server"
  }
}
  • 'serverName': MCP 服务器的唯一标识名称，例如 "weather"。
  • 'command': 启动 MCP 服务器进程的命令，例如 Node.js 环境中的 "node"。
  • 'args': 传递给 'command' 命令的参数列表，例如 '["dist/index.js"]'，指向编译后的服务器入口文件。
  • 'workingDirectory': MCP 服务器代码的根目录，此路径应相对于 MCP 客户端的启动目录。
  • 'env': MCP 服务器运行时所需的环境变量。
    • 'PORT': 服务器监听的端口号。
    • 'DESCOPE_PROJECT_ID': 您的 Descope 项目ID，用于服务器进行 OAuth 认证。
    • 'DESCOPE_MANAGEMENT_KEY': 您的 Descope 管理密钥，用于服务器进行管理操作（如动态客户端注册）。
    • 'SERVER_URL': MCP 服务器的公共可访问 URL，用于 OAuth 重定向和元数据发现。
  • 'transport': 定义客户端与服务器之间通信的协议和端点。
    • 'type': 传输协议类型，例如 "http" 表示基于 HTTP POST 的 JSON-RPC 通信 (如 Express 示例)，或者 "sse" (Server-Sent Events) (如 Hono 示例)。
    • 'endpoint': MCP 消息的通信路径，例如 "/mcp" 或 "/sse"。
  • 'auth': 客户端认证信息。
    • 'clientId': LLM 客户端在 Descope 中注册的客户端 ID。
    • 'clientSecret': LLM 客户端的密钥。
    • 'tokenUrl': OAuth 认证服务器的令牌端点 URL，用于获取访问令牌。

基本使用方法

一旦 MCP 服务器根据上述步骤成功启动，您的 LLM 客户端可以通过配置的传输协议和端点与其建立连接。

  1. 服务发现: LLM 客户端会首先通过 '/.well-known/oauth-authorization-server' 和 '/.well-known/oauth-protected-resource' 等标准端点发现 MCP 服务器的元数据和能力，包括其支持的工具列表及其输入输出规范。
  2. 认证: 客户端将使用 'clientId' 和 'clientSecret' 通过 OAuth 2.0 流程向配置的 'tokenUrl' 发起请求，获取有效的 Bearer Token。
  3. 工具调用: 客户端在调用任何工具时，会将获得的 Bearer Token 包含在 'Authorization' 请求头中。LLM 客户端可以通过 JSON-RPC 格式向 MCP 服务器发送请求，调用服务器上注册的工具（例如 'get-alerts'、'get-forecast' 等），并提供必要的参数。
  4. 接收响应: MCP 服务器执行工具逻辑后，将以 JSON-RPC 响应的形式返回结果给 LLM 客户端。

例如，LLM 可以调用 'get-alerts' 工具并提供 'state' 参数来查询特定州的天气预警，或者调用 'scan-barcode' 工具并提供 'barcode_url' 来扫描图片中的条形码。

信息

分类

AI与计算

访问项目