crowntowncompost-mcp

crowntowncompost-mcp

Crown Town Compost 客户门户的 MCP 服务 — 用自然语言查询上门收集服务、发票和即将到来的收集日期，跳过一次服务、报告漏收，并更新账户。

由 AI（Claude Code）开发和维护。使用风险请自行承担。

连接对象

crowntowncompost.com 是一个营销网站，不含客户数据。所有数据都位于 portal.crowntowncompost.com，这是一个 Django 应用（白标 StopSuite 清运服务平台）。 此服务会在服务器端使用你已有的会话 Cookie，或使用你自己的门户用户名和密码进行身份验证；普通表单登录会返回一个会话 Cookie。随后，它会读取网站所使用的相同页面和 JSON 端点。 无需浏览器扩展，无需绕过机器人防护墙，也没有第三方服务介入。

安装

npm install -g crowntowncompost-mcp

然后将其添加到你的 MCP 主机。以下两种配置均可使用 — 提供你已有的会话 Cookie（无需其他信息），或提供登录凭据，以便服务创建会话 Cookie：

{
  "mcpServers": {
    "crowntowncompost": {
      "command": "npx",
      "args": ["-y", "crowntowncompost-mcp"],
      "env": {
        "CROWNTOWN_USERNAME": "[email protected]",
        "CROWNTOWN_PASSWORD": "your-portal-password"
      }
    }
  }
}

若要改用会话 Cookie，请将 CROWNTOWN_SESSION_COOKIE 设置为已登录浏览器会话中的 Cookie 标头值（sessionid=…; csrftoken=…），并将用户名和密码留空。此时不会运行门户登录流程，也不会在任何地方存储密码。

同时设置两者也是有效的，而且是最稳健的配置：服务会优先使用 Cookie；当门户最终使其过期时，登录流程会静默创建替代 Cookie。如果只设置 Cookie，会话过期时系统会报告会话已过期 — 服务会明确告知，而不会声称未配置任何内容。

在本地，你也可以将 .env.example 复制为 .env。服务可以在没有凭据的情况下启动（以便通过主机的安装时探测）；配置错误会在首次调用工具时显示。

工具

读取

工具	返回内容
crowntown_healthcheck	凭据是否有效，以及账户状态；失败时，error.kind 会指出哪个环节出错（no_credential、credential_rejected、session_expired、edge_blocked、timeout、transport、http）
crowntown_get_dashboard	账户状态、订阅（套餐、价格、续订日期）、下次服务日期、服务地址和收集日期，以及你的环境影响
crowntown_get_account	联系方式和通知偏好设置
crowntown_get_pickup_schedule	每个地址的收集日期和时间范围 — 官方规定的摆放截止时间，以及根据你的收集历史推算的实际到达时间范围（最早／最晚／通常时间，时间是否稳定或有变化）
crowntown_list_service_history	过去的收集记录 — 日期、结果、时间、重量、服务。支持分页；可按 success／missing／empty／inaccessible／unacceptable 筛选
crowntown_list_upcoming_services	即将到来的收集日期，每个日期都包含跳过该次服务所需的 ID
crowntown_list_invoices	账单历史，包含金额、状态和 Stripe 付款链接

写入操作（均需确认）

工具	功能
crowntown_skip_service	跳过或取消跳过即将到来的收集日
crowntown_update_account	更新联系信息／通知偏好设置
crowntown_report_missed_pickup	报告漏收情况
crowntown_contact_support	向客户支持发送消息

每个会修改数据的工具都会在写入前要求你确认。能够显示确认提示的客户端（Claude Code）会显示该提示（除非 MCP_CONFIRM_ELICITATION=off）。在其他环境（claude.ai、Claude Desktop）中，首次调用不会发送任何内容，而是返回 status: "confirmation-required"，其中包含待发送内容的准确预览以及 confirmToken；只有使用相同参数和该令牌再次调用才会继续操作。令牌只能使用一次，会过期；如果待发送内容在此期间发生变化（包括工具预先读取的值，例如 crowntown_update_account 重新保存的账户表单内容，或支持表单预填的回复邮箱／电话），则会拒绝操作（DRAFT_CHANGED）。对于可以通过重新读取来确认变更已生效的操作（跳过收集日、更新账户），工具会重新读取并报告 verified；对于无法确认的操作（支持消息、漏收报告），工具会如实说明，而不会声称操作成功。

确认设置

变量	默认值
MCP_CONFIRM_MODE	ask-user	对于无法显示确认提示的客户端（claude.ai、Claude Desktop），写入操作的处理方式。ask-user：分两步操作——首次调用不执行任何操作，并返回预览和令牌；模型必须先在聊天中获得你的批准，再使用该令牌再次调用。auto：同样分两步，但模型审阅预览后可以自行使用令牌。refuse：在此类客户端上拒绝写入操作。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示永不显示确认提示，因此每个客户端都会采用 MCP_CONFIRM_MODE 的处理方式。对于声称能够显示提示、但实际上从不显示的客户端（写入操作会挂起——opencode 2.0.x），请设置此项。其他任何值都按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌需要在服务重启后继续有效时才设置。

支付操作有意不在支持范围内——crowntown_list_invoices 会返回托管发票的 URL，供你在浏览器中打开。

不使用 MCP

skills/crowntown-portal 技能可在 shell 中使用 curl 完成相同操作，适用于脚本，或未安装此服务的机器。它记录了 Django CSRF 握手、两个 JSON 端点以及每项写入操作的字段列表。

开发

npm install
npm run build
npm test

测试会模拟网络，无需凭据，也不会访问线上门户。tests/server-boot.test.ts 会启动实际构建产物（npm bin 和 bundle，后者不含 node_modules），并与它们执行 MCP 握手。

端点结构记录在 docs/CROWNTOWN-API.md 中，其中说明了哪些部分已通过线上验证，哪些尚未验证。

许可证

MIT