Skip to content

docs(fred): README, design doc, marketplace entry - #40

Merged
walkerhughes merged 1 commit into
fred/revisionsfrom
fred/docs
Aug 6, 2026
Merged

docs(fred): README, design doc, marketplace entry#40
walkerhughes merged 1 commit into
fred/revisionsfrom
fred/docs

Conversation

@walkerhughes

Copy link
Copy Markdown
Owner

Closes #35, and completes the stack from #30. On top of #39. No new code in src/.

This is the PR that makes the plugin installable, which is why it comes last rather than first: the stack should not advertise a server whose tools do not exist yet.

What's here

  • plugins/fred/README.md — install, credentials, the five tools, development.
  • plugins/fred/docs/design.md — the reasoning, following plugins/tastytrade/docs/design.md.
  • .claude-plugin/marketplace.json — the fred entry.
  • Root README.md — a row in the servers table, and fred in the layout tree.

What the curation buys, measured

The design doc's central table is measured against the live API, not estimated. Response sizes in characters:

Question Endpoint-wrapper baseline This server
Fed funds rate now, and its 20-year range 1 call, 694,388 chars 1 call, 4,194 chars
CPI year-over-year vs unemployment since 2015 2 calls, 27,758 chars, unaligned 1 call, 6,777 chars, one index
Find the unemployment rate series 1 call, 8,201 chars for 5 results 1 call, 1,835 chars
What did Q3 2025 GDP first print at? 1 call that 400s, then guesswork 1 call, 9 vintages collapsed to 1 revision

The first row is the argument for the whole design: 0.6% of the payload, and a better answer, because the exact 20-year minimum of 0.04 and maximum of 5.41 are in the summary rather than somewhere in 5,000 rows a model has to scan.

Two guards this repo has needed before

  • ${CLAUDE_PLUGIN_ROOT} must be bare. The :-default form is handled by env-var expansion, which does not know that variable, so the default always wins and the server launches against the user's own project directory. tastytrade carries the same test with a note that a sibling plugin shipped broken three times before it existed.
  • The marketplace entry's source must resolve to this directory. A listed plugin pointing at the wrong path fails at install with nothing useful to read.

Version ladder

The plugin version gate compares each PR against its own base, so every PR in a stack that touches shipped files needs its own bump. Applied bottom-up:

PR Version
#36 scaffold 0.1.0
#37 discovery 0.2.0
#38 observations 0.3.0
#39 revisions + calendar 0.4.0
this one 0.5.0

Nothing is installable until this PR lands, so no intermediate version ever reaches a user.

Verification

284 tests, 98% coverage, make check clean.

End to end through the real launcher, minimal PATH, real API key:

server: {'name': 'fred', 'version': '0.5.0'}
tools:  ['get_observations', 'get_release_calendar', 'get_revisions', 'get_series', 'search_series']
live:   get_observations(UNRATE,CPIAUCSL, units=yoy, start=3y)
        -> 35 dates, both series on one index, UNRATE yoy latest 2.43902

The version reported over the wire comes from plugin.json rather than a constant, so the two cannot drift.

Makes the plugin installable, which is why it comes after all five tools exist
rather than before.

The design doc's "what the curation buys" table is measured against the live API
rather than estimated. The headline row: the fed funds rate over 20 years is
694,388 chars of raw FRED payload and 4,194 from this server, and the shorter one
is the better answer, because the exact 20-year min of 0.04 and max of 5.41 are
in the summary instead of somewhere in 5,000 rows.

Also adds two guards this repo has needed before: that ${CLAUDE_PLUGIN_ROOT}
carries no :-default (the default silently wins and the server launches from the
user's own directory), and that the marketplace entry's source path resolves to
this plugin directory.

Version 0.5.0, one minor per PR in the stack, as the plugin-version gate requires.
@walkerhughes
walkerhughes merged commit 6660c93 into main Aug 6, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fred: README, design doc, marketplace entry

1 participant