Allows ingesting podcast RSS feeds to build and maintain the episode catalog that backs the server's search and evidence retrieval tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ask-pb what did the podcast say about suspension setup?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local podcast knowledge pipeline and read-only MCP server, starting with the Pinkbike Podcast. Independent project; not affiliated with Pinkbike or Outside.
Working foundation: RSS → episode catalog → audio cache → timestamped transcription → SQLite full-text search → MCP evidence tools.
The initial live sync found 363 episodes (375.4 declared hours). Metadata alone cannot answer bike questions: import transcripts or run the local transcription worker to populate search.
Python 3.11+ and SQLite with FTS5; the ingestion CLI supports macOS/Linux (uses POSIX file locking).
python3 -m venv .venv
.venv/bin/pip install '.[dev]'
.venv/bin/ask-pb sync
.venv/bin/ask-pb coverage
.venv/bin/ask-pb episodes --limit 10The default data directory is ./data. Set ASK_PB_DATA_DIR or pass --data-dir before the subcommand for a stable absolute location. All audio, database files, and model outputs belong outside version control. probe/ contains the original access investigation and catalog snapshot.
For development, use pip install -e '.[dev]' where editable installs work, or reinstall with pip install . after edits. Tests load src/ directly.
Related MCP server: gq-insight-mcp
Copy an episode ID from episodes. Import JSON matching this schema:
{
"provider": "your-transcriber/model-version",
"language": "en",
"segments": [
{"start": 12.5, "end": 20.0, "text": "Original transcript wording.", "speaker": null}
]
}.venv/bin/ask-pb import-transcript EPISODE_ID /absolute/path/transcript.json
.venv/bin/ask-pb search 'suspension'Timestamps are seconds from the start of the audio, finite, ordered, and positive in duration. Speaker is optional; do not assign a real person's name without verification. The example wording is synthetic, not a Pinkbike quote. Entire imports validate before replacement and commit atomically. Reimporting replaces the episode's search index; old evidence IDs change when the transcript changes.
.venv/bin/pip install '.[transcribe]'
.venv/bin/ask-pb process --limit 1 --model small.en
# Or select a specific pending episode:
.venv/bin/ask-pb process --episode-id EPISODE_ID --model small.enThe optional adapter uses faster-whisper on CPU with int8 computation by default. The first run downloads model weights. No cloud transcription API is called. Native dependency availability varies by Python/platform; Python 3.11 or 3.12 is a reasonable fallback if installation fails. Speech recognition itself has not been benchmarked against the Pinkbike archive yet.
process downloads and transcribes newest pending episodes, bounded by --limit (default 1). Completed episodes are skipped. Failed episodes retain an error and are retried on a subsequent invocation. A failed batch exits nonzero. Successful transcripts include a SHA-256 of the downloaded audio. Downloaded audio is cached and hash-checked; partial files are discarded on failure. Maximum file size is 1 GB.
For a different provider, implement a callable that takes an audio path and returns the same JSON document; pass it to core.process, or export JSON and use import-transcript.
Configure your MCP client to launch the installed executable with absolute paths:
{
"mcpServers": {
"pb": {
"command": "/absolute/path/ask-pb/.venv/bin/ask-pb",
"args": ["--data-dir", "/absolute/path/ask-pb/data", "serve"]
}
}
}The client owns the server process; there is no separate daemon to start. All diagnostics go to stderr. The server exposes:
Tool | Purpose |
| Check corpus size, feed check times, and transcription coverage |
| Browse metadata and transcription status |
| Search short topic/product keywords; all query words must match |
| Retrieve a passage's original wording and provenance |
| Read surrounding transcript passages by episode and time |
Tools cannot download audio, import data, or run models. Evidence includes timestamps, source URL, audio URL with a media time fragment, provider, and transcript hash. Time-fragment playback depends on the audio player; start/end seconds are also returned explicitly.
.venv/bin/ask-pb --data-dir /absolute/path/ask-pb/data serve --transport streamable-http --port 8000Connect a Streamable HTTP MCP client to http://127.0.0.1:8000/mcp. The server binds to loopback. For hosted deployment, see Deploy on Render: Docker, persistent storage, bearer authentication, a health endpoint, and scheduled ingestion. Render terminates TLS. OAuth and multi-tenant access are not implemented.
Rerun these commands from an external scheduler or manually:
.venv/bin/ask-pb --data-dir /absolute/path/ask-pb/data sync
.venv/bin/ask-pb --data-dir /absolute/path/ask-pb/data process --limit 3These local commands do not install a schedule. The Render deployment starts its own bounded ingestion worker. sync honors ETag/Last-Modified when provided, upserts by feed URL + GUID, and preserves transcripts through metadata-only changes. Changed audio URLs invalidate cached audio and mark transcripts stale; stale passages disappear from search until reprocessed. One ingestion CLI writer per data directory is enforced; MCP readers can remain running.
Feed omissions do not delete old records: feeds may be truncated. Takedown/deletion reconciliation is not implemented. A publisher changing audio bytes at an unchanged URL is also not automatically detected. Dynamic advertisements may shift playback timestamps across later requests; recorded audio hashes identify which file was transcribed. Back up the data directory with workers stopped (or use SQLite's backup API).
This is evidence retrieval, not yet archive-wide analysis. Search uses SQLite FTS5 with AND matching and ranks individual transcript segments. It does not perform semantic search, infer product generations, identify speakers, deduplicate video/podcast recordings, or prove consensus. Use several focused searches and check coverage before synthesizing. Source text is untrusted data, never instructions to an AI client.
Next: evaluate one real transcription; add overlapping retrieval windows and semantic search; normalize product generations; verify speakers; then add cross-episode research with explicit coverage and counterevidence. YouTube ingestion remains outside this foundation because the initial caption probe did not retrieve text.
Public feed access does not establish content reuse rights. The software license does not license Pinkbike audio, transcripts, or metadata. Keep corpus distribution separate from code distribution.
.venv/bin/python -m pytest -qTests use synthetic transcripts and mock network responses. They cover repeat syncs, revisions, invalid input, timestamp citations, atomic downloads, retry behavior, CLI operations, and a real MCP stdio session. They do not download podcast audio or model weights.
Get indexed episode counts, feed check times, and limitations. Metadata is not evidence.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context about the nature of the data (metadata vs evidence) and the specific outputs (counts, check times, limitations), going beyond what annotations provide. This is a useful disclosure of behavioral scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, with the action verb and main outputs front-loaded. The cautionary note is included without redundancy. Every word earns its place, making it an exemplary concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool with an output schema and annotations covering safety, the description is fully complete. It tells the agent what to expect (counts, check times, limitations) and warns about the metadata nature, leaving no ambiguity about the tool's purpose or scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. According to the rubric, a baseline of 4 applies for 0-parameter tools, and the description correctly does not attempt to explain nonexistent parameters. No additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (get) and resource (coverage metadata), listing concrete outputs: indexed episode counts, feed check times, and limitations. It also clarifies what it is not ('Metadata is not evidence'), distinguishing it from evidence-focused siblings like get_evidence and search_bike_evidence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool provides coverage metadata, not evidence. The explicit 'Metadata is not evidence' serves as a when-not guidance, telling agents not to use this for evidence retrieval. However, it does not name specific alternative tools or conditions for switching, so it falls short of fully explicit usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read surrounding transcript passages at or after a time, including overlapping passages.
Paginate using the last passage end time. Maximum 50 passages. Returns original wording.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| episode_id | Yes | ||
| start_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, and the description adds non-obvious behavior: overlapping passages, pagination by last end time, maximum 50 passages, and preservation of original wording. This exceeds what annotations provide and sets correct expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short front-loaded sentences with no filler. The core behavior is stated first, followed by pagination cap and output fidelity, each sentence earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, 3-parameter tool with an output schema, the description covers the critical operational details: start time, pagination method, limit, and wording. The only notable gap is selection guidance among sibling tools, which is covered under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage the description must carry parameter meaning. It maps 'at or after a time' to start_seconds and 'Maximum 50 passages' to limit, but it does not explicitly identify episode_id or explain how start_seconds and limit interact with pagination. Enough to get started, but not complete parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action ('Read') and resource ('surrounding transcript passages') with a clear temporal scope ('at or after a time') and notes overlapping passage behavior. It doesn't explicitly contrast with siblings like get_evidence or search_bike_evidence, but the resource/temporal scope makes the purpose recognizable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to choose this tool over its siblings (search_bike_evidence, get_evidence, get_coverage, list_episodes). It provides pagination instructions, but no when-to-use or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get original transcript wording and citation metadata for a search result.
A stale transcript flag means the feed's audio URL changed after transcription.
| Name | Required | Description | Default |
|---|---|---|---|
| passage_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only and non-destructive. The description adds value by explaining what a 'stale transcript flag' means, giving agents extra context about the tool's output semantics beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The primary purpose is front-loaded, and the stale-flag note earns its place by providing meaningful behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema presumably describes return values, and annotations cover the read-only safety profile. Still, the description leaves ambiguity about how passage_id is obtained and how this tool connects to the search workflow, so it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameter, but it only indirectly suggests that passage_id identifies a search result. It does not clarify where passage_id comes from, its expected format, or its relationship to the search results produced by sibling tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and names a concrete resource: original transcript wording and citation metadata for a search result. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like get_episode_passages or get_coverage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a search result' implies it should be used after searching, but there is no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. An agent must infer the intended workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse episode metadata, transcription availability, and errors. Maximum 500 per page.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the useful behavioral constraint of a 500-item page limit and clarifies what data is exposed (metadata, transcription availability, errors).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states purpose first and then the key constraint. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and only two optional pagination parameters, the description covers the essential behavior. The annotations cover safety, and the output schema handles return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for 'limit' by capping it at 500, but it does not explain 'offset' semantics (e.g., zero-based skip), leaving a gap for agents unfamiliar with pagination conventions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Browse') with a specific resource: episode metadata, transcription availability, and errors. This distinguishes it from siblings like get_episode_passages or get_evidence, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for browsing episode-level data and includes a practical pagination cap ('Maximum 500 per page'), but it does not explicitly state when to prefer this tool over siblings or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find timestamped transcript segments using keywords (all query words must match).
Use short product/topic queries, not full questions. Results include source and transcript provenance. Search is lexical, not exhaustive thematic analysis. Maximum 50 results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| episode_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly aligns with read-only behavior. It adds valuable context about lexical matching, the 50-result cap, and that results include provenance, going beyond what annotations provide. No contradictions detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each adding value: purpose, query style, result content, and search limitations. It is front-loaded with the primary purpose and includes no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description covers the core search behavior, query format, and result limits. However, it omits the purpose of episode_id and does not address when to use this tool versus siblings. The presence of an output schema reduces the need to describe return values, but the missing parameter semantics and alternative guidance keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides guidance on the query parameter (short product/topic queries) and implicitly on limit via 'Maximum 50 results', but it does not explain the episode_id parameter at all. With three parameters, this is a significant gap, especially since episode_id is not self-explanatory from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds timestamped transcript segments using keywords, and specifies that all query words must match. It also distinguishes itself from thematic analysis by stating it's lexical, which helps differentiate from sibling tools like get_evidence or get_episode_passages that might perform semantic retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using short product/topic queries rather than full questions, which is useful. However, it does not explicitly state when to use this tool versus alternatives like get_evidence or get_episode_passages, nor does it mention exclusions. The guidance on query format is helpful but incomplete for routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_coverageget_episode_passagesget_evidencelist_episodessearch_bike_evidenceScored across 5 tools
Each tool targets a distinct step in the workflow: searching transcripts, retrieving evidence details, listing episodes, checking coverage, and reading passages. No two tools appear to serve the same purpose; descriptions clearly differentiate them.
All tool names follow a consistent verb-object snake_case pattern (search_, get_, list_)) with clearly descriptive objects. The verbs are appropriate for the action, and no mixed conventions or vague generic names are present.
Five tools is well within the ideal range for a focused read-only evidence retrieval server. Each tool covers a necessary part of the search-and-retrieval workflow without bloat or missing essentials.
The tool surface covers the full workflow: search across transcripts, fetch exact evidence, browse episode metadata, check indexing coverage, and read surrounding passages. No obvious dead ends or missing operations for the stated purpose.
Search indexed YouTube and podcast transcripts. Full transcripts, mentions, momentum, and sponsors.
Search and analyze 50,000+ hours of business podcast transcripts, entities, and speakers.
Search evidence-backed AI-tool reviews, rankings, use cases, comparisons & toolkits (read-only).
Search speech in podcasts, government meetings, and your own audio: speakers, entities, timestamps.
