OpenPencil MCP 服务端

使用说明（Markdown 格式）

• 项目简介

  • OpenPencil 的 MCP 服务端实现旨在为 LLM 客户端提供标准化的上下文服务，核心能力包括资源管理、工具执行以及提示模板渲染。服务器通过 MCP 协议（JSON-RPC 风格请求/响应、SSE 实时事件等）进行通信，支持多传输方式，并具备会话管理与能力声明能力，方便与 Claude/Codex/Gemini 等代理/CLI 集成。

• 主要功能点

  • 资源管理与数据访问：托管、读取和修改资源数据，供 LLM 客户端查询与使用。
  • 工具注册与执行：注册外部工具（Tools），实现 LLM 调用外部功能的能力。
  • 提示模板（Prompts）：定义和渲染可定制的 Prompt 模板，支持多种交互模式。
  • MCP 服务器端通信：通过 JSON-RPC 风格的请求/响应，以及事件流（SSE）实现实时同步与通知。
  • 会话与能力声明：支持会话管理、能力声明，以及多传输协议（如 Stdio、SSE、WebSocket）的扩展。
  • 与本地/远程 CLI 的集成支持：提供对 Claude Code、Codex、OpenCode、Copilot 等 CLI/SDK 的适配与集成路径。
  • 与渲染端同步：提供对渲染端（Renderer/Electron/Dev Server）的实时文档同步和事件推送。

• 安装步骤

  1. 安装依赖并构建运行环境（项目使用 Bun/Nitro 架构，确保 Node 运行环境可用）。
  2. 构建 MCP 服务端代码到 dist 目录（dist/mcp-server.cjs）。
  3. 启动 MCP HTTP 服务端（默认端口 3100），或按需配置端口。
  4. 客户端集成时，配置 MCP 服务端的启动命令和参数以建立连接。

• 服务器配置（MCP 客户端配置示例） 说明：以下 JSON 配置用于 MCP 客户端在启动阶段与 MCP 服务器建立连接。请注意，客户端本身并不需要提交这段配置给解析程序，而是用于帮助你理解如何对接服务器。该配置包含服务器名称、命令和参数信息，便于脚本化部署与对接。

  { "serverName": "openpencil", "command": "node", "args": [ "dist/mcp-server.cjs", "--http", "--port", "3100" ] // 说明：serverName 为 MCP 服务器标识，command/args 为启动 MCP 服务端进程的命令及参数。 }

  备注：

  • dist/mcp-server.cjs 是构建产物的默认入口路径；实际路径可能根据部署方式有所不同，请以实际构建产物路径为准。
  • 端口号默认使用 3100，可根据需要改动并在服务器端相应配置。
  • MCP 客户端通常通过 JSON-RPC 与该服务器通信，并可通过 SSE 获取实时事件。

• 基本使用方法

  • 启动 MCP 服务器：以 Node/Fork 方式启动 dist/mcp-server.cjs，带上 --http 与 --port 参数。
  • 客户端接入：通过 MCP 客户端按照 MCP 协议发送 JSON-RPC 请求（如读取资源、调用工具、获取 Prompt 等），并处理服务器返回的 JSON-RPC 响应或事件流通知。
  • 会话与广播：服务器在文档变更时会广播更新，Renderer/LLM 客户端通过 SSE 接收实时通知，以实现高效的上下文同步。
  • 与本地 CLI 的集成：如需集成 Claude Code、Codex、OpenCode、Copilot 等工具，请按仓库内的集成逻辑进行工具注册与环境配置。
  • 安全与扩展：服务器实现包含会话管理、能力声明、以及多传输协议的扩展点，便于在生产环境中对接更复杂的客户端。

• 使用注意事项

  • 确保 MCP 服务器可在目标环境中访问（网络/端口开放、必要的依赖已安装）。
  • MCP 服务器端和客户端的版本对齐，以确保 JSON-RPC 的请求/响应结构兼容。
  • 若使用本地 CLI 代理，请确保相应二进制已正确安装并在 PATH 可执行。
  • 生产环境应考虑安全性、认证与授权，以及对通信通道的加密（如搭建 HTTPS/WSS）。

• 其他说明

  • 该实现包含服务端 API、SSE 流、文档同步、以及对外部工具/服务的集成适配能力，目的是为 LLM 客户端提供一个稳定、可扩展的 MCP 服务端。