UIMap MCP 服务器实现

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个基于 MCP 的服务端组件，核心功能是提供一个服务端口，允许 LLM 客户端通过 JSON-RPC 请求来读取资源、执行工具以及获取/渲染提示模板。服务器端通过 Stdio 传输与客户端通信，并在后端通过现有的 UIMap API 客户端实现对外部数据的访问与操作。

• 主要功能点

  • MCP 服务器核心：使用 MCP / JSON-RPC 机制建立与客户端的通信，作为后端上下文服务提供者。
  • 工具注册与执行：能够注册工具（如示例中的 search_uimap），并提供错误处理包装，确保在工具执行中产生的异常能被以合理的 MCP 响应返回给客户端。
  • 与后端 API 的集成：通过 API 客户端向 UIMap 的后端接口读取数据、执行查询并将结果封装为 MCP 响应。
  • 本地化传输支持：当前实现使用 StdioServerTransport，适合本地开发和调试环境的快速集成。
  • 会话与凭证管理：通过 CLI 提供的凭证管理、登录流程以及对凭证有效性的验证，确保对后端 API 的访问在认证层面的正确性。

• 安装步骤

  • 需要环境
    • Node.js 版本（建议使用与项目依赖兼容的版本）。
  • 全局安装/使用方式
    • 使用 npx 直接启动 MCP 服务：npx @refore-ai/uimap mcp
  • 本地开发运行
    • 在仓库根目录执行相关命令，确保依赖正确安装后，可以通过 CLI 的 mcp 子命令启动服务，/ 程序会在标准输入输出（Stdio）通道上等待 JSON-RPC 请求。

• 服务器配置（给 MCP 客户端使用的启动配置） 注：以下配置示例为 JSON 形式描述，用于 MCP 客户端在启动阶段连接到服务端。MCP 客户端需要的只是服务器的启动命令及参数信息，以便通过约定的传输通道建立会话。

  • 服务器名：uimap
  • 启动命令：npx
  • 参数：-y @refore-ai/uimap mcp
  • 环境变量（可选，若你的后端 API 需要认证信息）：UIMAP_API_KEY、UIMAP_APP_ID 示例（纯文本JSON描述）： { "mcpServers": { "uimap": { "command": "npx", "args": ["-y", "@refore-ai/uimap", "mcp"], "env": { "UIMAP_API_KEY": "<your_api_key>", "UIMAP_APP_ID": "<your_app_id>" } } } } 注释说明：
  • mcpServers.uimap.command 与 mcpServers.uimap.args 对应仓库中通过命令行启动 MCP 服务的方式。
  • env 中的变量用于在需要认证的场景下提供凭证信息，具体是否需要以及取值请根据实际后端 API 的授权要求配置。
  • 客户端无需额外的代码仅通过上述启动信息即可与服务器建立通信。

• 基本使用方法

  • 启动 MCP 服务：在支持 MCP 的客户端环境中，使用上面的命令启动服务端（如 npx @refore-ai/uimap mcp）。
  • 客户端连接：MCP 客户端通过配置的 serverName、command、args 连接到服务器后，即可发起对资源、工具等的请求。
  • 常用交互示例（概念性描述）
    • 客户端发送一个请求来执行注册的工具（如 search_uimap），服务器接收并处理请求，执行相应逻辑后返回结果给客户端。
    • 客户端可以通过工具返回的文本内容将信息传递给用户或嵌入到后续对话流程中。
  • 监控与排错
    • 如遇连接异常或工具执行错误，请检查服务器启动日志、传输通道状态，以及凭证是否正确配置与有效。