QuickDesk MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • QuickDesk MCP 服务器是一套完整的 MCP 服务端实现，核心职责包括：托管并管理资源（Resources）、注册与执行 Tools、定义并渲染 Prompt 模板（Prompts），并通过 MCP 协议向 AI 客户端提供统一的访问入口。服务器支持两种传输模式：stdio（AI 客户端直接启动服务器）与 HTTP/SSE（服务器托管 MCP 服务，支持多客户端），并通过 WebSocket 作为信令桥接 QuickDesk 的前后端组件。

• 主要功能点

  • MCP 核心接口：初始化、读取资源、列出工具、执行工具、获取 Prompts、事件工具等。
  • 资源、工具、Prompts 的注册、查询与执行。
  • 会话管理：会话创建、鉴权/认证、会话终止等。
  • 支持多客户端并发、事件推送、以及对接快速迭代的 AI Agent。
  • 两种传输模式：stdio 与 HTTP/SSE。HTTP 模式下提供 /health、/mcp、以及 SSE 事件流。
  • 与 QuickDesk Signaling、WS 客户端和 WebSocket 信令桥接，完成与宿主机器的指令流转。

• 安装步骤

  • 将仓库源码获取到本地（建议使用 Git 克隆或下载压缩包）。
  • 安装并构建 MCP 服务端（quickdesk-mcp），根据 README/构建脚本完成编译：
    • 依赖的工具链和语言环境请参阅 quickdesk-mcp 子工程目录中的 README/脚本。
    • 运行时产物为 quickdesk-mcp，可选择 stdio 或 http 传输模式。
  • 启动 MCP 服务器：
    • stdio 模式：直接以命令行启动快速进入 MCP 环境。
    • http 模式：以 HTTP/SSE 方式对外提供 MCP 服务，需要搭建 Signaling 服务与 React/Qt 客户端对接的信令通道。
  • 将 AI 客户端配置为连接 MCP 服务器：
    • 需要给 MCP 客户端提供正确的 server 名称、启动命令及参数等信息（见下方“服务器配置”）。

• 服务器配置（MCP 客户端需要的配置示例，格式为 JSON，包含 server name、command、args 等）

  • serverName: quickdesk-mcp
  • command: quickdesk-mcp
  • args: ["--transport", "http", "--port", "18080", "--ws-url", "ws://127.0.0.1:9600"]
  • 注释：该配置用于告知 MCP 客户端如何启动服务器及连接参数，其中 transport 指定传输模式（http），port 为监听端口，ws-url 指向 QuickDesk 的 WebSocket 信令入口。由于 MCP 客户端通常不需要直接修改实现代码，此配置仅用于自动化部署与集成场景。

• 基本使用方法

  • 将 MCP 服务器部署在可访问的主机上，确保信令通道可达。
  • 启动 MCP 服务器（选择 stdio 或 HTTP/ SSE 传输模式）。
  • 使用 AI Agent（如 Claude, GPT 等）连接到 MCP 服务器，通过 MCP 的工具、资源、Prompts 等 API 进行资源访问、外部工具调用、和 Prompt 渲染。
  • 通过 Signaling 服务对 QuickDesk 主机进行控制，确保会话、鉴权、事件推送等机制正常工作。
  • 监控 MCP 服务器的健康状态、日志与性能，以确保多客户端并发访问的稳定性。