excalibur-mcp

eXcalibur MCP

通过 AI Agent 将精美推文闪电般发布到 X（Twitter），并通过 DPYC(TM) 收费站协议，以 Bitcoin Lightning 微支付实现变现。

eXcalibur 是一个 FastMCP 服务，可让 AI Agent 使用丰富的 Unicode 格式和可选图片在 X（Twitter）上发帖。 X 的 Patron 身份验证使用 OAuth2 Authorization Code + PKCE——聊天中不会出现 凭据。运营方凭据（X 应用密钥、BTCPay）通过人工介入的 Secure Courier 交付， 并存储在运营方专属的 Neon Vault 架构中。工具调用通过 Tollbooth DPYC(TM) 预充值的 Lightning 余额计量——别打扰客户。

属于 DPYC(TM) Social Contract 的一部分。

开始使用

通过 Horizon 连接——无需本地安装：

https://excalibur-mcp.fastmcp.app/mcp

https://excalibur.tollbooth-dpyc.com 上的网页编辑器也可在浏览器中调用相同的工具。

第 1 步：检查会话

调用 excalibur_session_status 查看当前会话状态。如果你有一个已充值的活跃会话，就可以发帖了。

第 2 步：在连接上证明你的 Npub

身份信息绑定在连接上，而不是工具参数中。从 AI 助手连接时，这是一个 OAuth 持有者连接：调用 excalibur_request_npub_proof(patron_npub=<npub>)，回复它发送的 Nostr 私信，然后调用 excalibur_receive_npub_proof(patron_npub=<npub>, nonce=<nonce>) 一次。此后，在你于回复中选择的有效期内（最长 30 天），连接都会持有你的 npub，且每次工具调用只会传递 npub。持有 nsec 的调用方也可以改为对每个 HTTP 请求进行签名（NIP-98）。

第 3 步：X OAuth2 + PKCE（X 的 Patron 凭据）

1. 获取你的 Nostr npub——使用 dpyc-oracle 的 how_to_join() 工具，或任意 Nostr 客户端。
2. 调用 excalibur_begin_oauth(npub=<npub>)——它会返回一个 authorize_url。 在浏览器中打开主 authorize_url（而非短链接），并在 X 上授权该应用。
3. 调用 excalibur_check_oauth_status(npub=<npub>)——完成代码交换，将令牌存入 Vault，并激活你的会话。

会话以 npub 为键。令牌存储在 Neon Vault 中，并会在过期时自动刷新。

第 4 步：Secure Courier（运营方凭据）

运营方凭据（X OAuth2 应用密钥、BTCPay 连接）通过 Secure Courier（service="excalibur-operator"）交付。这是一个人工介入流程：运营方通过自己的 Nostr 客户端，主动批准每次凭据交付。调用 receive_credentials 时，中继器私信会被彻底清空——凭据在接收后只存在于 Neon Vault 中。

积分模式

每次工具调用需支付 api_sats。每次购买都会创建一个额度批次；只有当运营方的定价模式设置了 tranche_lifetime 时，该批次才会过期。 身份验证和余额工具始终免费。使用 excalibur_check_balance 查看余额和额度批次的到期时间。通过 excalibur_purchase_credits 充值。

可用工具

标准工具（来自 wheel）

标准 DPYC(TM) 工具由 tollbooth-dpyc 中的 register_standard_tools() 注册。这些工具包括会话管理、额度操作、安全信使、定价、公证和 Oracle 委托。每个工具都由确定性的 UUID v5 标识。

类别	工具
会话与计费	session_status、check_balance、account_statement、account_statement_infographic、restore_credits、service_status、check_price、check_authority_balance
安全信使	request_credential_channel、receive_credentials、forget_credentials、update_operator_credential、delete_operator_credential、update_patron_credential、delete_patron_credential、get_patron_credential_fields
Npub 证明	request_npub_proof、receive_npub_proof、check_proof_status、held_identities
购买与优惠券	purchase_credits、check_payment、mint_coupon、list_coupons、update_coupon、delete_coupon、redeem_coupon、list_my_coupons、forget_coupon
定价与约束	get_pricing_model、set_pricing_model、reset_pricing_model、list_constraint_types、list_canonical_identities
公证	notarize_ledger、list_notarizations、get_notarization_proof
入驻与采用	get_operator_onboarding_status、get_patron_onboarding_status、request_adoption、adoption_status、restore_neon_schema
Nostr 与诊断	get_nostr_profile、publish_nostr_profile、request_echo、report_issue
OAuth（X）	begin_oauth、check_oauth_status
Oracle（委托）	oracle_about、oracle_how_to_join、oracle_lookup_member、oracle_get_tax_rate、oracle_network_advisory

领域工具（eXcalibur 专用）

领域工具定义在 server.py 中（存储处理程序位于 tools/ 下）。价格由运营方的定价模型设定——调用前可使用 check_price 预览。读取和身份验证工具免费。

发布到 X

工具	描述
post_tweet	发布文本推文，并使用 Markdown 到 Unicode 的富文本格式
post_tweet_image	发布带主视觉横幅图片的推文（图片 URL 或渲染为 PNG 的 SVG）
get_x_profile	获取此用户关联的 X 账号用户名和名称（免费）
post_nostr_message	为你已验证的 npub 发布公开的 Nostr 笔记（kind 1），由临时记录者密钥签名并以 p 标签标记你

已存储的帖子（草稿和排期）

工具	描述
create_post	存储新帖子（草稿或已排期）；返回其 post_id
get_post	按 ID 读取一条已存储的帖子（仅限所属用户）
list_posts	列出你已存储的帖子，由服务端排序、筛选和分页
update_post	修改已存储的帖子（doc、publish_at、recurrence、status）
delete_post	删除已存储的帖子（默认软删除）

片段和风格

工具	描述
list_snippets	列出你保存的帖子片段（由服务端排序、筛选和分页）
get_snippet	按 ID 读取一条已保存的片段
save_snippet	保存可重复使用的片段（开场白／页脚／行动号召）
delete_snippet	删除已保存的片段（免费，仅限所属用户）
get_voice	读取你保存的写作风格（个人简介和禁用词）
save_voice	保存你针对每个 npub 的写作风格

AI 编辑和动态区块

工具	描述
refine_post_region	在服务端使用大模型润色帖子的标记区域
resolve_dynamic_block	开始解析动态（由提示词支持的）帖子区块；返回认领凭证
fetch_dynamic_block	兑换 resolve_dynamic_block 认领凭证（免费，需通过证明验证）

对话潜在线索

工具	描述
find_conversations	搜索 X 上提出你可以回答的问题的人；为其评分并将其存储为潜在线索
list_conversations	分页查看你存储的潜在线索（免费）
reply_to_conversation	在 X 上的潜在线索帖子串中发布你的回复，并将该线索标记为已互动
set_conversation_status	将潜在线索标记为新建、已查看、已互动或已忽略（免费）
list_conversation_queries	列出你保存的对话查询（免费）
save_conversation_query	创建或更新已保存的对话查询（免费）
delete_conversation_query	删除已保存的查询；其潜在线索会保留（免费）

帖子指标

工具	描述
harvest_metrics	按频率对已发送的帖子进行 X 指标快照扫描（仅限运营方）
get_post_metrics	读取你其中一篇帖子的指标快照序列
post_performance	根据已采集的帖子指标计算触达评分
post_performance_infographic	帖子表现的 SVG 信息图

调度器

工具	描述
process_scheduled_posts	发布所有到期的已排期帖子（仅限运营方）
get_scheduler_log	读取近期调度器周期的执行结果
scheduler_status	调度器的配置和当前状态（免费；任何已验证的用户均可使用）
scheduler_pending	查看排期帖子 cron Worker 正在等待的事项（仅限运营方）
scheduler_check_now	立即运行一个调度器周期（任何已验证的用户均可使用）
scheduler_reissue	立即再次发送调度器的证明请求（仅限运营方）

OAuth 流程工具（begin_oauth、check_oauth_status）现已作为 wheel 提供的标准工具 （参见上方的标准工具表）。

需要 npub 的工具只接收 npub：连接本身即可证明身份（参见 安全性）。

安全

• Npub 身份——通过 Nostr 公钥（npub）识别 Patron，而非电子邮件或密码。每种角色使用一个密钥对，由用户管理。
• 连接上的身份——连接通过以下两种方式之一证明其 npub：每个 HTTP 请求都使用 npub 的密钥签名（NIP-98，kind 27235）；或者 OAuth 持有者连接携带 Operator 签名的授权，该授权通过 request_npub_proof / receive_npub_proof 获取。Patron 可选择授权的有效期，最长为 30 天；held_identities 和 check_proof_status 会显示连接持有的身份。
• 有人参与的 Secure Courier——凭据交付需要 Operator 通过 Nostr DM 主动批准。收到后，中继消息会被彻底清空，因此密钥仅存在于加密的 Neon 保管库中。
• 每个 Operator 独立的 Neon 架构——每个 Operator 的凭据都存储在隔离的 Postgres 架构中，并使用专用 LOGIN 角色。Operator 之间无法互相访问。

架构

src/excalibur_mcp/
  server.py        FastMCP server -- domain tools + register_standard_tools()
  config.py        Pydantic settings from environment variables
  oauth_flow.py    X-specific OAuth2 Authorization Code + PKCE wrapper
  x_client.py      X API v2 client with OAuth 2.0 Bearer token auth
  formatter.py     Markdown -> Unicode rich text (bold, italic, headers)
  refine.py        Server-side editorial refinement for the post editor
  resolve.py       Server-side resolution of dynamic (prompt-backed) post blocks
  resolver.py      Builds one post's finished body (the slow half: dynamic blocks)
  publisher.py     Carries a finished body to X (the fast half: bill, post, record)
  scheduler.py     Scheduled-post firing (publishes due posts on the owner's behalf)
  conversation_scoring.py  Pure scoring + query composition for conversation leads
  metrics_harvest.py       Post-metrics harvest cadence and derived reach scores
  nostr_note.py    Public Nostr notes signed by an ephemeral scribe key
  tools/           Domain storage handlers (posts, snippets, voices, conversations, metrics)
  db/              eXcalibur persistence on the wheel's NeonVault (posts, snippets, voices,
                   conversations, metrics, scheduler runs, migrations)
modal_app.py       Detached runner for long dynamic-block resolves (Modal)
scheduler-worker/  Cloudflare Worker cron that fires due scheduled posts
frontend/          The web editor (excalibur.tollbooth-dpyc.com)

主要设计选择：

• OAuth2 Authorization Code + PKCE——通过浏览器流程获取 Patron 令牌。begin_oauth 会返回主要的 authorize_url（而非短链接）；check_oauth_status 会完成令牌交换。令牌存储在 Neon 保管库中，并在过期时自动刷新。不支持 OAuth 1.0a。
• UUID v5 工具标识——每个工具（标准工具和领域工具）都有一个根据其能力名称确定性生成的 UUID。定价、约束和计费都以 UUID 为依据。
• 来自 wheel 的标准工具——register_standard_tools() 提供所有 DPYC(TM) 基础设施工具。server.py 中仅定义特定领域的 X/Twitter 工具。
• Markdown 转 Unicode——将 **bold**、*italic* 和 # headers 转换为 Unicode 字符，使其无需标记语法也能在推文中正常显示。

自托管

环境变量

DPYC(TM) 身份（启动所需）

变量	必需	描述
TOLLBOOTH_NOSTR_OPERATOR_NSEC	是	用于身份引导和 DM 加密的 Operator Nostr 秘密密钥

这是启动所需的唯一环境变量。所有其他密钥（X 应用密钥、BTCPay 凭据）均通过 Secure Courier 凭据模板交付，并存储在每个 Operator 独立的 Neon 保管库架构中。

Operator 凭据（通过 Secure Courier）

这些凭据通过 Secure Courier（service="excalibur-operator"）交付，而非设置为环境变量：

凭据	描述
client_id	X OAuth2 Client ID（来自 X Developer Portal）
client_secret	X OAuth2 Client Secret（来自 X Developer Portal）
btcpay_host	BTCPay Server URL
btcpay_store_id	发票对应的 Store ID
btcpay_api_key	具有发票权限的 API 密钥
llm_api_key	可选。供 refine_post_region 和动态区块使用的模型路由器密钥（默认使用 OpenRouter）；没有此密钥仍可发帖
modal_token_id、modal_token_secret、modal_app_name	可选。运行动态区块耗时解析任务的 Modal 工作区；这些任务会从 MCP 主机分离运行
github_repo、github_token	可选。report_issue 提交 Patron 现场报告的位置（令牌仅需 issues:write 权限）

已认证的 Operator 会通过加密的 Nostr DM 从 Authority 获取 Neon 数据库 URL 以完成引导——不会从环境中读取 NEON_DATABASE_URL。

可选调优

变量	描述
SCHEDULER_WORKER_URL	定时发帖 cron Worker 的公共 URL（默认值：https://excalibur-scheduler.lonniev.workers.dev）
RESOLVE_BLOCK_BUDGET_MAX_S	单个动态区块的 LLM 运行时长上限，单位为秒（默认值：1800）；任务、租约和运行器超时均据此派生

故障排除

冷启动

部署后首次收到请求时，服务可能需要几秒钟来初始化 Neon 连接并加载定价模型。运行时会通过内联重试处理这一情况——预热完成后，调用方会收到结果，而不是收到“服务不可用”错误。

常见的工具调用情形

响应会说明当前生命周期状态，并提供下一步操作指引，而不是只返回错误消息。

• proof_required——连接未能证明其 npub（或授权已过期）。调用 request_npub_proof，回复私信，然后调用一次 receive_npub_proof。check_proof_status 会显示授权还剩多长时间。
• “Insufficient credit balance”——调用 purchase_credits 充值。使用 check_balance 查看额度批次的过期时间。
• “Operator credentials not configured”——这是 Operator 设置问题，与赞助者无关。

**不要纠缠客户：**除非响应明确指出上游令牌已过期或无效，否则不要要求赞助者重新进行身份验证、重新授权或重新完成 OAuth。

开发

# Install in development mode
cd excalibur-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
.venv/bin/pytest tests/

# Type checking
mypy src/excalibur_mcp/

# Formatting
black src/ tests/
ruff check src/ tests/

DPYC(TM) 生态系统

• tollbooth-dpyc -- Tollbooth 变现 Python SDK（保险库、身份验证、定价、Lightning 支付、Nostr 身份）
• dpyc-community -- 治理注册表：成员资格、公告、威胁模型
• dpyc-oracle -- 社区服务台（免费入门指导 + 成员查询）
• tollbooth-authority -- 认证基础设施（Schnorr 签名的采购订单证书）
• tollbooth-sample -- 示例 Operator（标准模板）
• tollbooth-pricing-studio -- iOS 定价模型编辑器 / Operator 控制台
• cypher-mcp -- 变现图谱问答：针对 Neo4j/AuraDB 的命名 Cypher 模板
• schwab-mcp -- Charles Schwab 经纪业务数据
• thebrain-mcp -- TheBrain 个人知识图谱
• excalibur-mcp -- X/Twitter 发帖
• taxsort-mcp -- 税务分类 + Cloudflare Pages 界面
• optionality-mcp -- 期权交易练习游戏
• goodearth-mcp -- 面向小型农场的区域气候分析
• beesknees-mcp -- The Bee's Knees 赛车游戏
• roastify-mcp -- Roastify 咖啡目录与包装艺术设计
• ChartRemotely-mcp -- 在桌面图表上远程添加证券
• tollbooth-web -- 面向 Operator 前端的共享浏览器 SDK
• tollbooth-oauth2-collector -- OAuth2 回调处理程序（倡导者服务）
• tollbooth-shortlinks -- URL 缩短工具

商标

DPYC、Tollbooth DPYC 和 Don't Pester Your Customer 是 Lonnie VanZandt 的商标。有关使用准则，请参阅 dpyc-community 仓库中的 TRADEMARKS.md。

许可证

Apache License 2.0 -- 详情请见 LICENSE。