mirror of
https://wget.la/https://github.com/leookun/cursor-byok
synced 2026-08-17 19:47:10 +08:00
71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# Cursor Protocol Debugger
|
|
|
|
[中文](README.md) | [English](README.en.md)
|
|
|
|
This standalone local Cursor API debugging service forwards every HTTP request outside the `__debuger__` debugging namespace to the fixed upstream `https://api2.cursor.sh`, preserving the method, path, query, headers, and body. It continues to capture `BidiAppend`, `RunSSE`, Fork Chat, and model-discovery traffic.
|
|
|
|
It is not a general-purpose HTTP proxy, does not handle `CONNECT`, requires no CA certificate, and does not modify the system proxy.
|
|
|
|
## Start
|
|
|
|
Generate the sibling `cursor-proto` module's Go code before the first build:
|
|
|
|
```bash
|
|
(cd ../cursor-proto && ./scripts/generate.sh)
|
|
go run .
|
|
```
|
|
|
|
The service listens on a single port:
|
|
|
|
- Cursor API service: `http://127.0.0.1:9090`
|
|
- Debugging UI: `http://127.0.0.1:9090/__debuger__/`
|
|
- Debugging API: `http://127.0.0.1:9090/__debuger__/api/*`
|
|
- Fixed upstream: `https://api2.cursor.sh`
|
|
|
|
The debugging UI opens automatically after startup.
|
|
|
|
## Configure Cursor
|
|
|
|
Quit Cursor completely, then launch it from a terminal with the local API address:
|
|
|
|
```bash
|
|
CURSOR_API_ENDPOINT=http://127.0.0.1:9090 \
|
|
CURSOR_API_BASE_URL=http://127.0.0.1:9090 \
|
|
/Applications/Cursor.app/Contents/MacOS/Cursor
|
|
```
|
|
|
|
`CURSOR_API_ENDPOINT` overrides the Agent API endpoint. `CURSOR_API_BASE_URL` also routes requests such as authentication that use the base API address through this service. Cursor proxy and Network settings do not need to be changed.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
(cd ../cursor-proto && ./scripts/generate.sh)
|
|
go build -o ./bin/cursor-proxy-debugger .
|
|
```
|
|
|
|
## Dependency Layout
|
|
|
|
The debugger is an independent Go module. Cursor protobuf message packages are generated by the sibling `cursor-proto` module. The generated `gen/` directory is not committed, so run its `scripts/generate.sh` before the first build. This project does not depend on the outer `cursor-byok` Go module.
|
|
|
|
## Options
|
|
|
|
```text
|
|
-addr Cursor API service listen address; default: 127.0.0.1:9090
|
|
-max-exchanges Maximum exchanges retained in memory; default: 200
|
|
-db SQLite database path; defaults to the user configuration directory
|
|
-open Open the browser after startup; default: true
|
|
```
|
|
|
|
## Data Handling
|
|
|
|
- Every request received by the service is forwarded to `https://api2.cursor.sh`; clients cannot select another upstream.
|
|
- The `__debuger__` namespace is reserved for the local debugging page and API and is never forwarded upstream.
|
|
- `RunSSE` is decoded incrementally using the 5-byte Connect frame header and supports per-frame gzip decompression.
|
|
- `BidiAppendRequest.data` is further decoded as `agent.v1.AgentClientMessage`.
|
|
- Fork Chat's `ForkBackgroundComposer`, `NotifyConversationClone`, and `UploadConversationBlobs` traffic is decoded bidirectionally as protobuf JSON.
|
|
- `CppService/AvailableModels`, `AiService/AvailableModels`, `GetDefaultModel`, and `GetDefaultModelNudgeData` are decoded bidirectionally.
|
|
- Requests can be filtered by time and protocol `request_id`; the UI can query by `conversation_id` and group requests by conversation.
|
|
- Complete captures are stored in SQLite and remain queryable after restart; `max-exchanges` only limits hot in-memory data.
|
|
- Sensitive headers such as `Authorization`, `Cookie`, and `Set-Cookie` are hidden in the UI by default.
|
|
- Raw bodies are retained up to 2 MiB per side by default; capture limits never truncate forwarded traffic.
|