MCP 工具参考

查阅 MCP 工具的用途和主要参数；编写调用或排查助手操作时使用本页。

Calends 的 MCP 服务器提供 27 个工具：14 个读取类，13 个写入类。只读令牌只能看到和调用读取类工具。接入方法见 MCP 接入。

通用约定

• 日期一律是 YYYY-MM-DD 字符串。
• subscription 可以是订阅 id，也可以是名称（模糊匹配）；匹配到多个时返回候选，让助手用 id 再试。
• method 可以是支付方式 id 或名称。
• currency_out 把金额换成指定币种，缺省为本位币。
• period 时间范围：today、next_3_days、next_7_days、next_30_days、this_month、next_month、last_30_days、this_year、custom（需要 from、to）。
• cycle 计费周期，比如 {"unit":"month","every":1}；unit 可选 day、week、month、year、lifetime（买断）。
• scope：mine 不含代付，合租只算我的份额；gross 是卡上的全额，含代付；proxy 只看代付。
• dry_run：所有写入类工具都支持。传 true 只返回预览不保存；不传或 false 时保存，并返回保存后的订阅和接下来几笔扣款。
• 参数错误、找不到订阅这类问题作为工具结果返回（isError），助手能看到原因并改正。

读取类

工具	用途	主要参数
get_overview	账本快照：今天、本位币、每月成本（不含代付，合租只算我的份额）、计费中的数量、支付方式（含 id）、在用的分类和地区、最重要的体检提示。建议第一个调用。	currency_out
list_categories	按显示顺序列出分类：名称、图标、颜色、内置代码，以及有多少订阅在用（全部 / 在用）。	无
list_subscriptions	列出订阅：状态、当前价格、每月成本、下次与上次扣款、支付方式、地区。	query（模糊匹配名称、标签、备注、分类）、status（active、trial、paused、ending、ended、upcoming、lifetime、live、all；live = 计费中 + 试用 + 到期不续 + 暂停）、kind（mine、share_owner、share_member、proxy、all）、category、method、region、sort（next_charge、monthly_cost、name、start）、limit（缺省 100）
get_subscription	一个订阅的全部细节：每个阶段（换区、换套餐、断更）、价格历史、首期优惠与赠送时长、最近和接下来的扣款、合租成员的应收、代付还款、累计花费。	subscription（必填）、months_back（缺省 12）、months_forward（缺省 6）、currency_out
list_charges	某个时间范围内的扣款（实际与预测）。	period（缺省 next_30_days）、from、to、scope（缺省 mine）、subscription、method、include_projected（缺省 true）、currency_out
spending_stats	按月、年、分类、支付方式、币种、地区或订阅汇总支出。现金口径：每笔已发生的扣款按当天汇率。	period（缺省 this_year）、from、to、group_by（缺省 category）、scope、include_projected、top（缺省 30）、currency_out
get_trends	时间序列：每月 MRR 走势、按月的现金与权责、或两个日期之间的 MRR 变动（新增、涨价、降价、退订、汇率影响）。	metric（mrr、cash_vs_accrual、movement）、months_back（缺省 12）、months_forward（缺省 3，仅 cash_vs_accrual）、from、to（仅 movement）
list_payment_methods	支付方式：当前估算余额、每月消耗、续航（能撑多久、第一次不够是哪一笔）和充值建议。	topup_months（缺省 6）
list_people	人员名册：联系方式、参与的合租和代付、现在欠多少、累计付过多少、最近一次付款。	query、owing_only
get_receivables	别人欠我的钱：按人汇总，合租里到期或逾期的成员，代付里还没还的扣款。	kind（share、proxy、all）、currency_out
get_insights	体检与报告。	section（insights 体检、year_review 年度回顾、prepaid 预付余值、cancel_savings 退订省下的钱）、year（仅 year_review）
list_events	花钱决定的变更日志：开始、结束、暂停、续订、调价、换区换套餐，以及各自对每月成本的影响。	since、until、subscription、limit（缺省 50）
search_app_store	按名称或 App Store 链接查应用：名称、图标地址、商店地址、开发者、类别。用来给新订阅补图标和网址。	query（必填）、country（两位商店区域代码，缺省 us）
get_carpool	合租：我发起或加入的每个合租的席位（已用 / 总数 / 空位）、成员的收费标准、已付至和欠款；一年的成本、成员应交、我还要付多少或赚多少；发起至今的付出、收回和结果。	subscription（可选，只看这一个）

写入类

工具	用途	主要参数
create_subscription	新建订阅。price 是每期价格。同名且同一开始日的订阅已存在时拒绝，除非 force=true。	name、price、currency、cycle（以上必填）、start（缺省今天）、category（尽量用 list_categories 里的名字；新名字会新建分类）、tags、method、region、url、icon、notes、account、status（active 或 trial）、trial_end、end、intro（{price, until}）、payments（可选完整历史：每笔 {date, amount, note?}，包含所有账期，日期须在 start 至今天之间；未来按 price 推算）、force
update_subscription	修改描述性字段和设置，只改传了的键。调价用 change_price，换区换套餐用 change_plan。	subscription、set：name、category、tags、url、manage_url、notes、account、method、region、remind_days（-1 不提醒）、end（null 清除）、next_due、trial_end、expires
change_price	在当前方案里记一次调价，从某天起生效；之前的扣款保留原价。	subscription、amount、from（缺省今天）
change_plan	开始同一个订阅的新阶段。	subscription、action、at、plan（price、currency、cycle 必填，可选 method、region、note、planned）、keep_previous_until、earlier_until
set_status	暂停（停止推算扣款）、退订（某天起不再续费）或恢复（清除暂停和结束日）。	subscription、action（pause、cancel、reactivate）、at（缺省今天；退订时从这天起不再续费）
record_payment	记一笔实际扣款、退款（填正数，保存为负）、补差或扣款失败，用订阅的币种。同一天同金额的重复记录会被拒绝，除非 allow_duplicate。	subscription、amount（必填）、date（缺省今天）、kind（charge、refund、adjust、failed）、settled（{amount, currency}，卡上实扣）、note、allow_duplicate、phase（两段并行时指定记在哪一段，填那段的开始日）
delete_payment	按日期删除一笔扣款记录。	subscription、date、index（同一天有多笔时的序号，从 0 开始）、phase
delete_subscription	删除订阅和它的全部历史，不可撤销。助手应先 dry_run 预览，由你确认。	subscription
set_share	设为合租或修改合租。	subscription、role（owner 我发起、member 我加入、none 取消合租）、seats（总席位，含我）、owner_name（我加入时的发起人）、since（发起日）、collect_from（统一收款起点）
save_share_member	给我发起的合租添加成员，或修改成员（传 member）。	subscription、member、name、fee（每次收多少）、fee_currency（缺省为合租收款币种）、bill_every（1、3、6、12 个月）、exempt（不分摊）、paid_until、joined、left、contact_via、contact、account、note、first_period（prorate 默认按天、full 整期、free 免费）、first_amount（首期覆盖金额，null 恢复计算）
remove_share_member	把成员彻底移出合租，收款记录一起删除。想保留历史请用 save_share_member 设 left。	subscription、member
record_receivable	记合租收款（kind=share）或代付还款（kind=proxy）。合租默认最早未付区间及金额；代付须传金额。可只传 person 定位唯一待收项目。	subscription、person、kind、member、charge、amount、currency、date（收到日，默认今天）、from、until（合租覆盖期，含两端）、note
update_payment_method	修改支付方式：校准当前余额、记一笔充值（可附实际花费，比如用人民币买的礼品卡）、改名称或地区。	method（必填）、balance、top_up（{amount, date, cost, cost_currency, note}）、name、region

合租收款

set_share 接受 collect_from，预览和保存都返回实际使用的起点。省略时保留已设覆盖值，或依次从发起日、历史覆盖期/已付至、订阅开始日推断。成员按该起点加自己的收费月数对齐，并保留月末规律。

save_share_member 的 first_period 可选 prorate（默认，按含两端的实际天数折算并取到分）、full、free。first_amount 可覆盖非免费首期金额，币种为 fee_currency；传 null 恢复计算，之后使用常规收费。新成员默认今天加入。见统一收款日与中途加入。

合租收款可省略 from、until 和 amount：record_receivable 使用最早未付区间、对齐周期末日和建议金额，并跳过免费首期。迟收款也保留旧欠期起点。显式金额（含零）按实收保存，所选覆盖期视为已付，不追踪差额欠款；已付至不会倒退。显式金额省略 currency 时沿用合租收款币种；推算金额默认收费币种，指定其他币种时按收到日汇率转换。缺失汇率会报错，不会记零。代付还款仍须传金额。

成员预览和保存返回 collect_from、paid_until、first_collection 与 next_collection（含两端的覆盖期和金额）、next_collection_date、is_first_period、pending_amount。record_receivable 还返回实收记录；get_carpool 带出同样的摘要、收费与首期设置。下次收款日可能已逾期，待收金额包含截至今天的旧欠期。所有写工具保留 dry_run，内置助手仍须确认草稿后才写入。

change_plan 的几种 action

action	作用
switch	从 at 起换区、换套餐、换币种或换支付方式。默认无缝切换；给了 keep_previous_until，上一阶段继续跑到那天，两段并行、都照常计费（比如新开了土耳其区，美区的预付还没用完）。plan.planned=true 表示只是计划。
resume	断更后在 at 重新订阅，中间的空档记为断更。
earlier	在订阅开始之前补一段历史（比如先买断、后来才改订阅），at 是那一段的开始日；缺省一直用到原来第一段开始，给了 earlier_until 则在那天结束，中间算断更。
confirm	确认一个计划中的阶段，at 为它的开始日。
drop	取消一个计划中的阶段，上一阶段在原定的切换日结束。

退订（set_status 的 cancel）会同时取消退订日之后排好的阶段，包括计划中的换套餐。

示例

「Netflix 从今天起涨到 17.99 美元」，助手大致会这样调用：

{ "name": "change_price", "arguments": { "subscription": "Netflix", "amount": 17.99, "dry_run": true } }

确认预览无误后，再去掉 dry_run 调用一次。