auxiliar-mcp: Instructions file for Claude Code

auxiliar-mcp — eval-backed discovery MCP for the auxiliar.ai gateway

This file is the single source of truth for what this repo is right now. Diarize from the code, not from memory — if this file disagrees with the source, the source wins; fix this file in the same change.

What this is

An MCP (stdio) server published to npm as auxiliar-mcp and to the MCP registry as io.github.auxiliar-ai/auxiliar-mcp. It runs in an agent's tool loop (npx auxiliar-mcp) and answers one question well: "which web-access provider is best for this job?" — from measured public benchmarks, not vibes.

It is the discovery half of the auxiliar.ai story — the gateway is one API key for 24 search / scraping / browser-automation / voice providers with upstream keys injected server-side; this MCP tells an agent which of those to call and why, with the numbers and their run dates attached.

Scope today (v0.23.0): discovery only. The MCP does not execute provider calls yet — it returns the executable route (https://api.auxiliar.ai/{provider}/{native-path} + Authorization: Bearer <key>) for the agent to call directly. In-loop execution (web_search, scrape, extract, crawl, … routed by the same rankings) is the v1.0 goal — see Roadmap in README.md.

Commands

npm install
npm run build            # rm -rf dist && tsc && copy src/data/*.json → dist/data && chmod +x dist/server.js
npm test                 # tsx test.ts — unit + an end-to-end stdio round-trip against the built server
npm run dev              # tsc --watch
npm run update-fallback  # refresh src/data/evals-fallback.json from https://auxiliar.ai/evals.json
npm run check-versions   # assert package.json / server.json / server.ts versions agree (prepublish gate)

There is no separate type-check step and no lint — npm run build (tsc) is the type-check. Run npm test before considering a change done; it boots the compiled dist/server.js over stdio, so it only passes if the build is real.