Bill Tracker

Bill Tracker Agent 插件

将你的 AI Agent 连接到 Bill Tracker。它是一款个人账单追踪工具，可通过 LINE 发送提醒。连接后，Agent 可以告诉你哪些账单即将到期或已逾期、记录付款、添加和编辑账单，并汇总你的支出，所有操作都通过你自己的 Bill Tracker 账户完成。

本仓库包含插件、连接器设置和 Agent 技能。它们都连接到同一个远程 MCP 服务：

https://bills.jirawat.dev/mcp

说明

Bill Tracker MCP 服务于 2026 年 10 月 20 日部署。公开元数据和 OAuth 登录挑战已通过部署冒烟测试。 Google 登录以及 21 项实时 OAuth/MCP 检查均已通过官方 JavaScript SDK 测试，其中包括账单写入、令牌刷新和撤销。用户还在浏览器中验证了 LINE 二维码登录，并成功进入账单明细。下方各客户端的配置仍需分别进行实时兼容性检查。

目录

• 本仓库包含什么
• 开始之前
• 登录、权限和隐私
• 选择你的客户端
• 安装
• 无头 Agent：个人访问令牌
• Agent 可以做什么
• 工具变更和弃用
• 故障排除
• 仓库结构
• 维护本仓库
• 许可证

本仓库包含什么

• 一个插件，捆绑 MCP 服务和 billing-tracker Agent 技能。可原生安装在 Claude Code、Codex 和 ChatGPT 桌面应用、Cursor、VS Code、GitHub Copilot CLI、Gemini CLI 以及 Antigravity CLI 中。
• 插件市场，让 Claude Code、GitHub Copilot CLI、VS Code 和 Codex 可以将本仓库添加为插件市场，并保持插件更新。
• 一个 server.json，供官方 MCP Registry 使用。
• 可复制粘贴的设置，适用于直接连接 MCP 服务的客户端：Claude 应用、ChatGPT、Windsurf、Cline、Zed 和仅支持 stdio 的客户端。
• 可移植的 Agent Skill，教 Agent 如何妥善使用账单工具：常见任务、破坏性更改前的确认，以及日期和泰铢金额的处理。

每项配置都将服务命名为 bills。

开始之前

• 一个 Bill Tracker 账户。 先在 Bill Tracker 使用 Google 或 LINE 登录以创建账户。
• 支持远程服务的 MCP 客户端。 服务使用 Streamable HTTP 传输和 OAuth 登录。下方列出的所有客户端都支持该方式；只能启动本地（stdio）服务的客户端可使用 mcp-remote bridge。
• 较新版本的客户端。 服务通过当前客户端使用的标准 initialize 握手，支持 MCP 协议修订版 2025-11-25（首选）和 2025-06-18。如果客户端在 initialize 中提供其他修订版，服务会以 2025-11-25 响应；客户端将自行决定是否可以继续。对于其他带有不受支持的 MCP-Protocol-Version 标头的请求，服务会返回错误 -32022。服务仅使用 Streamable HTTP，不支持旧版 HTTP+SSE 传输，因此仅支持 2025-03-26 或更早版本的客户端可能无法连接。

登录、权限与隐私

• 使用你自己的账户登录。 Agent 首次连接时，浏览器窗口会打开 Bill Tracker 网站。使用你在应用中使用的同一个 Google 或 LINE 账户登录，然后查看同意界面，其中会显示 Agent 的名称及其申请的权限。你不需要客户端 ID、密钥或 API 密钥：客户端会通过标准 MCP 授权（OAuth 2.1 with PKCE，通过 Client ID Metadata Documents 或 Dynamic Client Registration 注册客户端）自行发现登录流程。
• 你只能查看自己的账单。 每个请求都会以登录账户的身份执行。连接到你账户的 Agent 无法访问其他人的账单。
• 权限会逐步授予。 默认情况下，首次登录会申请 bills:read、bills:write 和 offline_access，后者允许客户端续期会话，无需再次通过浏览器登录。有些客户端（例如 Codex）会在一开始就申请所有已声明的权限。当 Agent 首次使用需要更多权限的工具时，服务端会申请相应权限，你的客户端会重新打开同意界面，或要求你重新登录服务。
• 删除账户始终需要单独批准。 登录时，任何客户端都无法申请 account:delete 权限。如果你要求 Agent 删除账户，它的首次尝试会被拒绝；随后你需要打开 设置 > 已连接的 AI Agent，并在最近一次登录后，通过该操作专属的同意界面批准删除。此权限会在原始登录时间加五分钟后过期；批准和代码交换不会重新计时。不会签发刷新令牌。
• 你可以断开任何 Agent。 在 Bill Tracker 中打开设置 > 已连接的 AI Agent，即可查看所有已连接的 Agent 和个人访问令牌，并撤销其中任意一项。在所有设备上退出 Bill Tracker 并不会断开 Agent；请在该页面撤销访问权限。
• 破坏性操作需要确认。 除非请求包含明确确认，否则服务端会拒绝删除账单、解除 LINE 关联或删除账户；随附的技能也会指示 Agent 先征求你的同意。
• 此代码仓库不存储数据或密钥。 其中仅包含配置和说明。你的 MCP 客户端会存储登录令牌，账单则保留在 Bill Tracker 中。

连接客户端前，请阅读服务的隐私政策和服务条款。

权限	允许 Agent 执行的操作
bills:read	列出、搜索和读取账单及摘要，包括 chat.run 的读取命令
bills:write	添加和编辑账单、记录付款、确认金额、安排付款
bills:delete	删除账单
reports:read	读取支出报告
account:read	导出你的所有数据
account:manage	让你在所有设备上退出登录、开启或关闭 LINE 提醒、解除 LINE 关联
account:delete	删除你的 Bill Tracker 账户。需在最近一次登录后单独批准；该权限会在该次登录后五分钟过期，且不提供刷新
line:read	查看是否已关联 LINE，以及提醒是否已开启
chat:read	解析 LINE 聊天机器人命令，但不执行命令或读取账单
chat:write	执行任何 LINE 聊天机器人命令，包括仅读取数据的命令；删除操作还需要 bills:delete
offline_access	保持登录状态：续期会话，无需再次通过浏览器登录

选择客户端

客户端	推荐设置	包含技能
Claude Code	从此市场安装插件	是
Claude apps（claude.ai、Claude Desktop、移动端）	自定义连接器	单独上传
ChatGPT（网页端的 Business、Enterprise 和 Edu）	创建为插件的自定义 MCP 服务	否
Codex（CLI、IDE 扩展、ChatGPT 桌面应用）	从此市场安装插件	是
Cursor	一键安装链接或本地插件	随插件提供
VS Code and GitHub Copilot	一键安装链接或从源代码安装插件	随插件提供
GitHub Copilot CLI	从此市场安装插件	是
Gemini CLI	扩展	是
Antigravity CLI	插件	是
Windsurf	mcp_config.json 条目	否
Cline	远程服务	否
Zed	context_servers 条目	否
仅支持 Stdio 的客户端	mcp-remote 桥接程序	否

任何支持 Agent Skills 的 Agent 都可以自行添加技能；请参阅 仅安装技能。每个客户端只使用一种设置：安装插件并 手动添加服务，会让每个工具都出现两次。

安装

Claude Code

安装插件即可同时添加 MCP 服务和技能。在 Claude Code 中：

/plugin marketplace add jirawatp/billing-tracker-agent-plugins
/plugin install billing-tracker@billing-tracker

或者在终端中运行：

claude plugin marketplace add jirawatp/billing-tracker-agent-plugins
claude plugin install billing-tracker@billing-tracker

然后运行 /reload-plugins（或重启 Claude Code），打开 /mcp，选择 plugin:billing-tracker:bills 并选择 Authenticate。

若要仅为所有项目添加服务：

claude mcp add --transport http --scope user bills https://bills.jirawat.dev/mcp
claude mcp login bills

在没有浏览器的机器上，claude mcp login bills --no-browser 会打印 登录 URL，并提示你粘贴重定向 URL。

如果之后某个工具报错“需要额外权限”，请打开 /mcp 并 重新验证服务，以批准额外权限。

Claude apps (claude.ai, Claude Desktop, mobile)

将 Bill Tracker 添加为自定义连接器。Free（一个自定义连接器）、Pro、Max、Team 和 Enterprise 套餐均提供自定义连接器；添加后，它们可在 claude.ai、Claude Desktop、Cowork 和移动应用中使用。

1. 前往 自定义 > 连接器，选择 + 添加，然后选择 添加自定义连接器。
2. 输入名称 Bill Tracker 和 URL https://bills.jirawat.dev/mcp， 然后选择 继续。
3. 在 身份验证 下，选择 立即登录。在 OAuth 客户端 下， 保持选中 使用 Claude 发布的身份（推荐）。将 请求标头 留空。
4. 选择 添加，然后在打开的窗口中使用 Google 或 LINE 登录。
5. 在聊天中，从 连接器 下的 + 菜单启用该连接器。

在 Team 和 Enterprise 套餐中，由 Owner 在组织设置中添加连接器， 然后每位成员连接自己的 Bill Tracker 账户。Claude 通过 Anthropic 的云端访问服务，而不是从你的计算机访问。

若还要添加技能，请在 设置 > 功能 中启用 代码执行和文件创建，创建一个包含 billing-tracker 文件夹的 ZIP，然后在 自定义 > 技能 中选择 + > 创建技能 > 上传技能 并上传：

git clone https://github.com/jirawatp/billing-tracker-agent-plugins
cd billing-tracker-agent-plugins/skills
zip -r billing-tracker.zip billing-tracker

ChatGPT

ChatGPT Business、Enterprise 和 Edu 可在网页端使用具备完整工具支持的自定义 MCP 服务。在 Business 中，只有工作区管理员和所有者可以添加；在 Enterprise 和 Edu 中，管理员及其授权的成员可以添加。Pro 账户只能连接具有读取和获取权限的自定义 MCP 服务，因此无法使用 Bill Tracker 中会更改数据的工具。

1. 在 ChatGPT 中打开 Plugins，选择 + 按钮，然后选择 Add custom MCP server。
2. 输入名称 Bill Tracker，并在 Connection 下输入 URL https://bills.jirawat.dev/mcp。
3. 选择 OAuth 进行身份验证。ChatGPT 会从服务发现登录设置，因此将客户端 ID 和密钥留空。
4. 查看风险警告，选择 I understand and want to continue，然后选择 Create as a plugin。
5. 查看发现的工具，安装插件，并在提示时使用 Google 或 LINE 登录。
6. 在新聊天中，输入 @ 并选择 Bill Tracker。

要与工作区共享，管理员或所有者需要发布插件。ChatGPT 会根据插件的权限，要求你确认写入操作。

Codex（CLI、IDE 扩展和 ChatGPT 桌面应用）

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用共用 ~/.codex/config.toml，因此只需设置一次。安装插件，它会添加 MCP 服务和技能：

codex plugin marketplace add jirawatp/billing-tracker-agent-plugins
codex plugin add billing-tracker@billing-tracker

添加市场后，你也可以从 ChatGPT 桌面应用的 Plugins 目录安装插件。

若只添加服务：

codex mcp add bills --url https://bills.jirawat.dev/mcp

此操作会将以下内容写入 ~/.codex/config.toml：

[mcp_servers.bills]
url = "https://bills.jirawat.dev/mcp"

使用 codex mcp login bills 登录（在远程计算机上添加 --no-browser），或在桌面应用或 IDE 扩展的 MCP 服务设置中，选择服务旁边的 Authenticate。Codex 会请求该服务声明的所有权限（账户删除权限除外，永远不会请求）。若要在保持登录状态的同时，只授予基本权限，请运行 codex mcp login bills --scopes bills:read,bills:write,offline_access。

Cursor

按钮会打开 Cursor 并要求你确认。以下是相同的 Cursor 深层链接：

cursor://anysphere.cursor-deeplink/mcp/install?name=bills&config=eyJ1cmwiOiJodHRwczovL2JpbGxzLmppcmF3YXQuZGV2L21jcCJ9

或者，将服务添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json （单个项目）：

{
  "mcpServers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

服务首次连接时，Cursor 会启动登录流程。你可以通过 Customize 管理服务或重新登录。

若要使用带有技能的插件：Cursor 可从 Cursor Marketplace 和团队市场安装插件。在 Bill Tracker 被列入其中之前，请将其作为本地插件加载，然后重启 Cursor 或运行 Developer: Reload Window：

git clone https://github.com/jirawatp/billing-tracker-agent-plugins ~/.cursor/plugins/local/billing-tracker

在 Teams 和 Enterprise 计划中，管理员必须允许导入本地插件。

VS Code 和 GitHub Copilot

或者在终端中运行：

code --add-mcp '{"name":"bills","type":"http","url":"https://bills.jirawat.dev/mcp"}'

也可以将其添加到工作区中的 .vscode/mcp.json，或添加到用户的 mcp.json （运行 MCP: Open User Configuration）：

{
  "servers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

服务器首次启动时，VS Code 会提示你登录。使用 MCP: List Servers 启动、停止服务器，或重新登录。

要使用包含技能的插件，请确保已开启 chat.plugins.enabled 设置，运行 Chat: Install Plugin From Source，并输入 https://github.com/jirawatp/billing-tracker-agent-plugins。若要通过市场接收更新，请将此仓库添加到 chat.plugins.marketplaces 设置，并在扩展视图中安装 Bill Tracker（搜索 @agentPlugins）：

{
  "chat.plugins.marketplaces": [
    "jirawatp/billing-tracker-agent-plugins"
  ]
}

GitHub Copilot CLI

安装插件，即可添加 MCP 服务和技能：

copilot plugin marketplace add jirawatp/billing-tracker-agent-plugins
copilot plugin install billing-tracker@billing-tracker

仅添加服务：

copilot mcp add --transport http bills https://bills.jirawat.dev/mcp

当服务显示 needs-auth 时，在 Copilot CLI 中运行 /mcp auth bills 并登录。VS Code 也会识别通过 Copilot CLI 添加的插件和服务。

Gemini CLI

Gemini CLI 现为 Gemini Code Assist 和 API 密钥用户提供服务；个人 Google 账户用户已于 2026 年 6 月转至 Antigravity CLI。安装扩展，即可添加 MCP 服务和技能：

gemini extensions install https://github.com/jirawatp/billing-tracker-agent-plugins

重启 Gemini CLI，然后运行 /mcp auth bills 登录。之后可使用 gemini extensions update billing-tracker 更新。

仅添加服务：

gemini mcp add --scope user --transport http bills https://bills.jirawat.dev/mcp

Antigravity CLI

安装插件，即可添加 MCP 服务和技能：

agy plugin install https://github.com/jirawatp/billing-tracker-agent-plugins

要登录，请运行 /mcp，选择 bills，选择 Authenticate，在浏览器中完成登录，然后将显示的代码粘贴回终端。

仅添加服务时，此操作会将 serverUrl 写入 ~/.gemini/config/mcp_config.json：

agy mcp add bills https://bills.jirawat.dev/mcp

如果已安装 Gemini CLI 扩展，运行 agy plugin import gemini 即可将其转换。

Windsurf

在 Cascade 的 MCP 菜单中选择 Open MCP config file（当前版本的文件路径为 ~/.config/devin/mcp_config.json，Windows 上为 %AppData%\devin\mcp_config.json；旧版本使用 ~/.codeium/windsurf/mcp_config.json），然后添加：

{
  "mcpServers": {
    "bills": {
      "serverUrl": "https://bills.jirawat.dev/mcp"
    }
  }
}

按下 MCP 面板中的刷新按钮。Cascade 首次使用该服务时会提示你登录。

Cline

在 Cline 面板中打开 MCP Servers，然后选择 Remote Servers 选项卡。输入名称 bills 和 URL https://bills.jirawat.dev/mcp，选择 Streamable HTTP，然后选择 Add Server。当 Cline 提示服务需要身份验证时，选择 Authenticate 并在浏览器中登录。

也可以直接编辑设置文件（在扩展中选择 Configure MCP Servers，或对于 Cline CLI 使用 ~/.cline/data/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "bills": {
      "type": "streamableHttp",
      "url": "https://bills.jirawat.dev/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

保留 "type": "streamableHttp"。如果没有此项，Cline 会使用此服务不支持的旧版 SSE 传输方式。

Zed

打开 Settings > AI > MCP Servers，选择 Add Server，然后选择 Add Remote Server。也可以将以下内容添加到设置文件中 （zed: open settings file）：

{
  "context_servers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

未配置 Authorization 标头时，Zed 会运行标准 MCP 登录流程。Zed 通过 ACP 运行的外部 Agent 不会共用此登录状态； 请直接在这些 Agent 中配置服务。

其他客户端（仅 stdio）

对于只能启动本地 MCP 服务的客户端，请运行 mcp-remote 作为桥接工具。它需要 Node.js，会打开浏览器进行登录，并将令牌保存在 ~/.mcp-auth 中。它会 原样传递客户端的协议握手，因此客户端本身仍需支持 MCP 2025-06-18 或更新版本。

{
  "mcpServers": {
    "bills": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://bills.jirawat.dev/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

这是大多数客户端使用的 mcpServers 格式，包括 Claude Desktop 的本地 claude_desktop_config.json（使用自定义连接器是更好的选择）。

仅使用 Skill

billing-tracker Skill 遵循 Agent Skills 规范，因此任何支持 Skill 的 Agent 都可以将其与上述任一服务设置搭配使用。使用 skills CLI：

npx skills add jirawatp/billing-tracker-agent-plugins

它会询问要为哪些 Agent 安装；添加 -g 可为当前用户安装，而不是当前项目。你也可以将 skills/billing-tracker 复制到 Agent 的 Skill 文件夹中。

无头 Agent：个人访问令牌

无法打开浏览器的脚本、CI 作业和 Agent 可以使用个人访问令牌，而不是 OAuth。

1. 在 Bill Tracker 中打开 设置 > 已连接的 AI Agent，然后选择创建个人访问令牌。为令牌命名，选择其权限和有效期，然后复制令牌。它只会显示一次。
2. 将其保存为密钥，例如保存到名为 BILL_TRACKER_TOKEN 的环境变量中。
3. 在每个请求中将其作为 bearer 令牌发送：

Authorization: Bearer <token>

服务会将个人访问令牌视为具有你所选权限的已登录会话。令牌会在你选择的日期过期；你可以在同一设置页面撤销或替换令牌。

Claude Code。 使用单引号可将 ${BILL_TRACKER_TOKEN} 保留为引用，供 Claude Code 连接时读取：

claude mcp add --transport http --scope user bills https://bills.jirawat.dev/mcp \
  --header 'Authorization: Bearer ${BILL_TRACKER_TOKEN}'

在 CI 中使用 claude -p 时，通过 --mcp-config 传入类似这样的文件：

{
  "mcpServers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${BILL_TRACKER_TOKEN}"
      }
    }
  }
}

Codex，配置位于 ~/.codex/config.toml（或使用 codex mcp add bills --url https://bills.jirawat.dev/mcp --bearer-token-env-var BILL_TRACKER_TOKEN）：

[mcp_servers.bills]
url = "https://bills.jirawat.dev/mcp"
bearer_token_env_var = "BILL_TRACKER_TOKEN"

Cursor，配置位于 mcp.json：

{
  "mcpServers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BILL_TRACKER_TOKEN}"
      }
    }
  }
}

VS Code，配置位于 .vscode/mcp.json。VS Code 会要求输入一次令牌，并将其安全存储：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bill-tracker-token",
      "description": "Bill Tracker personal access token",
      "password": true
    }
  ],
  "servers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bill-tracker-token}"
      }
    }
  }
}

GitHub Copilot CLI（使用单引号可保留变量引用）：

copilot mcp add --transport http --header 'Authorization: Bearer ${BILL_TRACKER_TOKEN}' bills https://bills.jirawat.dev/mcp

Gemini CLI 和 Antigravity CLI 会将令牌本身存储在其设置中：

gemini mcp add --scope user --transport http --header "Authorization: Bearer $BILL_TRACKER_TOKEN" bills https://bills.jirawat.dev/mcp
agy mcp add --header "Authorization: Bearer $BILL_TRACKER_TOKEN" bills https://bills.jirawat.dev/mcp

Windsurf 和 Cline 会在请求头中展开 ${env:...}：

{
  "mcpServers": {
    "bills": {
      "serverUrl": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BILL_TRACKER_TOKEN}"
      }
    }
  }
}

对于 Cline，请使用 Cline 部分中的 "type": "streamableHttp" 和 "url" 键，并搭配相同的 headers 块。

Zed 不会展开请求头中的变量，因此令牌需要直接写入设置文件：在 bills 条目中添加 "headers": { "Authorization": "Bearer <token>" }。

mcp-remote。 为避免令牌出现在进程列表中，请将请求头放入文件（一行 Name: value，例如 Authorization: Bearer <token>），并通过 --header-file 传入：

{
  "mcpServers": {
    "bills": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://bills.jirawat.dev/mcp",
        "--transport",
        "http-only",
        "--header-file",
        "/path/to/bill-tracker-headers.txt"
      ]
    }
  }
}

你的 Agent 可以做什么

该服务提供 30 个工具、3 个资源和 1 个提示词。每个工具都需要上述权限之一。删除账单、解除 LINE 关联以及删除账户，只有在请求中明确确认后才会执行（不会删除任何内容的批量删除试运行不需要确认）；删除账户还需要上述单独审批，而 Skill 会在将你从所有位置登出前征求你的同意。

账单日期

写入账单时，日期必须采用精确的 YYYY-MM-DD 格式。2400 至 2699 年（含）会按佛历处理：服务器会先减去 543，再检查所得的公历日期。例如，2569-10-20 会存储为 2026-10-20，而 2567-02-29 会存储为有效的闰日 2024-02-29。由于 2023-02-29 不存在，因此 2566-02-29 会被拒绝。此范围以外的年份保持不变，因此该范围也特意涵盖了那些可能被误认为遥远公历年份的日期。

此规则仅适用于通过应用、LINE/聊天、CSV 导入或 MCP 写入的账单日期字段（dueDate、paidDate、scheduleDate、nextStatementDate）。查询和报告日期仍使用公历。时间戳和现有历史记录不会转换；如果更新时某个旧值完全未变，则会保留该值。

账单

工具	功能	权限
bills.list	按类别列出账单：全部、未结清、逾期、即将到期、未确认、最高优先级、已支付或本月账单。每次最多返回 500 条，并说明是否还有更多	bills:read
bills.get	按 ID 或简短引用获取一笔账单	bills:read
bills.query	按状态、到期日期、类别、付款方式和标记筛选账单	bills:read
bills.search	搜索账单名称和备注	bills:read
bills.recentlyChanged	获取过去 N 天内有变动的账单	bills:read
bills.byRef	将 LINE 聊天机器人提供的简短引用转换为账单	bills:read
bills.create	添加账单	bills:write
bills.update	修改账单	bills:write
bills.markPaid	将账单标记为已全额支付	bills:write
bills.recordPayment	记录部分付款	bills:write
bills.setAmount	设置金额并标记为已确认	bills:write
bills.confirm	确认预估金额	bills:write
bills.schedule	将账单标记为已安排在指定日期付款	bills:write
bills.toggleTopPriority	将账单置顶为最高优先级或取消置顶	bills:write
bills.delete	删除账单（具有破坏性）	bills:delete
bills.bulkDelete	删除最多 500 笔账单；试运行会预览结果但不会删除（具有破坏性）	bills:delete

汇总和报告

工具	功能	权限
summary.kpis	逾期数量、未支付总额、未来 7 天内到期的账单、最高优先级账单数量	bills:read
summary.month	本月已支付金额和平均未支付金额	bills:read
summary.chatbot	以数据形式返回 LINE 聊天机器人的汇总	bills:read
reports.spend	按 3、6 或 12 个月生成月度支出报告	reports:read
reports.spendDigest	一段式支出摘要	reports:read
reports.paidMonthlyAverage	过去 N 个月的月均已支付金额	reports:read

账户、LINE 和聊天

工具	功能	权限
account.export	导出你的所有数据	account:read
account.delete	删除你的账户及其所有数据（具有破坏性；需要单独审批）	account:delete
account.revokeSessions	让你在所有设备上退出 Bill Tracker（具有破坏性）	account:manage
lineLink.status	查看是否已关联 LINE，以及每日提醒是否开启	line:read
lineLink.setNotifyEnabled	开启或关闭 LINE 每日提醒	account:manage
lineLink.unlink	取消关联你的 LINE 账户；账单会保留（具有破坏性）	account:manage
chat.parseCommand	解析泰语或英语 LINE 聊天机器人命令，但不执行命令	chat:read
chat.run	执行 LINE 聊天机器人命令；更改数据的命令需要确认	bills:read 或 chat:write（用于读取命令）；chat:write（用于更改）；删除还需要 bills:delete

chat.run 的读取命令包括 help、list、due、overdue、 unconfirmed 和 summary，以及它们支持的泰语别名。现有的 chat:write 令牌无需 bills:read 即可运行这些命令。chat:read 权限 仅通过 chat.parseCommand 解析命令，不授予任何财务数据访问权限。该工具保留了 其破坏性注释，因此客户端仍可能在执行读取命令前请求确认。

资源和提示词

名称	说明
bill://<id>	一笔账单的 JSON 数据
summary://today	今日摘要
report://spend/<yyyy-mm>	截止该月的期间支出报告
summarize-month 提示词	汇总某个月的支出；month 的格式为 YYYY-MM

工具调用失败时

工具调用失败时会返回一个标记为 isError: true 的工具结果，其中 structuredContent.error 包含一个稳定的代码，Agent 可以据此了解出错原因 并进行修正。例如：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "No bill with that id."
    }
  ],
  "structuredContent": {
    "error": {
      "code": 1001,
      "kind": "not-found",
      "message": "No bill with that id."
    }
  }
}

代码	类型	含义
-32602	invalid-params	参数与工具的输入架构不匹配
1001	not-found	没有这笔账单，或账单属于其他账户
1002	invalid-bill	账单值未通过验证，例如计划账单缺少计划日期
1003	forbidden	数据属于其他账户
1004	confirm-required	发起破坏性调用时未提供确认
1005	rate-limited	短时间内请求过多
1006	upstream-firestore	Bill Tracker 的数据库暂时出现问题
1007	insufficient-scope	需要你尚未授予的权限

协议级错误则以 JSON-RPC 错误的形式返回：-32602 表示服务没有该工具名称， -32603 表示内部错误（其消息中包含简短的参考信息），-32022 表示不支持的协议版本。

工具变更和弃用

由于一些宿主（包括 ChatGPT）会一直调用添加插件时看到的工具列表，直到管理员刷新列表， 因此服务将其工具视为有版本管理的公共契约。

• 新工具、新的可选输入、新的可选输出字段和新的错误代码都可能随时出现。现有配置仍可正常使用。
• 工具不会原地重命名、移除或变得更严格。服务会在旧工具旁添加新工具，为旧工具标注弃用通知，并且仅会在此处公布弃用信息并经过完整弃用期后将其移除。

当前弃用项：无。今后如有弃用，会在此处列出弃用工具、替代工具和移除日期。

故障排除

登录窗口未打开。 将登录 URL 从客户端复制到浏览器中。在远程计算机上，使用 claude mcp login bills --no-browser 或 codex mcp login bills --no-browser，然后粘贴重定向 URL。Gemini CLI 登录需要使用本地浏览器；请改用 个人访问令牌。

服务显示“needs authentication”或 401 Unauthorized。 重新登录： 在 Claude Code 中使用 /mcp，在 Codex 中使用 codex mcp login bills，在 Gemini CLI 或 Copilot CLI 中使用 /mcp auth bills，或者在 Cline 和 Antigravity 中选择身份验证。你的会话可能已过期，或已在“已连接的 AI Agent”中被撤销。使用个人访问 令牌时，请检查标头是否准确写为 Authorization: Bearer <token>，且没有 引号或尾随空格；令牌尚未过期；并且客户端启动时环境变量已设置。

工具调用失败，报错为 insufficient_scope、错误 1007 或“needs additional permissions”。 Agent 需要你尚未授予的权限。客户端提示时请批准，或者重新登录服务；在 Claude Code 中，打开 /mcp 并重新验证服务。使用个人访问令牌时，请创建包含该权限的新令牌。如果缺少的权限是 account:delete，请改在“已连接的 AI Agent”页面批准；客户端无法在登录期间请求此权限。

你大约每小时就得重新登录一次。 客户端未请求 offline_access，因此无法续订会话。请重新登录服务；使用 Codex 时，请在 --scopes 中加入 offline_access。

Claude Code 报告某个服务有“url”但没有“type”。 在服务条目中添加 "type": "http"。

Cline 连接失败或退回到 SSE。 在服务条目中设置 "type": "streamableHttp"。

在浏览器中打开服务 URL 时显示 405 Method Not Allowed。 这是预期行为。 此端点只接受通过 POST 发送的 MCP 请求。

客户端报告协议版本不受支持（-32022）或无法初始化。 服务支持 MCP 2025-11-25 和 2025-06-18。如果 initialize 提供其他修订版本，服务会以 2025-11-25 响应；客户端会自行决定是否能够继续。错误 -32022 表示请求使用了不受支持的 MCP-Protocol-Version 标头。如果客户端无法使用受支持的修订版本，请更新客户端。仅支持 2025-03-26 或更早版本的客户端可能无法连接； mcp-remote 会原样转发客户端自身的握手。

Agent 报告错误 -32603，并附有简短的参考编号。 这是服务内部错误，不是你的配置有问题。请稍后重试；如果问题持续出现，请在此存储库中提交 issue，并附上该参考编号。

工具缺失或不是最新版本。 服务不会推送工具列表变更，因此请重启客户端或刷新服务：在 VS Code 中使用 MCP: Reset Cached Tools，或点击 Windsurf 中的刷新按钮。ChatGPT 会保留创建插件时的工具快照。现有工具仍可正常工作（请参阅 工具变更和弃用）；工作区管理员可在插件设置中刷新快照，以获取新工具。

每个工具都出现了两次。 你安装了插件，同时又手动添加了服务。请移除其中一个。

Zed 将 ${MY_TOKEN} 按原样发送。 Zed 不会在标头中展开环境变量。请直接粘贴令牌，或者移除标头并使用 OAuth。

登录失败，提示客户端注册或重定向错误。 移除你填写的任何 OAuth 客户端 ID 或密钥，例如连接器的高级设置中的相关内容，让客户端自行注册，然后重试。

Antigravity 登录成功，但工具调用仍返回 401。 请更新 agy；早期版本不会在 MCP 请求中发送 OAuth 令牌。作为临时解决方法，请使用个人访问令牌添加服务。 重新开始。 移除该服务或插件，清除其已保存的登录信息（在 Claude Code 中打开 /mcp 并选择 Clear authentication；运行 codex mcp logout bills；对于 mcp-remote，删除 ~/.mcp-auth），在 Connected AI agents 下撤销旧连接，然后重新设置。

自行检查服务。 没有令牌时，服务应返回 401 Unauthorized，并带有一个以 WWW-Authenticate: Bearer resource_metadata="..." 开头的标头，用于启动登录发现：

curl -i -X POST https://bills.jirawat.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

使用个人访问令牌时，服务应列出工具。该服务是无状态的，因此只需发送一个带有协议版本标头的请求即可：

curl -sS https://bills.jirawat.dev/mcp \
  -H "Authorization: Bearer $BILL_TRACKER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

如需交互式检查，请运行 npx @modelcontextprotocol/inspector，选择 Streamable HTTP 传输，并连接到 https://bills.jirawat.dev/mcp。

仓库布局

.
├── .agents/plugins/marketplace.json  Codex and ChatGPT desktop marketplace
├── .claude-plugin/
│   ├── marketplace.json              Claude Code marketplace (also read by Copilot CLI and VS Code)
│   └── plugin.json                   Claude Code plugin manifest
├── .github/workflows/
│   ├── ci.yml                        Validation and link checks
│   └── publish-mcp-registry.yml      Manual publish to the MCP Registry
├── .mcp.json                         MCP server for the Claude Code plugin
├── config.json                       Server URL, app URL, repository and version
├── gemini-extension.json             Gemini CLI extension manifest
├── lychee.toml                       Link checker settings
├── mcp.json                          MCP server for the Agent Plugins format
├── mcp_config.json                   MCP server for Antigravity CLI
├── plugin.json                       Agent Plugins manifest (Codex, Cursor, VS Code, Copilot CLI, Antigravity CLI)
├── scripts/
│   ├── sync.mjs                      Copies config.json values into every file
│   └── validate.mjs                  Offline checks, run locally and in CI
├── server.json                       Official MCP Registry entry
└── skills/billing-tracker/
    ├── SKILL.md                      The agent skill
    └── references/tools.md           All 30 tools with permissions and inputs

维护此仓库

更改服务 URL、仓库或版本

多个文件中重复出现的值（服务 URL、托管 Connected AI agents 的应用 URL、仓库和版本）仅保存在 config.json 中。在那里修改后，运行：

node scripts/sync.mjs
node scripts/validate.mjs

sync.mjs 会重写所有重复使用这些值的清单和文档，包括一键安装链接。你也可以直接传入新值，例如 node scripts/sync.mjs --server-url https://example.com/mcp。这些脚本需要 Node.js 18 或更高版本，且无需安装软件包；TOML 检查还需要 Python 3.11 或更高版本。

持续集成

.github/workflows/ci.yml 会在每次推送和拉取请求时运行，并每周检查链接。它会检查每个文件是否与 config.json 一致，运行 scripts/validate.mjs（JSON 格式、TOML、文档中的代码块、技能和工具名称规则、写作风格），根据已发布的 JSON Schema 验证清单，运行 claude plugin validate --strict、 gemini extensions validate 和 Agent Skills 参考验证器，并使用 lychee 检查每个链接。

发布到 MCP Registry

server.json 将此服务描述为 官方 MCP Registry 中的 io.github.jirawatp/billing-tracker；发布过程会通过 GitHub 证明你拥有该命名空间。服务上线后，可从 Actions 标签页运行 Publish to MCP Registry 工作流，或使用 mcp-publisher 在终端中发布：

mcp-publisher login github
mcp-publisher publish

Registry 不接受已存在的版本，因此请先提升版本号。

发布新版本

1. 在 config.json 中设置新的 version，然后运行 node scripts/sync.mjs。
2. 提交更改，然后为该提交创建 vX.Y.Z 标签并推送该标签。

对于按版本缓存插件的客户端，例如 Claude Code、Codex 和 VS Code，版本更改后便会获取更新。

使技能与服务保持同步

skills/billing-tracker 中的工具名称、资源和提示词遵循服务的集成约定，该约定也列在 scripts/validate.mjs 中。服务新增工具时，请将其添加到该列表、references/tools.md、相关的 SKILL.md 内容以及本 README 的工具表格中。服务弃用工具时，请保留旧工具的记录，添加替代工具，并在整个弃用期内将其记录在 工具变更与弃用 中；服务只会在弃用期结束后移除旧工具，届时也应将其从此处的所有列表中移除。验证器会检查参考表和本 README 是否涵盖所有约定工具，并确保没有文档列出约定之外的工具、资源或提示词。

许可证

MIT