使用说明（Markdown 格式）

项目简介

Enterprise MCP Bridge 是一个企业级后端入口，提供对 MCP 服务的 REST/HTTP 封装。通过标准化的接口，LLM 客户端（如大语言模型代理）可以获取资源、调用工具、获取并渲染提示模板，以及管理会话和安全上下文。桥接层还支持多租户隔离、OAuth2 令牌流转、远端令牌交换、状态持久化、SSE 实时进度推送等企业特性，便于与现有的鉴权、审计和运维体系对接。

主要功能点

• 资源管理与数据访问：提供 /resources、/resources/{resource} 等端点，便于 LLM 通过 MCP 模型获取需要的数据资源。
• 工具注册与调用：通过 /tools、/tools/{tool}、/tools/{tool}/stream 等端点，支持工具发现、参数注入、结果返回以及进度流式推送。
• 提示模板与系统提示：通过 /prompts 端点获取系统定义与 MCP 提示，支持系统提示与自定义提示的合并使用。
• 会话与多租户支持：/session/start、/session/close、会话上下文隔离，支持基于 OAuth 身份和组的资源访问控制。
• Token 交换与安全：内置 OAuth2 Token Exchange、TokenRetrieverFactory、自动令牌注入、令牌刷新等机制，兼容 Keycloak 等代理。
• 流式传输与观测性：提供 Server-Sent Events (SSE) 支持，适用于长时间工具执行的进度推送与结果反馈，以及结构化的日志输出。
• 支持多种部署与集成：REST-first 接口、自动生成 OpenAPI 文档、容器化部署、可替换的会话管理后端（InMemory/分布式实现）、可观测性（OpenTelemetry/Prometheus）。
• 生成式 UI 与代理：内置应用代理组件，可在 MCP 工具集上构建 AI 生成的 Web 应用并提供前端代理能力。

安装与运行

• 克隆与环境
  • 将仓库克隆到本地或服务器环境中，建立虚拟环境并安装依赖。
• 启动服务器
  • 使用常用的 FastAPI/Uvicorn 启动方式，例如：uvicorn app.server:app --reload
• 运行注意
  • 服务器暴露的 API 基于 FastAPI，具备自动化文档（OpenAPI/Redoc）。
  • 如需在企业环境中接入 OAuth，请配置 Keycloak 等身份提供者并通过环境变量注入 Token。
• MCP 服务器与客户端的对接
  • MCP 客户端需要配置服务器启动命令和参数，以便桥接器能够远程或本地启动并对接 MCP 服务。
  • 桥接器提供了端点暴露的接口，便于与 MCP 服务器进行读取资源、调用工具、获取提示等交互。

服务器配置（MCP 客户端视角的说明）

• MCP 服务器配置概述
  • MCP 服务器是给 MCP 客户端使用的后端实现。客户端需要提供的配置信息通常包含服务器标识、启动命令（command）以及参数（args），用于启动并与 MCP 服务器建立连接。
• 允许的配置要点（请以 JSON 格式理解，便于企业环境使用）
  • server_name: 企业内部对该 MCP 服务器的唯一标识名称，便于审计与监控。
  • command: 启动 MCP 服务器的命令（如运行 Uvicorn 的入口，需与实际部署方式匹配）。
  • args: 启动命令的参数数组，必要时可包含占位符（如 {data_path}、{user_id}、{group_id}），桥接器在请求时解析并注入实际值。
  • base_path: MCP API 路径前缀（如 /api/mcp），用以在网关或 ingress 层实现统一路由。
  • data_path 或数据卷绑定：若 MCP 服务器在本地需要持久化数据，提供数据目录路径。
  • 认证与授权相关字段（若在客户端层面描述，需在网关或代理层实现实际鉴权；桥接器本身在运行时会处理令牌的传递与注入）。 说明：以上字段用于理解和协同配置，实际配置需求以企业内网的运营规范及网关/容器编排为准。桥接器已实现的能力将对接这些服务器。
• 配置示例（非代码形式描述）
  • server_name: enterprise-mcp-backend
  • command: uvicorn
  • args: [ "app.server:app", "--reload" ]
  • MCP_BASE_PATH: /api/mcp
  • 说明：这是对 MCP 客户端理解的描述性信息，不是直接的代码块；实际客户端配置请以企业内部文档为准。

基本使用方法

• 启动与接入
  • 启动桥接器服务器，确保依赖就绪、认证提供者可达。
  • 在企业网关中暴露入口，统一鉴权、监控与访问控制策略。
• 使用流程
  • MCP 客户端通过桥接器暴露的端点进行工具发现与工具调用，获取系统提示并执行工具，查询资源等。
  • 客户端可通过 SSE 获取长时间任务的进度更新，通过 OpenAPI 文档了解可用端点、请求参数与返回结构。
• 运行与运维要点
  • 配置项以环境变量与配置文件形式管理，确保 token、秘钥等敏感信息安全注入与轮转。
  • 多租户会话应结合 OAuth 授权域实现分区访问、日志与审计分离。
  • 使用审计日志与指标（Prometheus/OpenTelemetry）监控请求量、错误率、延迟等。

注意：本实现的 MCP 交互是基于 REST/HTTP 的接口暴露，并辅以相应的会话、工具和资源管理逻辑，核心能力虽与 MCP 的“资源/工具/提示/会话”等组件对齐，但如严格要求 JSON-RPC 形式的 MCP 协议，需要在客户端与服务端之间进一步统一为 JSON-RPC 调用格式。本仓库当前提供的是面向企业场景的REST-first MCP 服务实现，具备 MCP 语义与端点能力，可直接用于企业级对接与扩展。