SERVYSALUD360 MCP 服务器

关键词

Model Context ProtocolJSON-RPC多租户Supabase健康管理

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个完整的 MCP 服务器端，围绕 Model Context Protocol（MCP）提供对资源、工具、以及提示模板等上下文信息的托管、注册与执行能力。核心通过 JSON-RPC 2.0 与 MCP 客户端通信，并在 Next.js 应用中以 API 路由形式暴露 /api/mcp 端点，支持多租户场景下的资源访问与工具执行。
    • 服务器实现了资源/工具的注册、执行、以及对外部服务（如 Supabase、Gemini、OCR/PDF 处理等）的封装，能够在多种传输场景下向 LLM 客户端提供安全、可扩展的上下文服务。

  • 主要功能点

    • MCP 核心能力
      • 通过 /api/mcp 接口以 JSON-RPC 2.0 格式接收请求并返回响应或错误。
      • 支持列出工具、执行工具、列出/读取资源等能力的请求处理。
    • 资源与工具管理
      • 资源、工具、以及与之相关的权限和多租户策略（基于 Supabase Auth / RLS）。
      • 支持对工作流中常用工具的分组管理（如 tööt_workers、casos、examenes、storage、empresas、analytics 等）。
    • 与外部服务的整合
      • 集成 Supabase（数据库、认证、存储）。
      • 集成 Google Gemini，支持分析 EMO、生成报告、以及分析/预测相关任务。
      • PDF/图片处理、OCR 作为降级路径的实现。
    • 传输与部署
      • 以 API 路由形式暴露 MCP 服务，适用于 Next.js 部署；同时具备用于 STDIO 的 MCP 服务器入口，可在需要时运行独立的 MCP 服务进程。
      • 具备日志、缓存和错误处理的集中化实现，方便排错与性能优化。
    • 安全与权限
      • 结合 Redux 风格的权限模型、角色检测（Admin、Médico Ocupacional、RRHH、Supervisor 等）以及多企业隔离。
      • 提供统一的错误封装（MCPErrorResponse）以及工具执行的安全包装。

  • 安装与运行步骤

    1. 克隆并安装依赖
      • 通过仓库提供的包结构，可直接在根目录执行安装命令，安装所需依赖并准备好编译环境。
    2. 启动服务
      • 运行为 Next.js 应用的一部分，运行应用后将自动暴露 MCP API 路径：/api/mcp。
      • 访问示例：http://localhost:3000/api/mcp
    3. 测试与调试
      • 通过对 /api/mcp 的 JSON-RPC 请求进行调试，验证工具列表、工具执行、以及资源、日志等能力是否按预期工作。
      • 如需单独测试 MCP 服务器的 STDIO 模式，可参考 mcp-server/src/index.ts 提供的 main() 启动入口。

  • 服务器配置（客户端连接配置示例，JSON 格式） 说明：该 MCP 服务器在该仓库内以嵌入式方式运行，作为 Next.js 应用的一部分对外暴露 /api/mcp 的 JSON-RPC 2.0 接口。客户端在连接时无需单独启动 MCP 服务器进程。下面是适用于客户端连接的配置描述（非代码形式，便于理解）： { "serverName": "servysalud360-mcp-server", "command": "embedded", "args": [], "endpoint": "http://localhost:3000/api/mcp", "notes": "MCP 客户端应通过 HTTP JSON-RPC 调用此端点，服务器在同一应用中运行，无需单独启动进程。" }

  • 基本使用方法

    • 连接方式
      • MCP 客户端向 /api/mcp 发送 JSON-RPC 2.0 请求，传入 method、params、id 等字段，服务器返回 JSON-RPC 格式的响应。
    • 常见请求类型
      • 列出可用工具（如 trabajadores、casos、examenes、storage、analytics、empresas 等）；
      • 调用具体工具（如 trabajadores_listar、casos_buscar 等）并传入相应参数；
      • 读取/管理资源或执行分析任务（如 EMO 分析、报告生成等）。
    • 安全与鉴权
      • 客户端在请求时可携带访问令牌，服务器会基于令牌进行鉴权并结合多租户策略进行资源隔离。

  • 注意事项

    • MCP 服务在该仓库中以嵌入式方式结合 Next.js 应用运行，默认端点为 /api/mcp，客户端无需额外启动服务器。
    • 如将 MCP 服务做成独立进程运行，请确保提供与之配套的启动命令和参数（见上方配置示例）。
    • 配置环境变量（如 Supabase URL/Key、Gemini Key 等）需在运行时正确提供。

  • 参考实现要点

    • 核心尝试遵循 MCP 的请求/响应格式，具备错误封装、工具注册、工具执行、资源读取等能力。
    • 同步/异步执行、缓存、日志和安全性等方面提供了较为完整的实现。
    • 代码结构清晰、模块化程度较高，便于扩展新工具和新资源。

服务器信息

访问项目