Podcast Parser

@pipeworx/podcast-parser

在 162 个受追踪的播客中反复出现的内容——从 10,000 多期节目中提取的观点，每条都附有其状态背后的衡量依据：有多少个独立播客和发言者重复提及该观点，不包括最初提出该观点的人。

属于 Pipeworx — 一个将 AI Agent 连接到 1683+ 个实时数据源的 MCP 网关。

已上线，仅支持自带密钥（BYO）。 在 2026-09-14（fleet #1958）从 _incubator 提升并接入网关，当时 Bruce 的合作伙伴密钥已就绪，且导出的 8 个工具都能从真实 API 返回非空载荷。

尽管存在 Pipeworx 平台密钥，本服务仍仅支持自带密钥，这是有意为之，并非疏忽。网关的 Cloudflare 文本绑定数已达 250 个的上限，因此 wrangler secret put PLATFORM_CANONCANNON_KEY 会被直接拒绝——"Too many text bindings, found a total of 251, they exceed the limit of 250"（代码 10055）。如果声明了 platformKeyEnv，但密钥实际上并不存在，这个包就会在路由中取消沉底，并将有关播客共识的问题发送给一个只能拒绝请求的工具；这比诚实地返回 no_match 更糟——参见 fda-inspections 先例，fleet #617。因此，该包不声明 platformKeyEnv，keyBlockedTools() 会将其排除在 ask_pipeworx 检索之外，而拥有自己 CanonCannon 密钥的调用方仍可通过 _apiKey 直接调用它。

完成接入： 先为网关释放一个文本绑定，然后在同一项变更中提交 wrangler secret put 和 platformKeyEnv: 'PLATFORM_CANONCANNON_KEY'。密钥本身已经签发，保存在规范检出目录中被 git 忽略的 .env 文件里，并已通过实时验证。canon_citations 则另行暂缓开放——参见完整性门控。

工具

导出了 8 个工具。canon_citations 已实现，但有意暂缓开放——参见完整性门控。

• canon_search(query?, tier?, label?, limit?, cursor?) — 查找反复出现的观点。 每一行都包含 tier 和其衡量依据。
• canon_get(slug) — 完整条目：观点、证据、细微差异、缺失之处、相关内容、书籍，以及在其旁边用一句话说明的衡量依据。
• canon_episode_search(query?, podcast?, since?, limit?, cursor?) — 节目语料库。
• canon_episode_get(slug) — 一期节目的详情，包含提取出的观点、嘉宾和书籍。
• canon_person_get(slug) — 某人在不同节目中实际说过的内容。
• canon_podcast_list(limit?, cursor?) — 受追踪节目的名单，也就是规范标准的分母。
• canon_podcast_get(slug) — 一档受追踪节目的详情。
• canon_corpus_stats() — 语料库计数，以及当前生效的标准。
• canon_citations(slug) — 暂缓开放。 引用某观点的所有节目，包含发言者及其是否为提出该观点的人。

身份验证

目前仅支持自带密钥：_apiKey（Authorization: Bearer cc_live_...）。所有 /api/v1 端点在没有密钥时都会拒绝请求——不带密钥的 GET /stats 会明确返回 401 {"error":"Missing or malformed API key. Send Authorization: Bearer cc_live_..."}， 因此凭证缺失一目了然，不会被误认为是服务中断。

没有 platformKeyEnv，因为我们没有密钥。Bruce 签发合作伙伴密钥后，应在添加 MCP_PACKS 条目的同一项变更中，将 PLATFORM_CANONCANNON_KEY 接入网关（参见 fda-inspections 先例，fleet #617）——声明了但未设置的平台密钥会根据密钥规则导致该包中的所有工具失效，调用方看到的会像是一个故障的包，而不是一个尚未获得资金支持的包。

此外，引用端点仅限内部层级的密钥访问，因此合作伙伴密钥在该端点会收到 403。这是上游策略，不是我们的门控。

测量信封——完整契约

tier 绝不会在没有同级 measurement 的情况下提供，且只有以下两种形式：

{ "available": true, "measured_at": "…", "independent_podcasts": 23,
  "independent_speakers": 41, "independent_episodes": 36,
  "threshold": 9, "tracked_podcasts": 162 }

{ "available": false, "reason": "not_yet_measured" | "not_yet_persisted" }

我们会原样保留这种嵌套结构，而不是将其扁平化为顶层可空字段。 这样，调用方就能区分**“尚未计算”和“已计算，结果为零”**。零个独立发言者是对某个条目的强断言；不可用则完全不作断言；null 看起来两者都是，而当它与已填充的 tier 并列时，又像是在说*“忽略这个，相信 tier”*。

两种不可用原因代表不同的断言，我们绝不会将它们合并：

原因	含义	出现频率
not_yet_measured	此条目比上一次 nightly 重算更新	每行，按设计永久如此——今天添加的每个条目都符合此情况
not_yet_persisted	当前完全没有存储这些计数	整个语料库范围内，确实存在但暂时性的上游缺陷

如果将两者都呈现为笼统的“测量不可用”，调用方就会把正常情况误读为故障——在我们刚费尽心力避免制造虚假共识计数之后，又凭空制造出一份针对正常运行的流水线的虚假缺陷报告。

measured_at 是关键数据，不是元数据。CanonCannon 的门槛具有双向性：即使一个条目没有失去任何支持，它也可能仅仅因为语料库扩充而失去 canon 身份（门槛为 ceil(5% of tracked_podcasts)）。而且，逐行的 measured_at 是外部唯一能检测到 not_yet_measured 的依据。

没有 tracked_podcasts，就绝不会报告 threshold。“162 个中的 9 个”是一项断言；单独的“9”只是一个数字。

canon_citations 的完整性门禁

src/index.ts 中的 CITATIONS_VERIFICATION_LANDED = false 会阻止该工具进入导出的 tools 数组，而 callTool 会返回拒绝调用的原因。

CanonCannon 的提取器将 canon 条目用作归档标签，因此某个条目自己的摘要文本可能被计作对其自身的支持。canon_citations 返回的是共识计数——调用方最难核实的一类结果——所以，在受污染的链接上发布它，会让每个调用它的 Agent 都看到一个信心十足的错误数字，而这个数字还冠以 Pipeworx 之名。上游正在对 4,218 个链接进行验证。

切换此标记之前：

1. 确认验证流程已完成。“API 已上线”并不意味着验证已完成——该流程是独立的流水线任务，有自己的执行计划。
2. 检查返回的行中 verified: true。端点会为每行携带此标记，因此门禁由上游强制执行，而不是依赖某人记得执行。
3. 不要将排除规则硬编码。当本文撰写时，修复会改变规则的形式还是仅改变其输入，仍未确定。因此，该工具只报告 API 声明的规则，而非预期的规则。

为什么所有工具都以 canon_ 为前缀

episode_get、person_get、podcast_list 和 corpus_stats 是 CanonCannon 自身 API-PLAN.md §3 中的名称；如今在 mcps/* 和线上网关中都清晰明确（于 2026-09-14 确认）。这些名称也足够通用，任何人接下来构建的播客数据包——Listen Notes、Podcast Index、某个文字稿来源——都会想要其中四个。

这很重要，因为网关解析裸 tools/call 的方式是：当某个名称只属于一个数据包时，它会以裸名称公开；一旦第二个数据包导出同名工具，两个工具都只能通过 <pack>_<name> 访问。因此，未来的数据包可能会悄无声息地重命名此数据包的线上工具，破坏其 tool-examples.json 中的键，以及所有已经记住裸名称的调用方。九个中央银行数据包都导出 exchange_rates 就是实测先例；在该问题被清理之前，有人询问“日本央行政策利率”时，得到的却是以色列的数据。

现在加上 canon_ 前缀不费吹灰之力，之后再加则只能通过破坏性重命名实现。无论如何，在晋升时重新运行检查即可——成本很低：

for n in canon_search canon_get canon_citations canon_episode_search          canon_episode_get canon_person_get canon_podcast_list          canon_podcast_get canon_corpus_stats; do
  grep -rl "name: '$n'" mcps/*/src/ | head -3
done
scripts/pwcall.sh names canon_          # and against the live gateway

现在名称检查已生效：此数据包位于 mcps/podcast-parser/，pnpm check:collisions 和 check:error-body-leak 都会对该目录执行 glob 匹配。晋升时已确认所有九个 canon_* 名称在 mcps/*/src 中均为唯一名称。

数据源

• https://canoncannon.com/api/v1/openapi — 契约。无需密钥；应根据此文件构建工具架构，而不是根据文字说明。
• https://canoncannon.com/api/v1/canon、/canon/{slug}、/canon/{slug}/citations、 /episodes、/episodes/{slug}、/people/{slug}、/podcasts、 /podcasts/{slug}、/stats — 八个加一个工具所封装的接口。

上游已定义规格，但目前有意不予封装：GET /people（列表）、GET /search（跨语料库搜索）、GET /changes?since=（低成本轮询）。等调用方提出需求时再添加工具；每个工具都需要在 tool-examples.json 中有一条记录，该记录必须来自实际返回了行的调用，而目前我们无法记录这样的示例。

下一个人原本会重新发现的事情

• 使用游标分页，绝不使用偏移量分页。 ?cursor= 是键集分页。遇到 next_cursor: null 或页面为空时终止——绝不要因为页面较短就终止，因为短页面正是静默截断的表现。这一约定源自曾让我们吃过苦头的同一个 PostgREST 1,000 行上限；参见 docs/postgrest-row-cap.md。此工具包每次工具调用只发出一个上游请求，并将游标返回，因此调用方绝不会收到一个看似完整、实则已截断的列表。
• 在实际传输中，只有我们会使用 /api/v1。 CanonCannon 自己的页面在进程内渲染（Worker 获取自身区域时会重新进入该 Worker），因此其生产流量从未经过这些路由。我们会发现 API 的漏洞。将 OpenAPI 文件视为意图，将线上端点视为事实——因此这里的每个响应都可以带有 contract_warnings，而这些警告会传递给调用方，不会被吞掉。
• 那边的一个契约漏洞已经躲过了二十条绿色断言（canon_related 有两个指向 canon 的外键，嵌入查询存在歧义，生产环境中的每个详情请求都返回了 500，而所有桩测试都通过了）。详情端点没有声明响应架构，所以此工具包会原样传递它们的负载，而不是手动映射这里无人见过的字段。
• 不得重新引入未公开的 citation_count。 它原本是一个文本列，存着模型生成的描述，却披着数字字段的名字。
• 绝不直接访问 Supabase。 canon-cannon 的 Supabase 项目（admbyodxaxsikiczgfjf）是独立项目；Pipeworx 绝不能让迁移、摄取任务或数据管道 Worker 指向该项目。通过 HTTP 访问，才能在门槛变化时同步继承新要求，而不是逐渐偏离。不要把它“优化”为直接读取，也不要将他们的语料摄取到 Pipeworx 表中。
• 他们的 api_keys 表曾短暂处于未启用 RLS 的状态（匿名可读且匿名可写；问题被发现后在一小时内修复，并经过独立复测）。在此记录这一点，因为我们将持有的密钥正是从该表签发的。

测试

src/index.test.ts——基于已发布的 OpenAPI 文件中的固定数据，共有 25 条断言。它们验证我们对已声明契约的处理方式：两种不可用原因保持区分，tier 绝不会裸传，null 会被标记而不是转发，页面数量绝不会被说成总量，拒绝信息会原样包含 "requires an API key" 这几个词。

它们不能证明线上 API 会返回这些形状——这里没有发起过任何线上调用。密钥到位后、任何人将此工具包标记为已验证之前，请将固定数据负载替换为线上记录的实际数据。

推广发现的问题（2026-09-14）

在网关接线完成前，已针对真实 API 对全部八个导出的工具进行了实时冒烟测试，并发现了两个只有实时调用才能发现的问题：

1. canon_corpus_stats 告诉每位调用者未报告基准值，尽管两个数值都在载荷中。 /stats 将基准值嵌套在 { corpus: {...}, bar: { threshold, tracked_podcasts, computed_at, rule } } 中；该工具包却在顶层读取 threshold 和 tracked_podcasts，两者都没找到，于是输出了 "CanonCannon did not report both the threshold and the tracked-podcast count"。现在会优先读取嵌套结构，并将扁平结构作为回退方案。这是该工具包自己的首要规则——将 OpenAPI 产物视为意图，将实时端点视为事实——在还没有密钥可供检查的这段时间里失效了。
2. 八个文档示例中有三个使用了会返回 404 的 slug。 zone-2-base-training、huberman-lab-sleep-toolkit 和 the-drive 都是编造的；真实的 slug 是 circadian-rhythm-health-foundation、pa-392-sleep-apnea 和 peter-attia-drive。canon_search({query: "zone 2 training"}) 也返回了零行，因为上游的 q 使用的是短语匹配，而不是按词 AND 匹配——"zone 2" 能匹配，"zone 2 training" 则不能。工具描述和 tool-examples.json 中的所有示例现在都已替换为实际返回过数据的调用。

仍暂缓开放的内容

canon_citations 仍未导出（CITATIONS_VERIFICATION_LANDED = false）。 此限制在上游和这里都会执行：截至 2026-09-14， GET /canon/{slug}/citations 返回 HTTP 403 — "Citations are not yet public: the underlying links are pending a verification pass. This endpoint currently requires an internal key."。请向 CanonCannon 确认审核已完成，检查返回行中的 verified: true，然后切换该标志，并记录一个确实返回过数据的调用示例。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "podcast-parser": {
      "url": "https://gateway.pipeworx.io/podcast-parser/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/podcast-parser/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 的共享元工具——ask_pipeworx、discover_tools、search_within、remember/recall，还有网关范围内的其他工具。因此，你看到的工具数量会多于表中所列：目前，单个工具包端点会在工具包自身的工具旁列出约 30 个共享工具。连接的 initialize 响应会说明确切范围，是当天情况的权威依据。

这是有意为之，并非意外的多路复用。元工具能让限定范围的连接回答本工具包未覆盖的问题——通过 ask_pipeworx 跨整个目录路由——而无需你再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构信息占用的上下文比路由带来的价值还多，请连接一次完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不只是当前工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1683+ 个数据源。唯一的区别在于直接列出的是哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

此工具包需要你自己的 API 密钥（_apiKey）——我们不会代为提供，因此这里没有无需密钥就能运行的 curl 命令。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/canon_search。查找工具：使用 {"query":"..."} 发送 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经由网关往返：

{
  "mcpServers": {
    "podcast-parser": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-podcast-parser"]
    }
  }
}

也可以直接运行，以确认它能够启动：

npx -y @pipeworx/mcp-podcast-parser

它通过 stdin/stdout 使用 MCP 通信，并响应 initialize/tools/list/tools/call，仅提供此软件包的工具——不包含上述网关连接额外提供的任何共享元工具。相同的源代码，相同的工具，不使用 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗英语提问，而不是直接调用工具——这既适用于上述软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Podcast Parser data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT