使用说明（简明、面向开发与运维人员）

• 项目简介

  • 这是一个基于 Spring Boot 的 MCP 服务器实现，目标是让大语言模型客户端能够通过标准化的 MCP 协议访问 MonicaHQ 的 CRM 数据、执行外部工具，以及获取可自定义的 Prompt 模板，用于实现稳定、可扩展的上下文服务。支持两种运行模式：STDIO（适用于 Claude Desktop 等本地客户端）和 Web 服务器模式（HTTP/WebSocket，适用于生产环境或其他客户端）。

• 主要功能点

  • 资源管理：向 LLM 客户端提供对 MonicaHQ 资源的读取与查询能力（如联系人、公司、任务、笔记等实体及其字段）。
  • 工具注册与执行：注册多种工具/操作，LLM 可以通过 MCP 调用外部功能完成创建、查询、更新、删除等工作流。
  • Prompt 模板渲染：为 LLM 交互提供可定制的 Prompt 模板及渲染结果。
  • MCP 协议对接：通过 JSON-RPC 2.0 处理请求与响应，支持标准请求/响应结构、错误处理与通知。
  • 双模运行模式：STDIO 模式用于 Claude Desktop 集成，Web 服务模式提供 HTTP REST + WebSocket 接口，便于生产环境接入。
  • 安全与稳定性：OAuth2 Bearer 令牌用于 MonicaHQ API 访问，具备断路器等鲁棒性设计，具备测试覆盖（188/188 测试通过）及完整的部署文档。

• 安装步骤（开发与本地测试优先）

  1. 构建
     • 使用 Gradle 构建并打包为可运行的 JAR。
  2. 运行模式选择
     • STDIO 模式：用于 Claude Desktop 集成，命令示例为 Java -jar monicahqmcp-0.1.0.jar --stdio。
     • Web Server 模式：用于生产部署，命令示例为 Java -jar monicahqmcp-0.1.0.jar --web。
  3. 依赖与环境变量
     • MONICA_API_URL： MonicaHQ 的 API 地址（示例 https://your-monica-instance/api）
     • MONICA_API_TOKEN： OAuth2 Bearer Token，用于 MonicaHQ API 认证
  4. 部署选项
     • 直接运行 JAR
     • 使用 Docker 构建镜像并以容器运行（包含 STDIO 与 Web 两种模式）
     • 使用 Docker Compose 进行生产部署
  5. 客户端集成
     • MCP 客户端（如 Claude Desktop）通过配置 JSON 指定服务器信息、启动命令及参数来连接 MCP 服务器（详见“服务器配置”JSON 配置描述）。

• 服务器配置（面向 MCP 客户端的启动配置，JSON 格式说明） server_name: monicahq command: /usr/bin/java args: ["-jar", "/absolute/path/to/monicahqmcp-0.1.0.jar", "--stdio"] environment: MONICA_API_URL: "https://your-monica-instance/api" MONICA_API_TOKEN: "your-oauth2-bearer-token" 注释说明

  • server_name 为客户端看到的服务器标识名，便于在多 MCP 服务中区分。
  • command 与 args 描述 MCP 服务器的启动命令及参数，示例为直接执行 Java JAR 的标准启动方式。
  • environment 给出连接 MonicaHQ 的必要凭证信息，确保客户端在启动后能正确连接到 MonicaHQ API。
  • 客户端无需也不需要暴露内部实现细节，只需按照上述字段启动命令与环境变量即可建立连接。

• 基本使用方法

  • 启动与连接
    • 在开发环境使用 STDIO 模式启动 JAR，确保 MONICA_API_URL 与 MONICA_API_TOKEN 配置正确。
    • 在生产环境使用 Web 服务器模式，确保 HTTP/WebSocket 端口可访问，且环境变量配置正确。
  • 通过 MCP 客户端与 MCP 服务器进行交互
    • 调用工具：通过 tools/call 请求调用已注册的工具（如 contact_create、note_create、contact_list 等），获取结果或处理错误。
    • 读取资源：通过相应的 tools/list 或工具参数，读取联系人、任务、备注等资源数据。
    • Prompt 渲染：在需要时由客户端请求模板或执行模板渲染，获取可直接用于 LLM 的 Prompt 内容。
  • 监控与调试
    • 关注日志输出（STDIO 模式输出到标准错误/标准输出，Web 模式输出到日志）。
    • 如遇协议问题，开启 MCP_DEBUG 以获得详细协议日志。
  • 测试与验证
    • 项目内提供完善的测试覆盖，包含 contract 测试、集成测试与 Docker 测试用例，确保 MCP 协议、工具、资源的行为符合预期。

• 运行与维护要点

  • 适配 MonicaHQ API 版本：当前实现支持 Monica API 的 4.x/5.x 版本，需确保 Monica 实例能够正常访问并授权。
  • 证书与安全：生产环境建议走 HTTPS，并在容器或主机上妥善管理 MONICA_API_TOKEN。
  • 可扩展性：MCP 服务器设计允许扩展资源类型、工具集和 Prompts，便于未来接入更多 MonicaHQ 功能和外部工具。
  • 测试与治理：遵循 constitutional 验证与测试用例，确保 188/188 测试通过，保持对外 API 的高可用性与稳定性。

• 备注

  • 该仓库包含大量测试用例与开发文档，表明实现不仅是示例，而是完整的可运行 MCP 服务器及相关测试与开发工具链。