copilot-sdk-proxy

使用说明（Markdown 格式）

• 项目简介

  • 这是一个服务器端实现，基于 GitHub Copilot SDK，作为一个 MCP 风格的后端服务，提供向 LLM 客户端暴露的标准化 API（如 OpenAI、Claude、Codex 风格的路由），并通过 Copilot SDK 的会话与工具桥接实现资源管理、工具执行、提示渲染等能力。

• 主要功能点

  • MCP 相关能力：通过配置的 MCP 服务器（本地进程、HTTP、SSE 等）来连接后端资源，支持对资源、工具和 Prompts 的管理与渲染。
  • 三大提供商代理：内置对 OpenAI、Claude，以及 Codex 风格 API 的代理路由，实现跨 API 兼容性。
  • 会话与工具管理：使用会话管理器维护对话状态、工具调用以及多轮对话中的上下文传递。
  • 流式响应：通过 SSE/Server-Sent Events 的流式协议支持，逐步返回思考、文本与工具调用结果等。
  • 安全与配置：提供服务器级别配置（MCP 服务器、工具白名单、权限审批等）与自定义会话配置能力，便于在不同环境中部署。

• 安装步骤

  • 安装 Node.js 版本要求：Node.js 版本 25.6.0 及以上。
  • 全局安装服务端包（示例命令，按实际包名执行）：
    • npm install -g copilot-sdk-proxy
  • 启动服务器（默认提供 OpenAI 风格接口，端口 8080）：
    • copilot-proxy
  • 指定提供商（OpenAI、Claude/Anthropic、Codex）与端口：
    • copilot-proxy --provider claude
    • copilot-proxy --provider codex --port 9090
  • 服务器启动后，默认接口地址为 http://localhost:8080（或指定端口），客户端可将请求发送到这些路由来与 Copilot SDK 会话交互。

• 服务器配置（MCP 客户端需的配置信息）

  • MCP 配置用于定义可连接的 MCP 服务器，例如本地类型和远端 HTTP/SSE 服务器等。配置字段通常包含：服务器名称、类型、启动命令、参数、以及可选的环境变量、工作目录、以及允许的命令工具等。
  • 重要字段说明（以 JSON 结构描述，便于 MCP 客户端理解；实际使用时请以服务器端的 config.json5 为准）：
    • mcpServers：包含一个或多个服务器条目，每个条目有名称、type、command、args、env、cwd、timeout、allowedTools 等字段，用于描述需要启动的 MCP 服务及其参数。
    • allowedCliTools：定义 Copilot CLI 工具的白名单（允许全部使用时为 ["*"]，若为特定工具列表则列出名称）。
    • bodyLimit：请求体大小限制，单位为 MiB 的量级。
    • requestTimeoutMs：服务器端请求超时，单位为毫秒。
    • autoApprovePermissions：默认权限自动通过的策略，支持布尔值或具体权限 kinds 的列表。
  • 注意：MCP 客户端在连接时需要具备启动 MCP 服务器所需的命令与参数信息，这些信息在服务器端配置中定义；客户端本身不需要额外的代码改动来“理解”此配置信息。

• 基本使用方法

  • 运行前准备
    • 安装依赖并确保 Copilot 订阅或授权可用。
    • 根据需求在配置文件中定义 MCP 服务器及相关选项。
  • 启动与访问
    • 启动服务器后，默认监听端口 8080，提供对 OpenAI、Claude、Codex 风格请求的代理能力。
    • 客户端可通过对应提供商的路由进行对话，比如 /v1/chat/completions、/v1/models、/v1/responses 等，与 Copilot SDK 会话进行交互。
  • 调试与日志
    • 通过日志级别参数控制输出，默认 info 级别。
    • 如果需要追踪详细调试信息，可以将日志级别设为 debug。