使用说明（Markdown格式）

• 项目简介

  • 该仓库实现了一个基于 Model Context Protocol (MCP) 的服务器端生态，核心目标是以标准化的 JSON-RPC 调用向大语言模型（LLM）客户端暴露资源读取、工具调用和提示模板渲染等能力，并通过桥接组件连接 Cursor 等工具链与 Docmost 的后端 API。
  • 主要组成包括：MCP 服务端实现、资源/工具的注册与暴露、JSON-RPC 请求处理，以及一个用于将 Cursor 与 Docmost API 对接的 MCP Bridge。

• 主要功能点

  • MCP 核心功能：解析 MCP 请求、构建响应、按照工具/资源进行能力暴露，并支持多种传输方式（如标准 IO/管道式入口等场景，桥接模块中已有实现）。
  • 资源与工具管理：将 Docmost 的各类资源（空间、页、用户、评论、附件、工作区、群组、UI 操作等）映射为 MCP 工具，允许 LLM 通过工具调用对后端数据进行操作。
  • 桥接实现（Bridge）：提供一个桥接层，将 Cursor / 客户端的 MCP 请求转发到 Docmost 的 API，支持 API Key 身份认证，完成实际的资源操作与结果返回。
  • API 端点与工具清单：提供 MCP 标准接口、自定义工具清单、OpenAPI 描述等，便于你在本地/云端进行集成测试。
  • 日志与容器化/部署友好：包含日志输出、错误处理与分层模块设计，便于排错与扩展。

• 安装与运行（简要）

  • 依赖安装：使用项目根目录的包管理工具安装依赖（如 npm/yarn）。
  • 构建 bridge 组件（typeScript/TS+Node）：将 src 代码编译为可运行的 dist 目录。
  • 启动 MCP 服务端（NestJS 应用）以及 Bridge 服务，确保 API 端点与桥接端口可访问。
  • 将 Cursor 等客户端配置为连接到 MCP 服务端提供的端点，并确保 API Key/认证信息正确配置。

• 服务器配置（MCP 客户端连接配置示例） 服务器提供一个用于 MCP 客户端连接的配置信息，包含服务名称、启动命令与参数等。请按以下格式提供配置（JSON，可直接在客户端配置中使用）。其中 server name 与实际部署名称保持一致，command 与 args 根据实际构建产物设置： { "server_name": "docmost-mcp-bridge", "command": "node", "args": ["dist/index.js"], "working_directory": "/path/to/your/repo", "env": { "MCP_SERVER_URL": "http://localhost:3000", // MCP 服务器端地址（若 bridge 运行在同一机，通常指向服务端 MCP 接口） "MCP_API_KEY": "your_api_key_here", // 调用后端 API 的鉴权 Key "DEBUG": "false" } }

• 基本使用方法

  • 运行前准备
    • 启动 Docmost 的 MCP 服务端（NestJS 应用，提供 /api/mcp、/api/mcp-standard 等接口）。
    • 启动 MCP Bridge 服务（如果使用桥接模式），并确保 Bridge 能访问后端 API。
  • 与 Cursor 连接
    • 将 Cursor 配置中的 MCP 端点指向上一步部署的 MCP 服务器（例如 /api/mcp-standard 或桥接暴露的端点）。
    • 使用提供的 API Key 进行鉴权，确保工具能够被正确识别与调用。
  • 使用工具
    • 通过 MCP 客户端触发资源的读取、创建、更新等操作，桥接层将把请求映射到后端 Docmost 的资源、并返回结果。
  • 监控
    • 查看 bridge/log 文件或控制台输出，遇到错误可根据日志定位请求路径、参数格式或鉴权问题。

• 运行与调试建议

  • 先在本地完整启动后端 MCP 服务，再启动 Bridge 服务，确保两端网络/端口访问通畅。
  • 确认环境变量（如 MCP_SERVER_URL、MCP_API_KEY）正确设置，避免 401/403/404 等鉴权或路由错误。
  • 使用 MCP 提供的工具清单接口验证工具暴露情况，确保 Cursor 能获取到正确的工具定义。