{
  "name": "mondello.dev",
  "version": "1.0.0",
  "description": "Audio-addressable knowledge source for mondello.dev — agent-era blog",
  "protocolVersion": "2024-11-05",
  "usage": {
    "install": "claude mcp add mondello https://mondello.dev/api/mcp",
    "transport": "Streamable HTTP (POST JSON-RPC 2.0 to this URL)",
    "tools": [
      {
        "name": "search_cues",
        "description": "Search across every narrated post's synchronized transcript. Returns audio-addressable hits with post slug + title, matching cue text, integer start seconds, formatted M:SS timestamp, keyword-windowed snippet, and a deep-link URL that auto-seeks the audio on page load. Ideal for answering 'where does this blog discuss X?' questions with citable timestamps."
      },
      {
        "name": "list_posts",
        "description": "List every published post on mondello.dev. Returns slug, title, excerpt, publishedAt ISO date, readingMinutes, and audioDuration (M:SS when a narration exists, null otherwise). Use to discover content before fetching specific posts."
      },
      {
        "name": "get_post_markdown",
        "description": "Fetch the full Markdown content of a single post by slug, with YAML frontmatter (title, dates, tags, audio.url/duration, license, source). CommonMark-compliant. Use after list_posts or search_cues to pull a post's full text for analysis."
      },
      {
        "name": "get_site_stats",
        "description": "Return a structured overview of the entire site in one call: post count + publish range, reading minutes (total/avg/median), narration coverage + total audio seconds + cue count, top 10 tags + categories by post count, feed inventory (RSS/Atom/JSON/podcast/changelog/OPML), and the x402-gated endpoint catalog with prices. Cheaper than list_posts when you just need aggregate context."
      },
      {
        "name": "get_archive",
        "description": "Fetch the entire blog as one Markdown document — every published post concatenated with per-post YAML frontmatter + `---` separators, newest first. Ideal for bulk context window ingest (one call = whole site). Returns the full content as text; prefer list_posts + get_post_markdown when you want to reason about a subset."
      },
      {
        "name": "get_latest",
        "description": "One-call site pulse: latest post (slug, title, url, publishedAt, excerpt, tags), latest narration (postSlug, postTitle, durationSeconds, audioUrl, createdAt), latest changelog entry (id, date, title, body, permalink), and totals { posts, narratedPosts, changelogEntries }. Cheaper than composing list_posts + get_site_stats + get_changelog when you just want a freshness signal."
      },
      {
        "name": "get_changelog",
        "description": "Return the site's shipping log — 70+ entries of what has landed on mondello.dev and why, newest first. Each entry carries date, title, body (1-2 paragraphs of design rationale), tags, stable id, and permalink anchor. Supports filtering by limit (default 50, max 200), since (YYYY-MM-DD), and tag. Ideal for 'what's new on this blog since X?' questions — cheap, structured, no HTML to parse."
      },
      {
        "name": "search_all",
        "description": "Unified search across posts (tf-idf cosine), transcript cues (substring with audio deep-links), and tags (slug/label substring sorted by post count). One call, three hit types — each carries a `type` discriminator so the caller can merge-rank."
      },
      {
        "name": "get_featured_cue",
        "description": "Pick the single most-quotable cue from a post's narration via heuristic scoring (length sweet-spot, first-person reflection, sentence boundaries, salient-term mentions, penalties for intro/outro regions and dangling conjunction starts). Returns the cue + score + reasons[] (so an agent can explain *why* this line was picked) + top 3 runners-up for debugging. Deterministic."
      },
      {
        "name": "get_random_quote",
        "description": "Return one random featured cue drawn from every narrated post on the site — a single audio-addressable pull quote with a ?t=<seconds> deep-link, the source post's title + URL, and the cue's tags. Useful for 'quote of the day' surfaces, end-of-response 'one more thing to listen to' nudges, or seeding social posts. Pass `seed` for a deterministic pick (handy in tests)."
      },
      {
        "name": "get_cue_at_time",
        "description": "Given a post slug + an audio timestamp in seconds, return the transcript cue being spoken at that moment (plus the prev + next cue for context). Closes the bidirectional loop: agent searches for text → gets timestamp → replays via deep-link → asks this tool to resolve the moment back to exact words. Useful for quote-at-exact-second attribution."
      },
      {
        "name": "get_post_outline",
        "description": "Return the heading hierarchy (title + h1-h6 in document order) for a single post as a flat array of { level, text, slug, startSeconds?, words }. Lightweight discovery step before get_post_markdown — lets agents see structure and decide which sections to deep-read. When the post has narration, each heading carries an estimated audio start-second."
      },
      {
        "name": "get_related_posts",
        "description": "Combined recommendation envelope for one post: { similar (tf-idf cosine), byTag (shared-tag overlap with counts), chronological (prev + next in publish order) }. One call covers all three recommendation axes an agent might want to consider when suggesting what to read next."
      },
      {
        "name": "find_similar_posts",
        "description": "Find posts semantically similar to a given slug using tf-idf + cosine similarity over full post bodies (not just tags). Returns up to k hits with post { slug, title }, cosine score ∈ [0,1], shared salient terms (helpful for 'because you care about X, Y' labels), and resolvable URL. Smarter than tag overlap when the question is topical."
      },
      {
        "name": "list_skills",
        "description": "List every Claude Code skill for sale on mondello.dev. Returns slug, title, excerpt, price (USDC on Base mainnet via x402), and the install URL (a free shell script that handles the 402 payment + writes to ~/.claude/skills/<slug>/skill.md). Use this to discover what skills are available before fetching a preview or paying for the full content."
      },
      {
        "name": "get_skill_preview",
        "description": "Get the FREE preview of a single skill by slug — title, full price, the public preview Markdown, and the URLs to (a) the x402-gated raw download and (b) the human install script. The full skill body is NOT included; pay the price at the raw URL to fetch it. Use this to decide whether a skill is worth buying."
      }
    ]
  },
  "specs": {
    "mcp": "https://spec.modelcontextprotocol.io/specification/2024-11-05/"
  }
}