Grounded Synthesizer MCP Server

Grounded Synthesizer (reference)

This is a runnable reference implementation of the Stringer Grounded Synthesizer, a research service that returns extractive quotations with citations from verified public sources and refuses a topic it cannot ground. It mirrors the caller-observable surface of the hosted service at synthesis.getstringer.app and holds nothing back that a caller can see.

The boundary rule is the one stated in the worker header: a behaviour belongs here when an unauthenticated caller can observe it from outside. The bearer-gated admin stats route, the Durable Object funnel counters, the caller hashing, and the provider cost rate card stay out.

What the reference runs on

Node.js 20 or newer. The Worker is dependency-free and runs with no API keys and no external state, because the default research provider is a fixture-backed stub. That is the point: a stranger can clone the tree and watch the grounding and the refusal end to end without holding a single paid key.

git clone <this repository>
cd synthesizer-public
node --test test_discovery.mjs test_worker.mjs

To run it as a Worker locally, use Wrangler 4 (npx wrangler dev). No secret setup is required; the free allowance is held in process for the reference and is documented as such in wrangler.toml.

Hosted endpoints (the service this documents)

• MCP: https://synthesis.getstringer.app/mcp
• MCP tool: synthesize_intelligence
• REST: POST https://synthesis.getstringer.app/v1/synthesize
• REST alias: POST https://synthesis.getstringer.app/v1/execute
• Discovery: /.well-known/mcp.json, /server.json, /llms.txt, /llms-full.txt, /robots.txt, /sitemap.xml

The first three calls are free, total, with no signup and no claim header. The allowance does not reset. After that, a brief synthesis costs USD 0.10 and a deep synthesis costs USD 0.25, both paid through x402 v2 USDC on Base (eip155:8453). An unpaid call after the allowance is exhausted returns HTTP 402 with the accepted payment requirement in PAYMENT-REQUIRED and the tier price in X-402-Price-USD.

Grounding contract

• A brief synthesis requires at least 2 distinct verified sources.
• A deep synthesis requires at least 3 distinct verified sources.
• Every claim is an extractive quotation with a source URL and a character offset.
• GROUNDED: the quotation checks passed.
• REFUSED_UNVERIFIED_CLAIMS: fewer than the required verified sources, or a quote failed verbatim verification.
• SOURCE_EXTRACTION_FAILED: a named source could not be fetched or extracted.

The refusal is the product's whole claim. The test harness observes the grounded case and the refusal case red before making each green, so neither path can pass on a test that has never failed.

Swapping the stub for a real provider

The research provider is an injectable seam. synthesizeGroundedReport takes a provider argument, and the fetch handler reads env.researchProvider. The default is createFixtureProvider(), which searches a fixed corpus of three source documents and never makes a network call.

A real provider implements the same two methods:

{
  async search(query, numResults, domainsFilter) {
    // Return [{ url, title }] from your search backend.
  },
  async extract(url) {
    // Return { ok: true, document: { url, title, markdown, via } } on success, or
    // { ok: false, source_url: url, stage, reason } on failure.
  },
}

Wire one in by exporting it on the Worker environment, for example with an Exa search key and a Firecrawl scrape key held as Worker secrets. The reference never hard-codes a provider's unit cost and never names the hosted service's margin internals; the seam is the only thing a reader needs to change.

REST

curl -i https://synthesis.getstringer.app/v1/synthesize \
  -H 'Content-Type: application/json' \
  --data '{"topic":"Base network USDC settlement","depth":"brief"}'

Free responses carry X-Stringer-Access-Tier: free and X-Stringer-Free-Remaining. The fourth call returns HTTP 402. See openapi.json and RECIPES.md for the full flow.

MCP

Streamable HTTP at https://synthesis.getstringer.app/mcp. Clients must send both application/json and text/event-stream in Accept. The server implements initialize, ping, tools/list, and tools/call for synthesize_intelligence.

Test

node --test test_discovery.mjs test_worker.mjs
python3 -m py_compile client_sdk.py

License

MIT. See LICENSE.