UseAI MCP服务器实现

关键词

AI上下文服务JSON-RPC远程工具工具定义与执行插件扩展

  • 使用场景概述

    • 该仓库实现了一个后端服务器，作为 MCP（Model Context Protocol）风格的后端服务，向客户端（通常是集成了大语言模型的前端/应用）提供上下文相关的资源、工具以及可渲染的提示模板，方便 LLM 调用前端能力或接入外部工具。服务器与前端 UI 使用 AG-UI 协议扩展进行通信，并通过 JSON-RPC 风格的请求响应进行工具查询与执行。

  • 主要功能点

    • MCP 端点支持与管理：通过远程 MCP 端点清单加载外部工具，支持工具缓存、TTL、按头信息（headers）区分权限及认证。
    • 工具定义与执行：前端工具与远程 MCP 工具可混合注册，工具定义包含输入参数的 JSON Schema，且支持工具注释（MCP 风格注释）。
    • Prompt 模板渲染与系统提示：服务端可定义系统提示、运行时提示，以及对话上下文的组合，渲染给 LLM 使用。
    • JSON-RPC 与 AG-UI 事件流：遵循 AG-UI 的事件流（RUN_STARTED、TEXT_MESSAGE_START/CONTENT/END、TOOL_CALL_START/ARGS/END、RUN_FINISHED 等），并扩展了工具审批流、工具结果、以及工作流触发等能力。
    • 会话与状态管理：对每个客户端会话维护线程、会话状态、工具集合、以及 MCP 头部（headers）传递，支持多会话隔离和并发工具调用。
    • 外部扩展与插件：提供插件机制，内置了如 FeedbackPlugin、WorkflowsPlugin 等扩展点，便于接入 Langfuse、流程引擎等外部系统。
    • 运行时适配与跨环境支持：实现 Bun 与 Node 两种运行时的适配器，具备两种运行时下的 WebSocket/轮询传输能力。
    • MCP 工具与客户端协作：RemoteMcpToolsProvider 负责从外部 MCP 端点获取工具定义，并能将其转换成服务端可使用的工具定义，支持命名空间前缀等特性。
    • 安全与容错：包含速率限制、错误码映射、工具审批（destructiveHint 标注的工具需确认后执行）、以及对 MCP 调用的超时、错误处理机制。

  • 安装与运行步骤

    • 环境准备：本仓库提供了对 Bun 与 Node 两种运行时的支持，请根据实际运行时选择相应配置。
    • 构建与安装与运行要点：请在项目根目录执行标准依赖安装（如 bun install 或 npm install），随后启动服务。仓库给出多种运行与集成测试用例，实际部署时可参考官方 Docker 镜像或将服务作为独立应用部署。
    • 服务器配置要点（MCP 客户端需要的格式）
      • serverName: 用于标识 MCP 端的名称。
      • command: 启动服务器的命令（例如 bun 或 node）。
      • args: 启动命令的参数数组（例如启动脚本、端口等信息）。
      • 说明：MCP 客户端需要该配置来建立连接信息并执行对应任务，与前端的 AG-UI 客户端通信无关，配置仅用于描述如何启动 MCP 服务器。端口默认为 8081，实际应用中请按环境调整。
    • 配置示例（仅以文本描述，非代码块）：
      • serverName: use-ai-mcp-server
      • command: bun
      • args: ["start", "--port", "8081"]
      • 说明：以上为示意性配置，实际部署可能会依据运行时、打包方式及部署脚本调整。

  • 基本使用方法

    • 连接与使用
      • MCP 客户端通过指定的启动命令启动 MCP 服务器，并在配置中提供服务器的地址与端口。客户端与 MCP 服务器通过定义的工具集合进行协作，LLM 可以调用前端工具、访问资源、执行远程 MCP 工具，并接收服务器渲染的 Prompt 与上下文信息。
    • 工具与权限
      • 客户端工具可以是前端函数（本地工具）或远程 MCP 提供的工具。工具定义包含输入参数的 JSON Schema，服务器会在执行前对输入进行必填项与类型校验。
      • 支持工具的 destructiveHint 注释，需要用户在 UI 层进行明确授权后再执行。
    • 会话与安全
      • 服务器端提供会话管理、IP 基于传输的速率限制、以及对 MCP 端点的认证头部支持，允许按端点配置不同的请求头，确保对外部服务的访问权限控制。
    • 集成与扩展
      • 通过插件机制可扩展功能，集成 Langfuse、工作流 runner 等外部系统。
    • 运行与维护
      • 支持多传输协议与运行时适配，确保在不同运行环境下的稳定性（如 Bun/Node、WS/轮询等）。

  • 重要注意事项

    • MCP 端点的安全性与认证策略需在生产环境中严格配置，确保工具的权限控制不会被滥用。
    • 在使用远端 MCP 端点时，请正确设置工具缓存 TTL、请求头策略以及超时设置，以保障性能与稳定性。
    • 客户端在启动与连接时应提供正确的服务器地址与参数，确保成功建立工具执行与响应的链路。

  • 主要参考信息

    • MCP 端点与工具缓存、命名空间前缀等功能均在服务端实现，具体行为以代码逻辑为准，包含工具合并、权限检查、以及缓存策略等。

服务器信息

访问项目