Skip to main content
Glama
macsplit

HPR Knowledge Base MCP Server

by macsplit

Hacker Public Radio Knowledge Base MCP Server

An MCP (Model Context Protocol) server providing access to the Hacker Public Radio (HPR) knowledge base, including episodes, transcripts, hosts, series, and community comments.

About HPR

Hacker Public Radio is a community-driven podcast where hosts contribute content on topics of interest to hackers. All content is released under Creative Commons licenses, making it freely available for learning and sharing.

Related MCP server: slack-messages

Features

This MCP server provides:

  • Episode Search: Search through thousands of HPR episodes by title, summary, tags, or host notes

    • Fuzzy Matching: Automatically handles typos and misspellings (e.g., "linx" finds "linux", "pythoon" finds "python")

  • Transcript Search: Full-text search across all episode transcripts with flexible matching modes

  • Episode Details: Get complete information about any episode including transcript and comments

  • Host Information: Look up hosts and see all their contributions

    • Fuzzy Matching: Handles name variations and typos (e.g., "klattu" finds "Klaatu")

  • Series Browsing: Explore mini-series of related episodes

  • Statistics: View overall HPR statistics and recent episodes

Installation

Prerequisites

  • Node.js 18 or higher

  • The HPR data files:

    • hpr_metadata/ directory containing JSON files

    • hpr_transcripts/ directory containing transcript files

Setup

  1. Install dependencies:

npm install
  1. Make the server executable:

chmod +x index.js

Usage

Running Locally (Stdio Mode)

You can test the stdio server directly (for local MCP clients like Claude Desktop):

npm start

Running as HTTP Server (Network Access)

For network access and public deployment, use the HTTP/SSE server:

npm run start:http

This starts an HTTP server on port 3000 (configurable via PORT environment variable) with:

  • SSE endpoint: http://localhost:3000/sse

  • Health check: http://localhost:3000/health

  • Built-in rate limiting, compression, and graceful degradation

Using with AI Tools

Claude Desktop (and other MCP-compatible clients):

See CONFIGURATION.md for detailed setup instructions for:

  • Claude Desktop (stdio - fully supported)

  • ⚠️ Other MCP Clients (varies by client)

  • ChatGPT (not supported - workarounds included)

  • GitHub Copilot (not supported - alternatives included)

  • Google Gemini (not supported - integration options)

  • 🔧 Custom Integration (Python/Node.js examples)

Quick Start (Claude Desktop):

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hpr-knowledge-base": {
      "command": "node",
      "args": ["/absolute/path/to/knowledge_base/index.js"]
    }
  }
}

Replace /absolute/path/to/knowledge_base/ with the actual path to this directory.

Note: Claude Desktop currently only supports local (stdio) connections. Remote HTTP/SSE support coming in future versions.

Using with Other MCP Clients

Any MCP-compatible client can connect to this server via stdio. The server will load all HPR data on startup and make it available through tools and resources.

Available Tools

1. search_episodes

Search for episodes by keywords in title, summary, tags, or notes.

Parameters:

  • query (string): Search query

  • limit (number, optional): Maximum results (default: 20)

  • hostId (number, optional): Filter by specific host

  • seriesId (number, optional): Filter by specific series

  • tag (string, optional): Filter by tag

  • fromDate (string, optional): Filter from date (YYYY-MM-DD)

  • toDate (string, optional): Filter to date (YYYY-MM-DD)

Example:

Search for episodes about "linux kernel" from 2020 onwards

2. get_episode

Get detailed information about a specific episode.

Parameters:

  • episodeId (number, required): Episode ID

  • includeTranscript (boolean, optional): Include transcript (default: true)

  • includeComments (boolean, optional): Include comments (default: true)

Example:

Get details for episode 16 including transcript and comments

3. search_transcripts

Search through episode transcripts for phrases or multiple terms with flexible matching.

Parameters:

  • query (string, optional): Phrase to search for. Useful for exact-phrase lookups.

  • terms (string[], optional): Explicit list of terms to search for; combine with matchMode for logical AND/OR searches.

  • matchMode ('phrase' | 'any' | 'all', optional): How to combine query/terms. Defaults to 'phrase'. Use 'any' to match if any term is present, 'all' to require every term somewhere in the transcript.

  • limit (number, optional): Maximum episodes to return (default: 20).

  • contextLines (number, optional): Lines of context to include around each match (default: 3).

  • hostId (number, optional): Only return matches for this host ID.

  • hostName (string, optional): Only return matches for hosts whose name includes this value.

  • caseSensitive (boolean, optional): Treat terms as case-sensitive (default: false).

  • wholeWord (boolean, optional): Match whole words only (default: false).

  • maxMatchesPerEpisode (number, optional): Maximum number of excerpts per episode (default: 5).

Example queries:

Find transcripts mentioning "virtual machine"
Find transcripts where klaatu talks about bash or python
List episodes where host ID 123 mentions "encryption" and "privacy" (require all terms)

4. get_host_info

Get information about a host and their episodes.

Parameters:

  • hostId (number, optional): Host ID

  • hostName (string, optional): Host name to search for

  • includeEpisodes (boolean, optional): Include episode list (default: true)

Example:

Get information about host "klaatu" including all their episodes

5. get_series_info

Get information about a series and all its episodes.

Parameters:

  • seriesId (number, required): Series ID

Example:

Get information about series 4 (Databases series)

Fuzzy Matching

The server includes intelligent fuzzy matching for episode and host searches to handle typos and misspellings.

How It Works

  1. Exact Match First: The server always tries exact substring matching first for speed

  2. Fuzzy Fallback: If no exact matches are found, it falls back to fuzzy matching using Levenshtein distance

  3. Match Indicators: Results include indicators showing whether they're exact or fuzzy matches

Examples

Host Search:

  • Query: "klattu" → Finds: Klaatu (fuzzy match, distance: 1)

  • Query: "ken" → Finds: Ken Fallon (exact match)

Episode Search:

  • Query: "pythoon" → Finds episodes with python in the title (fuzzy match, distance: 1)

  • Query: "linx" → Finds episodes with linux (may match exactly in summary/tags, or fuzzy in title)

Distance Thresholds

  • Hosts: Maximum distance of 2 characters (handles 1-2 typos)

  • Episodes: Maximum distance of 3 characters (more lenient for longer titles)

What the AI Agent Sees

When fuzzy matching is used, results include:

  • matchType: 'exact' or matchType: 'fuzzy'

  • matchDistance: N (for fuzzy matches, indicating how many character edits were needed)

This allows AI agents to provide context to users, such as: "I found results for 'klaatu' (you typed 'klattu')"

Technical Details

The fuzzy matching uses the Levenshtein distance algorithm, which counts the minimum number of single-character edits (insertions, deletions, substitutions) needed to change one string into another.

Note: Transcript search uses regex-based matching and does not use fuzzy matching, as the flexible regex patterns already handle many variations.

Available Resources

hpr://stats

Overall statistics about the HPR knowledge base

hpr://episodes/recent

List of 50 most recent episodes

hpr://hosts/all

List of all HPR hosts with episode counts

hpr://series/all

List of all HPR series with descriptions

Data Structure

The server expects the following directory structure:

knowledge_base/
├── index.js
├── data-loader.js
├── package.json
├── hpr_metadata/
│   ├── episodes.json
│   ├── hosts.json
│   ├── comments.json
│   └── series.json
└── hpr_transcripts/
    ├── hpr0001.txt
    ├── hpr0002.txt
    └── ...

Deployment

The HTTP/SSE server (server-http.js) is designed for public deployment with graceful degradation features:

Features

  • Rate Limiting: 50 requests per minute per IP address

  • Request Timeouts: 30-second timeout per request

  • Concurrent Request Limiting: Maximum 10 concurrent requests

  • Circuit Breaker: Automatically stops accepting requests if failure rate is too high

  • Memory Monitoring: Rejects requests if memory usage exceeds 450MB

  • Compression: Gzip compression for all responses

  • CORS: Enabled for cross-origin requests

# Free tier available, $7/mo for always-on
# Auto-scaling and health checks built-in

Railway.app

# $5 free credit/month, pay-per-usage
# Scales to zero when idle

Fly.io

# Free tier: 256MB RAM
# Global edge deployment

Environment Variables

  • PORT: Server port (default: 3000)

Health Check

The server provides a health check endpoint at /health for monitoring:

curl http://localhost:3000/health

Returns:

{
  "status": "ok",
  "memory": {
    "used": "45.23MB",
    "threshold": "450MB"
  },
  "activeRequests": 2,
  "circuitBreaker": "CLOSED"
}

Development

Project Structure

  • index.js - Stdio MCP server (for local use)

  • server-http.js - HTTP/SSE MCP server (for network deployment)

  • data-loader.js - Data loading and searching functionality

  • package.json - Node.js package configuration

Extending the Server

You can add new tools or resources by:

  1. Adding new methods to HPRDataLoader in data-loader.js

  2. Registering new tools in the ListToolsRequestSchema handler

  3. Implementing tool logic in the CallToolRequestSchema handler

License

This MCP server code is released under CC-BY-SA to match the HPR content license.

The Hacker Public Radio content itself is released under various Creative Commons licenses as specified in each episode's metadata.

Credits

Contributing

Contributions are welcome! This server can be extended with:

  • Advanced search features (relevance ranking, semantic search)

  • Tag cloud generation

  • Episode recommendations

  • Audio file access

  • Web interface for browsing

Support

For issues related to:

Example Queries

Here are some example queries you can try with an MCP client:

  1. "Find episodes about Python programming from 2023"

  2. "Show me all episodes by Ken Fallon"

  3. "Search transcripts for discussions about encryption"

  4. "What is the Database 101 series about?"

  5. "Show me recent episodes about Linux"

  6. "Find episodes tagged with 'security'"

Enjoy exploring the Hacker Public Radio knowledge base!

Available Tools

5 tools
get_episodeA
Read-only

Get detailed information about a specific HPR episode including transcript if available

ParametersJSON Schema
NameRequiredDescriptionDefault
episodeIdYesEpisode ID number
includeTranscriptNoInclude full transcript if available (default: true)
includeCommentsNoInclude community comments (default: true)

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=true (results may vary). The description adds that transcript may be included if available, but doesn't disclose other behavioral details like rate limits or auth needs. It is consistent with annotations and adds moderate context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single clear sentence, front-loaded with the verb 'Get', no wasted words. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should clarify what 'detailed information' includes beyond transcript. It mentions transcript but not other likely fields (host, series, date, etc.). With siblings, it's somewhat complete but could be more specific.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter described. The description reinforces the 'includeTranscript' parameter but adds no new semantic information beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves detailed information about a specific HPR episode, including transcript if available. It distinguishes from siblings like search_episodes (which is for searching) and get_host_info/get_series_info (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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have an episode ID and want detailed info. It doesn't explicitly exclude alternatives, but the context from siblings makes it clear. A slightly more explicit 'when to use' statement would improve it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_host_infoA
Read-only

Get information about an HPR host including all their episodes

ParametersJSON Schema
NameRequiredDescriptionDefault
hostIdNoHost ID number
hostNameNoHost name (will search if hostId not provided)
includeEpisodesNoInclude list of all episodes by this host (default: true)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and dynamism. The description adds no behavioral traits beyond stating it includes episodes, which is a feature, not a behavior. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 12 words, fully front-loaded. No wasted words; every part contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and complex optional parameters, the description lacks details on return format, error handling, or fallback behavior when no parameters are given. Sufficient for simple understanding but incomplete for precise invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with clear parameter descriptions. The description's phrase 'including all their episodes' slightly reinforces the includeEpisodes parameter but adds no new semantic context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Get' with resource 'information about an HPR host including all their episodes', clearly distinguishing from sibling tools like get_episode and search_episodes. No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. The description implies usage for host info but doesn't reference sibling tools or provide contextual selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_series_infoB
Read-only

Get information about an HPR series including all episodes in the series

ParametersJSON Schema
NameRequiredDescriptionDefault
seriesIdYesSeries ID number

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds no behavioral context beyond what annotations provide, such as pagination, response format, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, efficient sentence with no redundant information. The purpose is front-loaded and the description is appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one parameter and no output schema, the description is adequate but lacks detail about what 'information' and 'episodes' entail. The openWorldHint partially compensates but the description could specify return features.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (seriesId explained as 'Series ID number'). The description does not add additional meaning, but the baseline score is 3 due to high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('HPR series including all episodes'), and the name clearly indicates series-level info. It implicitly distinguishes from siblings like get_episode (single episode) and get_host_info (host info), but does not explicitly differentiate its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives such as get_episode or search_episodes. The description does not provide any usage context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_episodesA
Read-only

Search HPR episodes by keywords in title, summary, tags, or host notes. Can filter by host, series, tags, and date range.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSearch query (searches title, summary, tags, and notes)
limitNoMaximum number of results to return (default: 20)
hostIdNoFilter by host ID
seriesIdNoFilter by series ID
tagNoFilter by tag
fromDateNoFilter episodes from this date (YYYY-MM-DD)
toDateNoFilter episodes to this date (YYYY-MM-DD)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly and openWorld hints. The description adds context about search fields and filters, aligning with annotations and providing additional clarity but not significant new behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences effectively communicate the tool's function and available filters with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given full schema coverage and clear annotations, the description is adequate for a search tool. It could be improved by mentioning the result format, but this is not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description summarizes the search and filter capabilities without adding meaning beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches episodes by keywords in multiple fields and can apply filters, distinguishing it from sibling tools like get_episode or search_transcripts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (searching episodes) compared to siblings, but does not explicitly state when not to use it or provide alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_transcriptsA
Read-only

Search through episode transcripts using phrases or multiple terms with AND/OR matching and optional host filters

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSearch phrase to find in transcripts. Combine with terms/matchMode for advanced searches.
termsNoExplicit list of terms to search for; useful when pairing with matchMode "any" or "all".
matchModeNoHow to interpret the query/terms. "phrase" (default) matches the phrase exactly, "any" matches if any term is present, "all" requires every term.
limitNoMaximum number of episodes to return (default: 20)
contextLinesNoNumber of lines of context around matches (default: 3)
hostIdNoRestrict matches to a given host ID.
hostNameNoRestrict matches to hosts whose name contains this value.
caseSensitiveNoPerform a case-sensitive search (default: false).
wholeWordNoMatch whole words only (default: false).
maxMatchesPerEpisodeNoMaximum number of excerpt matches to include per episode (default: 5).

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating safe read behavior. The description adds no further behavioral traits (e.g., return format, pagination, rate limits). It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence front-loads the primary action. No redundant information, but could be slightly more structured with bullet points or separation of concerns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, no output schema, and annotations present, the description adequately covers the core functionality but omits return format, ordering, and pagination details. It's minimally sufficient for a qualified agent with good schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal narrative linking query/terms/matchMode to 'phrases or multiple terms with AND/OR matching' and 'host filters' to hostId/hostName, but does not explain syntax or defaults beyond what schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches episode transcripts, mentions phrase/term matching with AND/OR logic and host filters. It distinguishes from siblings like get_episode (single episode) and search_episodes (likely episode-level metadata) by focusing on transcript content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (for transcript text search) but does not explicitly contrast with alternatives like search_episodes or mention when not to use. No exclusion criteria or usage context beyond the basic function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.0.0
    • First observedget_episode
    • First observedget_host_info
    • First observedget_series_info
    • First observedsearch_episodes
    • First observedsearch_transcripts

TDQS

A4/5.0
Disambiguation5/5

Each tool targets a distinct aspect: episode details, host info, series info, episode search, and transcript search. No functional overlap.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (get_*, search_*), making them predictable.

Tool Count5/5

5 tools are well-scoped for a knowledge base server, covering retrieval and search without unnecessary bloat.

Completeness5/5

The set covers the core data model (episodes, hosts, series, transcripts) with both individual lookups and search, leaving no obvious gaps for a read-only knowledge base.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables fuzzy searching and browsing of Slack messages, users, and channels via CLI or MCP server integration.
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    A read-only research MCP server that provides search and browsing tools for Hacker News, Reddit, and Product Hunt. Works with zero API keys for basic use.
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    MCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/macsplit/hpr-knowledge-base'

If you have feedback or need assistance with the MCP directory API, please join our Discord server