Roster

Your agent has 200 tools. Only five get to start.

Roster is a neutral, open-source, local-first tool router for AI agents. One MCP endpoint fronts your local stdio MCP servers and approved skills; your agent gets the best ≤5 tools for the task at hand — the starting five — instead of every schema at once. It learns from derived call outcomes on your machine and works with MCP clients that can launch a stdio server, including Claude Code, Codex, Cursor, and OpenClaw.

The eject promise, up front: roster eject restores every active path Roster synced for its four write clients, from backups committed before each client write. Dedicated MCP config files return byte-for-byte (comments and formatting included). Live state files the client itself rewrites, such as ~/.claude.json, restore key-level: original servers return, Roster's exact injected entry is removed, and settings or servers changed since sync survive. --force explicitly selects the pristine raw bytes. A private journal makes a multi-path eject recoverable after interruption, and topology checks refuse a moved symlink rather than writing through it.

Why

Tool schemas can consume 72% of a 200K context window before the first user query. Tool-selection accuracy collapses from 43% to ~13.6% as toolsets grow. In a 100-server live stress test, the median MCP server passed only 71% of tasks; the bottom decile passed 38%. And the haystack keeps growing: 177,000+ public MCP tools as of February 2026.

Search-based tool loading is a proven fix — Anthropic measured an 85% token cut, with accuracy going 49% → 74% — but shipped it for Claude. Roster's bet is that the fix should be neutral (every client), learned (outcomes, not just keywords), and public (a league, not a listicle).

What it is

Four parts, one product:

• The router ("the Rotation"). An aggregating stdio MCP proxy for command-backed servers. Your supported write-client configs go from N mcpServers entries to one. Default mode is transparent: a faithful passthrough — every backend tool re-exported (namespaced), with titles, annotations, execution hints, and error codes preserved — while only derived outcomes are stored locally. Opt into five mode and the agent sees two meta-tools — draft(need) returns the best ≤5 capabilities for the stated task (K configurable 1–10), call(tool, args) proxies the invocation. When a drafted tool hard-fails, Roster can attach a structured suggestion for the next-ranked equivalent (the Sixth Man — suggest-only; Roster never executes the alternate).
• The Coach. Local outcome learning. Outcome class, latency, hashes, and drift are stored on-device; raw prompts, arguments, and results are not. An opportunistic maintenance job refines routing toward the tools that work on your stack. No hosted Roster service or API key is involved.
• The League. A static generator for public MCP server rankings, fed by the open-source Combine harness. Certification binds category, task signing, and descriptions to an exact authoritative suite/version; standings rank only within that identical comparison set. Named scores use signedWilsonLb only. Artifacts are validated before a complete atomic site swap, and box-score filenames include a SHA-256 identity suffix so lossy display names cannot collide. The committed run remains unsigned pre-season data until a human signing session occurs. See docs/methodology.md.
• The Playbook. Skills (SKILL.md) are first-class alongside tools. Tree traversal and script reads are bounded and no-follow. A primary SKILL.md symlink is the deliberate exception for dotfile-managed installs: its descriptor is read with a bound and identity checks, it is always review-flagged, and it is withheld by default. Unreadable entries, unsupported file types, other symlinks, or scan-cap exhaustion likewise produce a review finding. Review-flagged skills become available only through the explicit ROSTER_ALLOW_REVIEW_SKILLS=1 operator override.

Quickstart

Initial CLI preview. The package is @npmmo/roster; the installed executable remains roster. The unrelated unscoped roster package is not this project. Publication approval and release evidence are tracked in release readiness.

For one-copy setup without a global install, including Windows commands, use the installation guide.

npm install --global @npmmo/roster
roster init       # detect clients, import supported servers, print your Day-0 receipt
roster sync       # swap N config entries for one (originals backed up first)
roster serve      # run the router
roster eject      # put every config back exactly as found (byte-for-byte for dedicated files)
roster receipt    # re-print your audit  ·  roster unquarantine <id>  # re-admit a drift-benched tool

The published CLI supports Node 22.17 or newer within Node 22.x, or 24.2 or newer. Older Windows/libuv builds cannot provide consistent file identities and are refused before local state is created; file-safety checks are not weakened to accommodate them. init needs no account or Roster API key. It prints a Day-0 receipt of clients, servers, and skills discovered, modeled per client: clients that already defer tool schemas natively, like Claude Code, are reported as such rather than credited with savings they do not need. sync currently writes Claude Code, Cursor, Codex, and OpenClaw configs and routes command-backed stdio servers only. If a selected config contains a URL-only server, unsupported server settings (such as client-specific disable/allowlist rules, cwd, or env_vars), or malformed server definitions, sync refuses before changing roster.json, backups, or the client config rather than silently discarding those settings. Explicit command, args, and string-valued env entries remain supported. If the client edits its config during sync preparation, sync refuses the observed conflict; retry when the client is idle.

Synced launchers use this installation's absolute Node and CLI paths, or the scoped package command for an npx-cache install. Re-running sync migrates older recorded launchers without importing Roster into itself.

Seven day-one utilities

The League is the show; these earn the install without it:

1. Context relief where you enable five mode — best-five serving behind a stable two-tool interface, with transparent mode as the default.
2. One roster across the four write clients — import command-backed servers from their different config formats, then point those clients at one local endpoint.
3. The Sixth Man — failover suggestions when a tool hard-fails, so one bad server doesn't kill the task. Suggest-only at launch; automatic substitution returns later, if field data earns it.
4. The local outcome record — derived outcome classes and latency support ratings and maintenance without persisting prompts, arguments, or results. The dashboard remains planned, not shipped.
5. Drift quarantine — changed capability definitions are quarantined locally, including remove/re-add cases carried through tombstones.
6. Secrets hygiene — API keys live in one place (~/.roster/roster.json, owner-only 0600, alongside the config backups that hold your original files) and are passed through to backends only. They are never sent anywhere, never written to the outcome database, and never logged — but be clear-eyed: importing a server copies its env block, so those keys are on disk, exactly as they already were in each client's own config.
7. A Coach that learns your team — local outcomes refine routing on your own stack; public-Lab prior seeding remains planned.

Privacy

• Local-first, by law. No account or Roster API key. State lives in ~/.roster/. Lexical full-text retrieval works with no model and no download, so the install is ~39 MB and Roster is useful the moment it finishes. Semantic (dense) retrieval is opt-in: roster init asks, or roster dense enable adds it later — it installs a ~385 MB local embedding runtime into ~/.roster/runtime and then fetches a model from Hugging Face in the background on first use. Decline it, or stay permanently offline, and Roster runs in lexical mode forever. Nothing is uploaded either way.
• Your content never leaves. Prompts, tool arguments, and results are never uploaded, persisted to the outcome database, or logged.
• Telemetry is OFF by default and opt-in only. roster telemetry status|on|off controls it; the published schema in docs/telemetry-schema.md defines exactly what could ever be sent — coarse outcome events only, with hard exclusions for prompts, args, results, embeddings, hostnames, and paths. Aggregates publish only past k-anonymity thresholds. Full schema: docs/telemetry-schema.md. The upload endpoint does not exist yet, so today nothing leaves your machine even if you opt in. Before launch, the OFF default gets verified by packet capture.

Status: initial CLI preview

The CLI, the public League, and hosted surfaces have separate release gates. Release readiness records the candidate evidence and remaining owner actions; passing repository tests is not a claim that every client or environment has been verified.

• Package identity: @npmmo/roster, with executable roster. Every publication requires the reviewed artifact, public-registry verification, and owner approval. The earlier @roster/cli choice was not an owned publication namespace for the authenticated release account.
• League and hosted surfaces: the League generator can build locally from the committed artifact, but named public scores remain gated on human-signed verifiers. Publishing the CLI does not publish the League, register a domain, or create a telemetry endpoint.
• What exists today: a pnpm/TypeScript monorepo (packages/router, coach, cli, combine, playbook, shared) with CI, built against the milestones in ROSTER-BUILD-HANDOFF.md. Strategy and decision records: ROSTER.md, ROSTER-STATE-AND-DECISIONS.md.
• Day-to-day build status: STATUS-FOR-MO.md · design docs: docs/.

Built with agents, reviewed by hand

Roster is developed with heavy agentic AI assistance, under written discipline: specs are amended before code, security-critical paths (eject/config rewriting, credential passthrough, telemetry redaction) are committed to line-by-line human review before launch, and no named public score ever comes from a verifier a human didn't sign. The full disclosure, the rules, and the running human-review log live at docs/PROVENANCE.md.

License

MIT.