@nick3/copilot-api 1.10.9 → 1.10.30

package/README.md

@@ -30,7 +30,7 @@ English | [简体中文](./README.zh-CN.md)
 >
 > 2. **Recommend for Opencode:** When using with opencode, we recommend starting with the opencode OAuth app. This approach behaves identically to opencode's built-in GitHub Copilot provider with no Terms of Service risk:
 >    ```sh
->    npx @nick3/copilot-api@latest --oauth-app=opencode start
+>    bunx --bun @nick3/copilot-api@latest --oauth-app=opencode start
 >    ```
 >
 > 3. **Disable multi agent when using codex:** If you're using codex via GitHub Copilot, it's recommended to disable the multi agent feature. Currently, GitHub Copilot charges based on the last message being a user role when using codex, and the billing logic has not been adjusted.
@@ -46,6 +46,7 @@ Compared with routing everything through plain Chat Completions compatibility, t
 ## Features
 
 - **OpenAI & Anthropic Compatibility**: Exposes GitHub Copilot as an OpenAI-compatible (`/v1/responses`, `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`) and Anthropic-compatible (`/v1/messages`) API.
+- **Codex Responses WebSocket Compatibility**: Accepts Codex's preferred Responses WebSocket transport on `/v1/responses` and bridges it through the existing Responses handler.
 - **Anthropic-First Routing for Claude Models**: When a model supports Copilot's native `/v1/messages` endpoint, the proxy prefers it over `/responses` or `/chat/completions`, preserving Anthropic-style `tool_use` / `tool_result` flows and more Claude-native behavior.
 - **Fewer Unnecessary Premium Requests**: Reduces wasted premium usage by routing warmup requests to `smallModel`, merging `tool_result` follow-ups back into the tool flow, and treating resumed tool turns as continuation traffic instead of fresh premium interactions.
 - **Phase-Aware `gpt-5.4` and `gpt-5.3-codex`**: These models can emit user-friendly commentary before deeper reasoning or tool use, so long-running coding actions are easier to understand instead of appearing as a sudden tool burst.
@@ -126,7 +127,7 @@ When an Anthropic API key is configured, the proxy forwards Claude model token c
 ## Prerequisites
 
 - Bun (>= 1.2.x)
-- Node.js if you plan to run the published CLI with `npx`
+- Node.js only if you want to run the lightweight MCP bridge through `npx`
 - GitHub account with Copilot subscription (individual, business, or enterprise)
 
 ## Installation
@@ -143,26 +144,28 @@ To start the server directly from source:
 bun run start start
 ```
 
-## Using with npx
+## Using the published CLI with Bun
 
-You can run the project directly using npx:
+The server and account-management commands are Bun-only because the Admin UI and request history use `bun:sqlite`. Run the published CLI with Bun so the `#!/usr/bin/env node` shebang does not force Node.js:
 
 ```sh
-npx @nick3/copilot-api@latest start
+bunx --bun @nick3/copilot-api@latest start
 ```
 
 With options:
 
 ```sh
-npx @nick3/copilot-api@latest start --port 8080
+bunx --bun @nick3/copilot-api@latest start --port 8080
 ```
 
 For authentication only:
 
 ```sh
-npx @nick3/copilot-api@latest auth
+bunx --bun @nick3/copilot-api@latest auth
 ```
 
+The lightweight MCP bridge is the exception and can still be launched with `npx`; see [GPT Tool Search](#gpt-tool-search).
+
 ## Using with Docker
 
 Build image
@@ -293,6 +296,20 @@ The following command line options are available for the `start` command:
 | --claude-code  | Generate a command to launch Claude Code with Copilot API config              | false      | -c    |
 | --show-token   | Show GitHub and Copilot tokens on fetch and refresh                           | false      | none  |
 | --proxy-env    | Initialize proxy from environment variables                                   | false      | none  |
+| --enable-mcp-http | Expose the unauthenticated MCP Streamable HTTP endpoint at `/mcp`          | false      | none  |
+
+### MCP Command Options
+
+The `mcp` command defaults to stdio for local Claude Code compatibility. Use `--transport http` only when your MCP client supports Streamable HTTP.
+
+| Option      | Description                         | Default   |
+| ----------- | ----------------------------------- | --------- |
+| --transport | Transport to use: `stdio` or `http` | stdio     |
+| --host      | HTTP transport host                 | 127.0.0.1 |
+| --port      | HTTP transport port                 | 4142      |
+| --path      | HTTP transport path                 | /mcp      |
+
+MCP HTTP browser CORS is loopback-only by default. Set `COPILOT_API_MCP_HTTP_ALLOWED_ORIGINS=https://client.example.com,https://admin.example.com` to allow extra browser origins, or `*` to explicitly opt into wildcard CORS.
 
 ### Auth Command Options
 
@@ -451,7 +468,7 @@ The `<target>` can be either the account ID (GitHub login) or a 1-based index.
 - **modelRefreshIntervalHours:** Interval for refreshing account model lists in the background. Set to `0` to disable refresh. Defaults to `24`.
 - **sessionAffinityRetentionDays:** Number of days to retain session affinity bindings. Defaults to `7`.
 - **useMessagesApi:** When `true` (default), Claude-family models that support Copilot's native `/v1/messages` endpoint may use the Messages API path. Set to `false` to skip the Messages API candidate and fall back to `/responses` (if supported) or `/chat/completions`.
-- **useResponsesApiWebSocket:** When `true` (default), Responses API requests use Copilot's WebSocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable WebSocket routing.
+- **useResponsesApiWebSocket:** When `true` (default), outbound Copilot Responses API requests use Copilot's WebSocket transport for models that advertise `ws:/responses`; models that only advertise `/responses` continue to use HTTP. Set to `false` to disable upstream WebSocket routing. This does not disable the inbound Codex-compatible WebSocket listener on `/v1/responses`.
 - **useResponsesApiWebSearch:** When `true` (default), `/v1/responses` keeps tools with `type: "web_search"` and forwards them upstream. Set to `false` to strip them before the Copilot request is sent.
 - **logLevel:** Controls handler file-log verbosity under `logs/*.log`. Allowed values: `error`, `warn`, `info`, `debug`. Defaults to `info`. Set it to `debug` when you need payload- or stream-level diagnostics written into file logs.
 - **anthropicApiKey:** Optional Anthropic API key used for accurate Claude token counting (see [Accurate Claude Token Counting](#accurate-claude-token-counting) below). Can also be set via the `ANTHROPIC_API_KEY` environment variable. If not set, token counting falls back to GPT tokenizer estimation.
@@ -489,6 +506,7 @@ These endpoints mimic the OpenAI API structure.
 | Endpoint                    | Method | Description                                                      |
 | --------------------------- | ------ | ---------------------------------------------------------------- |
 | `POST /v1/responses`        | `POST` | OpenAI Most advanced interface for generating model responses.          |
+| `GET /v1/responses`         | `WS`   | Codex-compatible Responses WebSocket transport.                  |
 | `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation.        |
 | `GET /v1/models`            | `GET`  | Lists the currently available models.                            |
 | `POST /v1/embeddings`       | `POST` | Creates an embedding vector representing the input text.         |
@@ -570,86 +588,98 @@ The server also exposes a built-in admin UI and API for inspecting account statu
 
 ## Example Usage
 
-Using with npx:
+Using the published CLI with Bun:
 
 ```sh
 # Basic usage with start command
-npx @nick3/copilot-api@latest start
+bunx --bun @nick3/copilot-api@latest start
 
 # Run on custom port with verbose logging
-npx @nick3/copilot-api@latest start --port 8080 --verbose
+bunx --bun @nick3/copilot-api@latest start --port 8080 --verbose
 
 # Use with a business plan GitHub account
-npx @nick3/copilot-api@latest start --account-type business
+bunx --bun @nick3/copilot-api@latest start --account-type business
 
 # Use with an enterprise plan GitHub account
-npx @nick3/copilot-api@latest start --account-type enterprise
+bunx --bun @nick3/copilot-api@latest start --account-type enterprise
 
 # Enable manual approval for each request
-npx @nick3/copilot-api@latest start --manual
+bunx --bun @nick3/copilot-api@latest start --manual
 
 # Set rate limit to 30 seconds between requests
-npx @nick3/copilot-api@latest start --rate-limit 30
+bunx --bun @nick3/copilot-api@latest start --rate-limit 30
 
 # Wait instead of error when rate limit is hit
-npx @nick3/copilot-api@latest start --rate-limit 30 --wait
+bunx --bun @nick3/copilot-api@latest start --rate-limit 30 --wait
 
 # Provide GitHub token directly
-npx @nick3/copilot-api@latest start --github-token ghp_YOUR_TOKEN_HERE
+bunx --bun @nick3/copilot-api@latest start --github-token ghp_YOUR_TOKEN_HERE
 
 # Run only the auth flow
-npx @nick3/copilot-api@latest auth
+bunx --bun @nick3/copilot-api@latest auth
 
 # Run auth flow with verbose logging
-npx @nick3/copilot-api@latest auth --verbose
+bunx --bun @nick3/copilot-api@latest auth --verbose
 
 # Add multiple accounts (each account is added in order)
-npx @nick3/copilot-api@latest auth add
-npx @nick3/copilot-api@latest auth add  # add second account
+bunx --bun @nick3/copilot-api@latest auth add
+bunx --bun @nick3/copilot-api@latest auth add  # add second account
 
 # List all registered accounts
-npx @nick3/copilot-api@latest auth ls
+bunx --bun @nick3/copilot-api@latest auth ls
 
 # List accounts with quota information
-npx @nick3/copilot-api@latest auth ls -q
+bunx --bun @nick3/copilot-api@latest auth ls -q
 
 # Remove an account by index (1-based)
-npx @nick3/copilot-api@latest auth rm 2
+bunx --bun @nick3/copilot-api@latest auth rm 2
 
 # Remove an account by ID (GitHub login)
-npx @nick3/copilot-api@latest auth rm octocat
+bunx --bun @nick3/copilot-api@latest auth rm octocat
 
 # Show your Copilot usage/quota in the terminal (no server needed)
-npx @nick3/copilot-api@latest check-usage
+bunx --bun @nick3/copilot-api@latest check-usage
 
 # Display debug information for troubleshooting
-npx @nick3/copilot-api@latest debug
+bunx --bun @nick3/copilot-api@latest debug
 
 # Display debug information in JSON format
-npx @nick3/copilot-api@latest debug --json
+bunx --bun @nick3/copilot-api@latest debug --json
 
 # Initialize proxy from environment variables (HTTP_PROXY, HTTPS_PROXY, etc.)
-npx @nick3/copilot-api@latest start --proxy-env
+bunx --bun @nick3/copilot-api@latest start --proxy-env
 
 # Use opencode GitHub Copilot authentication
-COPILOT_API_OAUTH_APP=opencode npx @nick3/copilot-api@latest start
+COPILOT_API_OAUTH_APP=opencode bunx --bun @nick3/copilot-api@latest start
 
 # Set custom API home directory via command line
-npx @nick3/copilot-api@latest --api-home=/path/to/custom/dir start
+bunx --bun @nick3/copilot-api@latest --api-home=/path/to/custom/dir start
 
 # Use GitHub Enterprise via command line
-npx @nick3/copilot-api@latest --enterprise-url=company.ghe.com start
+bunx --bun @nick3/copilot-api@latest --enterprise-url=company.ghe.com start
 
 # Use opencode OAuth via command line
-npx @nick3/copilot-api@latest --oauth-app=opencode start
+bunx --bun @nick3/copilot-api@latest --oauth-app=opencode start
 
 # Combine multiple global options
-npx @nick3/copilot-api@latest --api-home=/custom/path --oauth-app=opencode --enterprise-url=company.ghe.com start
+bunx --bun @nick3/copilot-api@latest --api-home=/custom/path --oauth-app=opencode --enterprise-url=company.ghe.com start
+```
 
-# Run the published CLI with Bun instead of Node.js
-bunx --bun @nick3/copilot-api@latest start
+For the MCP tool-search bridge only, `npx` remains supported:
+
+```sh
+# Local stdio MCP bridge, unchanged
+npx -y @nick3/copilot-api@latest mcp
+
+# Standalone Streamable HTTP MCP bridge
+npx -y @nick3/copilot-api@latest mcp --transport http --host 127.0.0.1 --port 4142 --path /mcp
+
+# Main proxy server with /mcp explicitly enabled
+bunx --bun @nick3/copilot-api@latest start --enable-mcp-http
 ```
 
+The HTTP MCP endpoint is unauthenticated. Keep the default loopback host for standalone mode. Browser CORS defaults to loopback origins only; set `COPILOT_API_MCP_HTTP_ALLOWED_ORIGINS` only for trusted clients. Do not expose `/mcp` on an untrusted network unless an external proxy, firewall, or tunnel access policy protects it.
+
 ### Opencode OAuth Authentication
 
 You can use opencode GitHub Copilot authentication instead of the default one:
@@ -659,16 +689,52 @@ You can use opencode GitHub Copilot authentication instead of the default one:
 export COPILOT_API_OAUTH_APP=opencode
 
 # Then run start or auth commands
-npx @nick3/copilot-api@latest start
-npx @nick3/copilot-api@latest auth
+bunx --bun @nick3/copilot-api@latest start
+bunx --bun @nick3/copilot-api@latest auth
 ```
 
 Or use inline environment variable:
 
 ```sh
-COPILOT_API_OAUTH_APP=opencode npx @nick3/copilot-api@latest start
+COPILOT_API_OAUTH_APP=opencode bunx --bun @nick3/copilot-api@latest start
+```
+
+## Using with Codex CLI
+
+Codex can use this proxy as an OpenAI-compatible Responses API provider. The proxy supports both Codex's HTTP `POST /v1/responses` path and its preferred WebSocket upgrade on `GET /v1/responses`.
+
+Start the proxy:
+
+```sh
+bunx --bun @nick3/copilot-api@latest start
+```
+
+> **Note:** The inbound Codex WebSocket listener on `GET /v1/responses` requires the Bun server runtime, so start the proxy with `bunx --bun` (or a local Bun install). The `npx` path is only supported for the lightweight MCP bridge and does not run the WebSocket listener.
+
+Add a provider to `~/.codex/config.toml`:
+
+```toml
+[model_providers.copilot-api]
+name = "copilot-api"
+base_url = "http://localhost:4141/v1"
+wire_api = "responses"
+supports_websockets = true
+
+[profiles.copilot-api]
+model_provider = "copilot-api"
+model = "gpt-5.4"
 ```
 
+Then run Codex with that profile:
+
+```sh
+codex -p copilot-api
+```
+
+If you configured `auth.apiKeys`, add the same key to Codex's provider headers or bearer-token configuration so both HTTP and WebSocket requests authenticate successfully. For troubleshooting only, set `supports_websockets = false` in Codex to force its HTTP fallback path.
+
+> **Note:** When using Codex via GitHub Copilot, it is currently recommended to disable Codex multi-agent features because Copilot billing may count Codex traffic based on the final user-role message.
+
 ## Using with Claude Code
 
 This proxy can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code), an experimental conversational AI assistant for developers from Anthropic.
@@ -680,7 +746,7 @@ There are two ways to configure Claude Code to use this proxy:
 To get started, run the `start` command with the `--claude-code` flag:
 
 ```sh
-npx @nick3/copilot-api@latest start --claude-code
+bunx --bun @nick3/copilot-api@latest start --claude-code
 ```
 
 You will be prompted to select a primary model and a "small, fast" model for background tasks. After selecting the models, a command will be copied to your clipboard. This command sets the necessary environment variables for Claude Code to use the proxy.
@@ -736,7 +802,9 @@ Do not set Claude Code's native `ENABLE_TOOL_SEARCH` for GPT models. That flag e
 
 If you install `tool-search@copilot-api-marketplace`, Claude Code receives this MCP bridge automatically and you can skip the manual Claude Code MCP setup below.
 
-Add the tool search bridge to the MCP config used by Claude Code:
+This MCP bridge is intentionally small and does not load the server or SQLite code, so it remains safe to run through `npx`. Use Bun for the main `start`, `auth`, `check-usage`, and `debug` commands.
+
+Add the tool search bridge to the MCP config used by Claude Code over stdio:
 
 ```json
 {
@@ -750,6 +818,33 @@ Add the tool search bridge to the MCP config used by Claude Code:
 }
 ```
 
+To use Streamable HTTP instead, start the MCP HTTP bridge in one terminal:
+
+```sh
+npx -y @nick3/copilot-api@latest mcp --transport http --host 127.0.0.1 --port 4142 --path /mcp
+```
+
+Then add the HTTP MCP server to Claude Code:
+
+```sh
+claude mcp add --transport http tool_search http://127.0.0.1:4142/mcp
+```
+
+Equivalent manual MCP config:
+
+```json
+{
+  "mcpServers": {
+    "tool_search": {
+      "type": "http",
+      "url": "http://127.0.0.1:4142/mcp"
+    }
+  }
+}
+```
+
+If you prefer the main proxy process to expose the same MCP server, start it with `--enable-mcp-http` and use `http://127.0.0.1:4141/mcp` as the Claude Code MCP URL. Use either the stdio config or the HTTP config for `tool_search`, not both.
+
 Add the tool search bridge to the MCP config used by opencode:
 
 ```json
@@ -778,7 +873,7 @@ OpenCode already has a direct GitHub Copilot provider. Use this section when you
 Start the proxy with the OpenCode OAuth app:
 
 ```sh
-npx @nick3/copilot-api@latest --oauth-app=opencode start
+bunx --bun @nick3/copilot-api@latest --oauth-app=opencode start
 ```
 
 Then point OpenCode at the proxy with `@ai-sdk/anthropic`.
@@ -868,7 +963,7 @@ Why these fields matter:
 curl "http://localhost:4141/api/admin/meta"
 
 # Enable remote admin UI/API access (server-side)
-# ADMIN_TOKEN=your_admin_token_here npx @nick3/copilot-api@latest start
+# ADMIN_TOKEN=your_admin_token_here bunx --bun @nick3/copilot-api@latest start
 
 # Remote access (token required)
 curl -H "x-admin-token: your_admin_token_here" "http://localhost:4141/api/admin/accounts?include_stats=1"
@@ -886,9 +981,9 @@ curl "http://localhost:4141/api/admin/requests/<requestId>"
 
 The proxy includes a built-in admin UI served from your running instance. It lets you inspect account status and request history captured by the proxy (models/endpoints, tokens/usage, timing, and error summaries).
 
-1. Start the server. For example, using npx:
+1. Start the server. For example, using Bun:
     ```sh
-    npx @nick3/copilot-api@latest start
+    bunx --bun @nick3/copilot-api@latest start
     ```
 2. Open the UI in your browser:
     - `http://localhost:4141/admin` (replace the port if you changed it)