best-mcp: events + manifest tools, and optional source - #6
Merged
Conversation
Tools-only LLM hosts had no access to the events capability and were
forced to guess the CloudEvent source. Four new tools and one relaxation:
- get_manifest: /.well-known/best (tenant-scoped via the tenants.manifest
template when the connection targets /tenants/{id}) — capability and
push-channel discovery.
- get_events: the historical log with filter/cursor passthrough — the
turn-based polling drain.
- get_event_schema: typed event payload documentation.
- sample_event_stream: bounded SSE sampling — collects until max_events/
max_seconds enforced CLIENT-side, so any conformant endpoint works;
Last-Event-ID resume supported. A turn-based host cannot hold a stream
open; this gives it a window instead.
- send_command source is now optional, defaulting to the client identity
urn:best-mcp: the commands spec defines source as the ORIGIN and forbids
routing by it alone, so requiring agents to scrape a value from schema
descriptions produced guesswork the server discards. Explicit source
remains supported for legacy source-routing dialects.
specs/transports/mcp.md mapping table and flow updated to match.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Four new tools and one relaxation in
best-mcp, closing the gap where tools-only LLM hosts (VS Code Copilot, Claude Desktop, …) could not see or consume theio.best.agents.eventscapability at all, and had to scrape a CloudEventsourcevalue out of schema descriptions.get_manifest— fetches/.well-known/bestfrom the connection host (resolving the tenant manifest via thetenants.manifesttemplate for/tenants/{id}connections). Agents finally discover declared capabilities and push channels.get_events—GET /eventswith filter/cursor parameter passthrough: the turn-based polling drain.get_event_schema—GET /events/{schema}/{version}.sample_event_stream— opens the SSE stream and collects untilmax_events/max_seconds, bounds enforced client-side so any conformant endpoint works;Last-Event-IDresume supported. A turn-based host cannot hold a stream open between turns — this gives it a bounded window, and the tool description points standing reactions at the service's own alerting commands.sourceonsend_commandis now optional, defaulting to the client identityurn:best-mcp. The commands spec definessourceas the command's origin and says servers MUST NOT route by it alone — requiring agents to read a routing value out of descriptions was legacy-dialect residue (and produced observable guesswork). Explicitsourceremains supported.specs/transports/mcp.md(mapping table, flow, CloudEvent construction) and the repo instructions updated to match.Verification
Built and driven end-to-end over stdio against a live BEST 0.9.1 endpoint (baas.dotquant.io): tenant manifest resolution, history drain with vendor cursor passthrough, bounded stream sample returning the opening frame +
lastEventId, and a default-source command envelope accepted by the server edge (rejected only by payload schema validation, as intended).🤖 Generated with Claude Code