Skip to content

v0.0.2 — contract drift cleanup

Choose a tag to compare

View all tags
@ghul0 ghul0 released this 16 May 12:41
· 12 commits to main since this release
v0.0.2
8e72473

First fully contract-compliant release of @hhc-mcp/core and @hhc-mcp/stdio. v0.0.1 was tagged but never reached npm (auth gap). v0.0.2 is the first version on the registry, with all 13 tools matching docs/read-only-tools.md.

Install

npx -y @hhc-mcp/stdio@0.0.2

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "hhc": {
      "command": "npx",
      "args": ["-y", "@hhc-mcp/stdio@0.0.2"],
      "env": {
        "HHC_BASE_URL": "https://your-fluent-site.example",
        "HHC_USER": "your-wp-username",
        "HHC_APP_PASS": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

What's in the box

13 read-only tools backed only by upstream GETs:

club_search_members, club_get_profile, club_get_my_profile, club_list_spaces, club_list_courses, club_get_feed, club_get_feed_comments, club_get_user_comments, club_get_recent_posts, club_get_recent_comments, club_get_since_summary, club_get_unread_notifications, club_search_content.

Contract conformance (vs v0.0.1)

v0.0.1 was tagged but did not publish; on review it drifted from docs/read-only-tools.md in 19 distinct ways. v0.0.2 resolves all of them across 4 review waves (PR #77).

Inputs (wave 1) — 6 tools were accepting params but silently ignoring them: get_user_comments.since, get_recent_posts.space + missing feed_base_url=feeds and order_by_type=new_activity, search_content.since, list_spaces.{include_members,member_limit}, list_courses.include_sections, get_my_profile.include_private_fields. All now wired through to upstream.

Output field naming (wave 2) — schemas leaked upstream names. Renamed per docs: message→message_text, message_rendered→message_html, short_description→short_description_text/_html (profile), cover_photo added, nested post.{id,title,permalink} and space.{slug,title} on comments, pagination.{current_page,has_more} on get_user_comments, unread_count on notifications.

Output shapes (wave 2) — get_since_summary now returns {new_posts[],new_comments[],edited_comments[],counts,scan_metadata} instead of {since,posts,comments}. search_content returns {results[].{kind,score?,matched_field,member?,post?,comment?},counts,scan_metadata}. edited_comments[] carry edit_reason.

Output sanitization (wave 2) — validateOutput in stdio now returns parsed.data so Zod .strip() is a real final sanitizer. include_private_fields semantics moved from core schema to stdio transport: schema accepts email always; stdio handler redacts unless the caller opts in.

Correctness (waves 3-4) — search_content now paginates /feeds up to scan_feed_limit (was: single page max 100), uses search=&search_in[]=post_content&per_page=100 for post search, applies a global limit cap across combined results (members → posts → comments), filters members by since on last_activity, carries the source Feed through comment hits so post/space context is preserved when include_posts=false. get_user_comments filters by since page-by-page (was: filter after limit truncation), uses ProfileCommentsResponseSchema to backfill author from envelope-level xprofile, sets pagination.has_more=true when client-side limit truncates a page with remaining items. get_recent_posts removed unsafe early-stop (created_at is non-monotonic under new_activity sort). get_since_summary.scan_metadata is plumbed from getRecentComments (was: hardcoded scanned_feeds:0).

Validation (wave 1) — query is now trimmed and rejects control characters per docs common rule.

Hard caps (wave 1) — search_content enforces a 2000-scanned-comment cap.

Tests

492 tests passing on merge (423 core + 69 stdio). Coverage gate deferred to v0.1.0.

Supply chain

Known issues

  • SBOM step in release.yml failed (@cyclonedx/cyclonedx-npm uses npm ls, which doesn't understand pnpm workspace symlinks). Will be fixed in v0.0.3. Packages were published before SBOM ran, so the failure does not affect what is on the registry.

Full review history

PR #77 went through four review waves (operator-led, all REQUEST_CHANGES). Commits on the branch: c96a275 (wave 1), d50e8ae, 2500738 (wave 2), 1c3ce74 (wave 3), 5309436 (wave 4). Squash-merged as 7666312.

Assets 2
Loading