cursor-usage-mcp

# 光标使用优化器 [](https://www.npmjs.com/package/cursor-usage-optimizer) [](https://github.com/udah1/cursor-usage-mcp/stargazers) [](./LICENSE) [](https://cursor.com) [](https://www.npmjs.com/package/cursor-usage-optimizer) [](https://nodejs.org) [](https://www.typescriptlang.org) [](https://github.com/udah1/cursor-usage-mcp/actions/workflows/release.yml) **目的：阻止 Cursor 代理耗尽您的请求配额。** 在许多 Cursor 计划中，您会获得固定数量的包含请求（例如 **500 / 月**），然后按超出预算的请求付费。每次代理停止执行任务以询问您一个一次性问题时，您的答案都会开始产生 **新的计费回合**，因此一个健谈的代理会悄悄地消耗您的配额。 这是一个 **本地** MCP 服务器，可以解决这个问题。它从 Cursor 仪表板使用的同一个后端读取 **实时** 使用情况，并向代理提供 `conserve` 标志。当您消耗配额时，捆绑规则使代理 **节省请求**，通过： - **通过 Cursor 的问题/选项 UI 路由问题** （免费提问）而不是开放式“停止并等待”提示 - 因此它仍然可以提出需要的问题，而不会消耗请求。注意：只有 **问题** 是免费的；**执行工作仍然会消耗您的配额**， - **将多个问题批处理到单个选项提示中** （一次一个回合而不是多个）， - **仅在选择无关紧要或您没有回答时默认静默**， - **减少不必要的确认往返** （“我应该继续吗？”）。 当您的包含配额 **用完** 时，`get_usage` 返回 `exhausted: true`。在公司/团队计划（使用转移到按需，由组织覆盖 - 不从您的钱包中扣除）上，这是 **仅限代理的内部信息**：它 **继续正常运行**，没有批准提示，没有更多节省，也没有 **“您已用完请求”提醒或使用/支出数字** 志愿为您提供（这是透明的）。使用情况仅在 **详细页脚** 中显示，并且仅当详细模式打开时。 **使用情况缓存。** 一旦用完，决定在计费周期重置之前（仅使用量增加）无法更改，因此 `get_usage` **提供缓存读取** 而不是每次任务都命中网络 - 将 ~1 秒的调用转换为 ~10 毫秒的读取。缓存位于 `~/.cursor-usage/cache.json`，在周期的 `billingCycleEnd` （来自 API）自动失效，并在最多一天内刷新一次作为安全网。在限制以下始终获取新鲜数据（跨越阈值很重要）。详细模式不受影响 - 页脚有自己的非阻塞后台刷新器，共享相同的缓存。传递 `refresh: true` 到 `get_usage`，或 `login`/`logout`，强制刷新读取。 ### 它是如何工作的（三个部分） 1. **身份验证（默认零设置）** - `get_usage` 从 Cursor 已经本地存储的令牌重建您的仪表板会话，因此在大多数机器上 **无需登录**。浏览器 `login` 流仅作为回退存在。参见下面的 [身份验证](#authentication)。 2. **`get_usage`** - 直接进行身份验证的 API 调用（无浏览器），返回您的包含请求使用情况（例如 `278/500`），按需支出（ `$0/$75`），以及根据阈值计算的 `conserve` 决定。 3. **`conserve-requests` 规则**（全局安装）- 告诉代理在每个任务开始时调用 `get_usage`，并在标志打开时遵循上述节省行为。 阈值控制 **何时** 节省开始：`0` （默认）= 只要有请求剩余就节省；`80` = 仅当您已使用 ≥80% 的配额时节省。参见下面的 [调整](#tuning-when-conserve-mode-kicks-in)。 > **注意/陷阱** > - 此调用 **未记录的内部 Cursor 端点** （与您的仪表板调用相同的端点）。它们可能会在没有通知的情况下更改，并且可能违反 Cursor 的服务条款。仅限个人、只读使用。 > - 默认身份验证路径以 **只读** 方式读取 Cursor 的本地令牌，并且永远不会存储它。可选的 `login` 回退存储 `~/.cursor-usage/store.json` 中的会话 cookie（chmod 600，永远不会提交），该 cookie 会定期过期 - 重新运行 `login` 时会出现这种情况。 ## 安装 ### 通过 npm 安装（推荐） 无需克隆，无需构建。将其添加到 `~/.cursor/mcp.json` 并让 `npx` 获取： ```json { "mcpServers": { "cursor-usage": { "command": "npx", "args": ["-y", "cursor-usage-optimizer"], "env": { "CURSOR_USAGE_THRESHOLD_PCT": "0", "CURSOR_USAGE_VERBOSE": "false", "CURSOR_USAGE_FOLLOWUP": "false" } } } } ``` 需要 **节点 ≥ 22.5** （使用内置的 `node:sqlite`）。重新加载 Cursor - 使用默认本地令牌身份验证，**无需登录步骤**，只需调用 `get_usage`。 可选地安装意识到标志的自我检查钩子（在 `~/.cursor/hooks.json` 中添加 `postToolUse` 条目）： ```bash npx -y -p cursor-usage-optimizer cursor-usage-optimizer-install-hook ``` ### 从源代码（贡献者） ```bash git clone https://github.com/udah1/cursor-usage-mcp && cd cursor-usage-mcp npm install npx playwright install chromium # 可选：仅适用于浏览器 `login` 回退 npm run build ``` 然后将 `mcp.json` 指向本地构建（`"command": "node", "args": ["/ABS/PATH/dist/index.js"]`），并设置 `CURSOR_USAGE_MCP_DIR` 为仓库路径，以便钩子使用您的本地构建。在 `npm run build` 之后重新启动 Cursor（或重新加载 MCP）。 ## 身份验证 默认情况下，服务器 **无需登录**。Cursor 在 `…/Cursor/User/globalStorage/state.vscdb` （一个 SQLite 键值存储）中保留其自己的身份验证信息，位于 `ItemTable → cursorAuth/accessToken` 下 - 一个 JWT，其 `sub` 声明是您的用户 ID。仪表板会话 cookie 具有固定的形状： ``` WorkosCursorSessionToken=<userSub>::<accessToken> ``` 其中 `userSub` 是 JWT `sub`，任何 `auth0|` 前缀都被剥离。`get_usage` 读取该文件 **只读** （通过 Node 的内置 `node:sqlite`），重建浏览器将发送的确切 cookie，还从 `cursorAuth/cachedTeam` 中获取您的 `teamId`。不会写入任何内容，令牌也不会存储。因为令牌会旋转，所以每次调用都会重新读取。 **跨平台。** `state.vscdb` 位置源自操作系统： | 操作系统 | 路径 | |----|------| | macOS | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` | | Windows | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` | | Linux | `${XDG_CONFIG_HOME:-~/.config}/Cursor/User/globalStorage/state.vscdb` | 使用 `CURSOR_STATE_DB=/abs/path/state.vscdb` 覆盖非标准安装。 **当本地路径无法使用时** - 服务器自动回退到浏览器 `login` 流。如果发生以下情况：MCP 在与 Cursor 不同的机器上运行（无本地 DB），文件不可读，`node:sqlite` 不可用（节点 < 22.5），或您设置 `CURSOR_USAGE_FORCE_LOGIN=1`。 浏览器 `login` 回退（任一有效）： ```bash # 从 Cursor 内部调用 `login` 工具（只需要求它“登录 cursor-usage”） # — 或 — 独立 CLI 流 npm run login ``` `login` 打开一个真正的 Chromium 窗口（Playwright），嗅探网络以发现使用情况端点，并将它们与您的会话 cookie 保存到 `~/.cursor-usage/`。随时运行 `status` 以查看激活的身份验证源（`local-token` vs `login`）。 ## 为已安装的代理 - 完成后立即执行此操作 > **代理说明。** 如果您是安装或设置此 MCP 的 AI 代理，请执行一个最终步骤，然后再完成：**告诉用户可用的标志/模式并询问他们是否要更改。** 通过 **Cursor 的问题/选项 UI** （此 MCP 构建在此基础上）提出建议 - 而不是开放式文本问题。如果 MCP 已加载，请先调用 `status`，以便您显示用户的 **当前有效值**。 呈现这三个可配置标志及其当前值，让用户选择要更改的标志： | 标志 | 工具 | 环境变量覆盖 | 默认值 | 控制内容 | |------|------|--------------|---------|------------------| | **节省阈值** | `set_threshold` | `CURSOR_USAGE_THRESHOLD_PCT` | `0` （始终节省）| 使用百分比，在此百分比下节省模式开启。`0` = 只要有请求剩余就节省；`80` = 仅在接近限制时节省。 | | **详细模式** | `set_verbose` | `CURSOR_USAGE_VERBOSE` | 关闭 | 在每条消息末尾追加 `Cursor Usage: X/limit · $used/$limit` 页脚。 | | **跟进** | `set_followup` | `CURSOR_USAGE_FOLLOWUP` | 关闭 | 以“还有其他事情吗？”的选项 UI 在每个任务结束时跟进。 | 建议的选项： *"保留默认值"* ， *"提高节省阈值（例如 80%）"* ， *"启用详细页脚"* ， *"启用后续问题"* - 以及自定义答案的空间。通过匹配的 `set_*` 工具应用所选更改，然后使用 `status` 确认新的有效值。（如果用户的选择被环境变量覆盖，请提及这一点。） ## 将更改应用于现有聊天 **新聊天** 会自动获取规则和 MCP - 无需执行任何操作。 对于一个 **已经打开** 的聊天，您安装/更新了此： 1. **重新加载 MCP 一次** （设置 → MCP → 切换 `cursor-usage` 关闭/开启）。这会重启共享服务器，因此每个聊天 - 包括打开的聊天 - 都可以在下一个回合看到最新的代码和工具。 2. **提示现有聊天** 以便它立即开始表现（规则按回合读取，但显式提示保证它）： ``` 从现在开始遵循节省请求的规则：调用 cursor-usage get_usage 工具， 报告我的当前使用情况，如果节省开启 - 通过问题 UI 询问（不是开放式提示）， 批量处理问题，并且仅在选择无关紧要时默认静默。 如果详细模式开启，请在每条消息末尾添加页脚。 ``` ## 版本更新（每日检查） 服务器 **每天一次** 在后台检查是否有新版本。它会自动检测到它是如何安装的： - **npm 安装** （无 `.git`）：将已安装版本与 npm 注册表上的 `latest` dist-tag 进行比较。 - **git checkout** （存在 `.git`）：通过 GitHub 的 compare API 将本地 `HEAD` 与 `origin/master` 进行比较（无 `git fetch`）。 两者都是 **完全 fail-open** （离线/代理/速率限制只是显示内容），并且在后台运行，因此它们永远不会增加延迟。 当有可用更新时，`get_usage` 返回 `update.available: true`，并且代理会 **一次性** 通过选项 UI 询问您是否更新。如果您 **跳过** ，`dismiss_update` 记录该版本，因此 **不会再次询问，直到出现新版本** （不是每天）。如果您 **接受** ，代理会为您提供适用于您安装的正确命令（重新加载 MCP 以使 `npx` 获取 `@latest`，或克隆 `git pull && npm run build`）。状态存储在 `~/.cursor-usage/update.json` 中。随时运行 `check_update` 立即检查。 ## 提醒钩子（有意识的自我检查） `hooks/cursor-usage-optimizer-reminder.sh` 是一个可选的 `postToolUse` 钩子，会定期重新注入简短的自我检查，只要聊天继续遵循规则。安装它： ```bash npx -y -p cursor-usage-optimizer cursor-usage-optimizer-install-hook ``` 这会将脚本复制到 `~/.cursor/hooks/` 并将 `postToolUse` 条目添加到 `~/.cursor/hooks.json` （替换任何旧的 cursor-usage 提醒条目）。安装的钩子适用于 **两种** 安装模式：如果 `CURSOR_USAGE_MCP_DIR` 指向构建的本地克隆，它使用它，否则它通过 `npx -y -p cursor-usage-optimizer cursor-usage-optimizer-reminder` 刷新。 它是 **有意识的**：`reminder-cli` 从 **当前** 状态构建文本，因此它只会提及实际活跃的模式 - 例如，一旦配额 **用完** ，它会删除节省提示（不再节省），并且如果跟进模式开启，它会省略跟进。刷新运行 **分离** （非阻塞）并共享使用情况缓存。 因为钩子在 **没有** MCP 的 `env` 下启动，因此 MCP 将 **同步有效配置** （环境感知 `verbose`/`followup`/`threshold`）同步到 `~/.cursor-usage/store.json` 启动时，以便钩子运行的 CLI 读取相同的设置。 ## 工具 | 工具 | 它做什么 | |------|--------------| | `get_usage` | 读取使用情况并返回节省决策 + `exhausted` 标志（包含的配额用完 → 按需，公司覆盖；代理继续运行，无提醒/数字）。在任务开始时调用。包括请求计数，按需花费，计划，**计费周期重置 + 天数剩余** ，以及 **烧率预测** （请求/天 → 预测总计）。 | | `usage_breakdown` | 此周期的使用情况按 **模型** 分解：成本、请求计数和令牌总数（输入/输出/缓存）。比 `get_usage` 更重；按需调用。 | | `login` | **回退** 浏览器登录 + 端点自动发现（仅在本地令牌路径无法使用时使用）。报告当前使用情况。 | | `logout` | 清除存储的 `login` 会话（cookie + 端点）。不影响本地令牌路径。 `forgetBrowser=true` 也会删除保存的浏览器配置文件。 | | `set_threshold` | 持久化阈值（0-100）。默认为 **0** = 只要有请求剩余就节省。被环境变量覆盖，如果设置。 | | `set_verbose` | 启用/禁用每条消息的使用情况页脚（持久化）。被环境变量覆盖，如果设置。 | | `set_followup` | 启用/禁用任务结束时“还有其他事情？”的跟进问题（持久化，默认为关闭）。 | | `check_update` | 强制对 GitHub 进行即时检查以获取新版本（绕过一天一次的限制），并报告如何更新。 | | `dismiss_update` | 记录用户已拒绝当前可用的更新，因此不会再次显示，直到出现新版本。 | | `status` | 显示活动的 **身份验证源**（`local-token` vs `login`）和本地令牌详细信息（state.vscdb 路径，teamId，令牌过期），是否存储了登录会话，捕获时间，以及存储/环境/有效阈值，详细模式和跟进设置。 | ## 调整节省模式何时开启 阈值是激活节省模式的最小 **使用百分比**： - `0` （默认）：只要有请求剩余就节省。 - `80`：仅当您已使用 ≥80% 的限制时才节省。 有两种设置方法， **环境变量优先** （如果两者都设置）： **1. 环境变量（推荐 - 在 `mcp.json` 中声明）：** ```json "cursor-usage": { "command": "npx", "args": ["-y", "cursor-usage-optimizer"], "env": { "CURSOR_USAGE_THRESHOLD_PCT": "80" } } ``` （对于本地克隆，请使用 `"command": "node", "args": ["/ABS/PATH/dist/index.js"]` 代替。） 更改数字并重新加载 MCP。接受 `0`–`100`。留作默认值（或删除）以获得默认始终节省行为。如果设置了 `CURSOR_USAGE_THRESHOLD_PCT`，它将 **覆盖** 任何通过以下工具设置的值。 ## 每条消息的详细模式（每条消息末尾的使用情况页脚） 在 `mcp.json` 的 `env` 中设置 `CURSOR_USAGE_VERBOSE` 为 `true`，让代理在每条消息末尾附加一个使用情况页脚： ```json "env": { "CURSOR_USAGE_VERBOSE": "true" } ``` 页脚格式（渲染为围栏代码块）： ``` Cursor Usage: 290/500 requests · $0.00/$75.00 (~任务开始时) ``` 您也可以在不编辑 `mcp.json` 的情况下，通过 **`set_verbose`** 工具随时切换它（持久保存在 `~/.cursor-usage` 中）。如果设置了 `CURSOR_USAGE_VERBOSE` 环境变量，它将 **覆盖** 工具值 - 从 `mcp.json` 中删除它，以纯粹通过 `set_verbose` 控制详细模式。 注意：数字反映从 **任务开始** 的读取（不是每条消息刷新），并且因为将页脚附加到每条消息是一个模型行为，所以它可能会偶尔被错过。默认为关闭。 ## 跟进模式（任务结束时的“还有其他事情吗？”问题） 独立于节省/详细模式。当开启时，`get_usage` 告诉代理以简短的 **跟进问题** 结束每个任务，通过 Cursor 的问题/选项 UI - 例如 “还有其他事情吗？”带有“否，我们已经完成”选项和一些开放式答案空间（当合适时更具体的问题）。因为回答该 UI 是免费的，所以您几乎总是会得到一个提示，您可以响应并让会话继续进行，而无需花费额外的请求来重新参与。 在 `mcp.json` 中通过环境变量启用： ```json "env": { "CURSOR_USAGE_FOLLOWUP": "true" } ``` 或者在运行时使用 **`set_followup`** 工具切换（持久保存在 `~/.cursor-usage`）。如果设置了 `CURSOR_USAGE_FOLLOWUP` 环境变量，它将 **覆盖** 工具值。 **默认为关闭**。 ## 阈值，继续 **2. `set_threshold` 工具（持久化在 `~/.cursor-usage`）：** ``` set_threshold { "activationThresholdPct": 80 } ``` 仅在环境变量未设置/为空时使用。运行 `status` 查看 `storedThresholdPct`、`envThresholdPct` 和生成的 `effectiveThresholdPct`。 ## 应用于现有聊天的更改 **新聊天** 会自动获取规则和 MCP - 无需执行任何操作。 对于一个 **已经打开** 的聊天，您安装/更新了此： 1. **重新加载 MCP 一次** （设置 → MCP → 切换 `cursor-usage` 关闭/开启）。这会重启共享服务器，因此每个聊天 - 包括打开的聊天 - 都可以在其下一个回合中看到最新的代码和工具。 2. **提示现有的聊天** 以便它立即开始表现（规则按回合读取，但显式提示保证它）： ``` 从现在开始遵循节省请求的规则：调用 cursor-usage get_usage 工具， 报告我的当前使用情况，如果节省开启 - 通过问题 UI 询问（不是开放式提示）， 批量处理问题，并且仅在选择无关紧要时默认静默。 如果详细模式开启，请在每条消息末尾添加页脚。 ``` ## 用量读取方式（查询时无需浏览器） `get_usage` **不会** 打开浏览器。它直接向仪表盘端点发出经过身份验证的请求（使用来自 [本地令牌](#身份验证) 的 cookie，或存储的 `login` cookie）： - **`/api/usage?user=<sub>`** → 请求次数（含 `gpt-4.numRequests` / `maxRequestUsage`），例如 `278/500`。 - **`/api/usage-summary`** → `membershipType`，`isUnlimited`，`limitType`，计划内花费（`individualUsage.plan.used`），以及按需花费（`individualUsage.onDemand`，美分 → 美元）。 - **`/api/dashboard/teams`**（团队账户）→ `requestQuotaPerSeat`。 - **`/api/dashboard/get-hard-limit`**（团队账户）→ 用户级 `$` 限额，用于上下文。 浏览器（Playwright）**仅在 `login` 回退时使用**。 节省决策基于 **包含请求百分比**（“X / 500”数字）。 **预算与团队上限。** 花费线报告您的 **实际** 按需预算，来自 `individualUsage.onDemand.limit`（对您具有权威性），以及团队范围内的默认用户级上限，来自 `get-hard-limit`（`hardLimitPerUser`）。这些通常匹配，但如果您的组织设置了用户级覆盖，则可能不同；如果它们不同，工具会标记出来。 **团队账户。** 对于团队计费账户，包含请求数学运算与 Cursor 仪表盘完全镜像：限制为 `500 × requestQuotaPerSeat`（从 `/api/dashboard/teams` 获取），使用计数来自计划内花费（`ceil(planUsedCents / 4)`），在花费为 `0` 或无法读取座位配额时回退到旧的 `gpt-4` 存储桶。个人账户直接使用旧的 `gpt-4` 存储桶。 `get_usage` 始终返回来自源的 **原始** JSON，因此如果某个字段看起来不对劲，您可以检查 `raw` 并调整 `parseLegacyBucket` / `computeIncludedRequests` / `parseSummary`，位于 `src/usage.ts` 中。 ## 发布（维护者） 发布到 npm 是通过 GitHub Actions（`.github/workflows/release.yml`）自动化的，由版本号触发： ```bash npm version patch # 升级 package.json + 创建 vX.Y.Z 标签（按需使用 minor/major） git push --follow-tags # 推送提交和标签 → CI 发布到 npm ``` 工作流运行 `npm ci && npm run build`，验证标签与 `package.json` 版本匹配，然后运行 `npm publish --access public`。 **身份验证 = npm 受信任发布（OIDC）— 无令牌/密钥。** 工作流使用 GitHub 的 OIDC 令牌（`id-token: write`）进行身份验证；自动生成出处。npmjs.com 的一次性设置： 软件包 → **设置 → 发布访问 → 受信任发布者 → GitHub Actions**，并输入： | 字段 | 值 | |-------|-------| | 组织或用户 | `udah1` | | 仓库 | `cursor-usage-mcp` | | 工作流文件名 | `release.yml` | | 环境 | *（留空)* | （工作流在 CI 中将 npm 升级到 `@latest`，因为受信任发布需要 npm ≥ 11.5.1。）