Infobroker
<!--
README DESIGN:
Product principle.
The README is the product — it answers three questions in under
60 seconds: what this does, why you should care, how to use it.
Readme-driven development: changes that affect the README's claims
SHALL update the README before or alongside the code change. A README
that promises something the server does not deliver is a defect.
Every numeric claim (tool count, provider count, zero-config count,
skill count) reconciles against src/index.ts, config.json, and skills/
— the validator enforces this (Numeric claims check).
Voice: Professional, confident, benefit-first. Direct address ("you").
No first-person ("we", "I", "our"). Short declarative fragments in the
tagline. Every sentence survives a reader who knows nothing about
Infobroker.
Demo: Natural-language prompts in blockquotes ("Search for..."), never
full tool names (`infobroker_search_web`). Show the reader how to
express what they want — the AI maps intent to tools. Every demo
prompt SHALL be a valid natural-language command the reader could
actually run; broken prompts are a README defect.
Structure: Hero → North Star → Quick Start → MCP Server (§3 features) →
Skills → Providers → Configuration → How It Compares → Contribute →
License → Spec. No other ordering. Canonical h2 headings are enforced
by validate-readme. A TOC listing the canonical h2 sections follows the
Hero; validate-readme enforces TOC↔heading sync.
Audience split: §2 is for developers who want to start the server.
§3 describes what users can do with it. The Skills section (§3.5)
describes the bundled client skills and instructions. §4-5 are
configuration. §6 is competitive context. §7-9 are
contributor/license/spec.
Skills section: Prose only — no tables, no blockquotes, no feature
bullet lists. Lists the six bundled skills and the workflow shapes the
orchestrator routes to, with analysis-loop as the escalation shape.
Cross-links to the skill references (pipeline-map.md, workflows.md).
No repetition. One story vector per section. Don't explain the same
concept in two places — the validator flags near-duplicate sentences.
No feature bullet lists in prose. No tables for feature descriptions.
Feature blurbs: Each h3 under §3 follows a four-beat cadence —
benefit hook, mechanics, competitive proof, closer. The
competitive-proof sentence contrasts Infobroker against the
current tool landscape without naming individual competitors; it
answers "why this beats what you're used to."
MCP server order: Features under §3 follow a research workflow —
Search → Extract → Verify → Write → Manage. New features
insert at the workflow point they serve; reorder the section
to restore the workflow after every addition or removal.
Comparison table: Three columns (Tool name | What you're used to |
How Infobroker differs). One row per competitor category, never
individual products. Prose paragraph below synthesizes the table;
it never repeats a row's content verbatim.
Hero: Exactly three elements — h1 heading, bold tagline, one prose
paragraph. No sub-headings, bullet lists, or preamble paragraphs.
The tagline uses short declarative fragments separated by periods
— never a sentence or question. Enforced maximum 200 words
(validate-readme). The tagline "One server. Every source. Research
that delivers." is the repeated refrain — it appears exactly twice,
in the Hero tagline and the comparison closing prose, and no more.
The hero paragraph closes with "Free first. Privacy always." —
distinct from the tagline. Updating any repeated line requires
updating its echo.
North Star: Single paragraph stating the Bothan Spynet metaphor and
intelligence-cycle framing. No sub-headings, lists, or blockquotes.
Maximum 100 words (enforced by validate-readme).
Tables. Exactly two tables: the Providers table (§4) and the
Comparison table (§6). No other tables. The Providers table lists
every configured provider (excluding the `native_fetch` fallback
renderer) — one row per provider, matching config.json.
Word budget. Hero ≤ 200 words. North Star ≤ 100 words. Each §3 feature
h3 ≤ 350 words. The validator's Design-limits check enforces these,
plus the tagline-refrain count, the two-table rule, the per-feature
blockquote prompt count, and the `Last updated` date.
Non-goals. The README is not an API reference, a tool catalog, a spec
document, or a changelog. The complete tool inventory lives in the
feature taxonomy (§D of infobroker.md), which the README links to.
Tool names appear in prose only as shorthand in backticks where a
feature is introduced (e.g. `manage_kb`), never as a bare list.
Validator. Rules marked "(validate-readme)" SHALL be checked by
scripts/validate-readme.ts. Other rules are enforced by author/AI
discipline. Adding an enforceable rule requires a corresponding
validator check. Tool and provider names are derived from
src/index.ts and config.json at validate time — never hardcoded.
Binary style checklist (applies to every AI edit of this file):
1. Second person ("you"), never first-person.
2. Tool names in backticks, shorthand form; full `infobroker_`
prefixes only in the design comment's "never do this" example.
3. Blockquotes only in §3 feature subsections, 2-5 natural-language
prompts each, no tool names.
4. Tagline refrain "One server. Every source. Research that
delivers." appears exactly twice (Hero + comparison closing).
5. No bullet list of features in prose.
6. Exactly two tables (Providers, Comparison), no others.
7. Every numeric claim reconciles to src/index.ts + config.json.
8. ATX headings only, no setext.
9. One story vector per section, no near-duplicate sentences.
10. "Last updated: YYYY-MM-DD." matches package.json version date.
-->
# Infobroker
**One server. Every source. Research that delivers.**
Infobroker is a multi-provider MCP server that unifies web search,
structured knowledge, academic, archive, and content-extraction APIs
behind a single tool surface. Twenty-one zero-config providers ship in the
box — search the web, look up facts, fetch articles — with nothing to
configure. Five more providers unlock with an API key or self-hosting.
A built-in corroboration engine cross-references independent sources to
separate established facts from contested claims. Bundled client skills
transform raw research into polished writing. Free first. Privacy always.
[](https://glama.ai/mcp/servers/flukeatzerocool/infobroker)
[](https://m8ven.ai/mcp/flukeatzerocool-infobroker-1q5c6g)
- [North Star](#north-star)
- [Quick Start](#quick-start)
- [MCP Server](#mcp-server)
- [Skills](#skills)
- [Providers](#providers)
- [Configuration](#configuration)
- [How It Compares](#how-it-compares)
- [Contribute](#contribute)
- [License](#license)
- [Spec](#spec)
## North Star
Infobroker is the [Bothan Spynet](https://starwars.fandom.com/wiki/Bothan_Spynet/Legends) as a tool — a decentralized intelligence
network that queries independent sources and routes results through a
single, impartial interface. It runs the intelligence cycle: **direction,
collection, processing and exploitation, analysis and production,
dissemination**. You supply the requirement and receive the report; the server
does the work between, and the knowledge base carries the feedback that closes
the loop.
## Quick Start
```sh
npx -y infobroker
```
The npm package ships its default configuration. The server resolves it from
the installed package, so no environment variable is required. Your own
overrides live at `~/.config/infobroker/config.local.json`, or at a path set
by `INFOBROKER_CONFIG_LOCAL`.
To run from a clone instead:
```sh
cd Infobroker && npm install && npm run start
```
The configuration below is written for OpenCode. Other MCP clients connect the same way — a local server command plus the instruction and skill paths — but their config keys and file locations differ, so adapt the block to your client's schema.
Add this to your OpenCode config (`~/.config/opencode/opencode.json`):
```json
{
"instructions": [
"<path-to-Infobroker>/instructions/search-preferences.md"
],
"skills": {
"paths": [
"<path-to-Infobroker>/skills",
"<path-to-opencode-config>/skills"
]
},
"mcp": {
"infobroker": {
"type": "local",
"command": ["node_modules/.bin/tsx", "src/index.ts"],
"cwd": "<path-to-Infobroker>",
"environment": {
"INFOBROKER_CONFIG": "<path-to-Infobroker>/config.json"
}
}
}
}
```
For an npm install, point `instructions` and `skills.paths` at
`node_modules/infobroker/...` and use `["npx", "-y", "infobroker"]` as the
command. On Windows, quote paths containing backslashes.
The `mcp` block starts the server; the `instructions` and `skills` blocks
are what activate the bundled client skills. Without them the skills ship
with the package but stay inert.
Most free providers work immediately; CORE needs a free API key. The keyed
providers — Exa, Tavily, Yep — unlock higher throughput and specialized
search when enabled, and a self-hosted SearXNG instance puts the search path
on infrastructure you operate:
```bash
export INFOBROKER_EXA_API_KEY="your-key"
```
Requirements: Node.js 24+.
## MCP Server
Your research backend. Seven tools, twenty-six providers, one
corroboration engine. The complete feature inventory is documented in the
[feature taxonomy](infobroker.md#d-appendix-feature-taxonomy) in the
spec. Each tool and requirement has exactly one home there, and each area's
gate column matches its requirements' declared gates.
### Unified Search
> "Search for the location of the second Death Star."
> "Find scholarly papers on hyperspace travel theories."
> "Search the latest astromech specs and show me the passages that answer: does the R2 unit pre-date the Clone Wars?"
`search_web` sends one query to every provider that can answer it. Search
across DuckDuckGo, Wikipedia, academic databases, news, code repositories —
or describe your task and the server picks the best source. Common operators
(`site:`, `filetype:`, quoted phrases) pass through to engines that support
them, a preferred language is honored where a provider allows it, and anything
the serving provider drops is reported rather than hidden. Pass an array of
queries to batch several searches in one call. Ask for a deep read and it
fetches the top results, then ranks each page's passages against your query,
so you get the specific text that answers the question instead of links. Pass
`analyze: true` and the same response carries topic terms, entity mentions,
semantic clusters, and a dated timeline derived from those results — computed
in-process, with no extra request. A query that names a measurable attribute —
attendance, population, area, elevation, a percentage, a date — resolves a
sourced `facts` entry from Wikidata or a Wikipedia infobox/table ahead of the
prose results. `include_domains` narrows a search to the sources you trust —
`restrict` returns only those hosts, `prefer` ranks them ahead without
excluding the rest — on top of the configured blocklist, and the response
reports the matched and excluded counts. When two task types are equally
supported and would reach different providers, the tool offers both instead of
guessing: you get the candidates and an empty result list, then re-issue with
`task_type`.
Failed providers fall back silently through a configurable chain so you get
results, not error messages. Other search tools lock you to one engine;
Infobroker routes every query to the right provider and keeps going when one
fails. Every tool also returns the same envelope as a machine-readable
object, so programmatic clients read fields instead of parsing text.
### Content Extraction
> "Fetch the article on the Battle of Yavin and summarize it."
> "Get the text of that page about the Death Star plans."
> "Where, in that report, does it mention the reactor core?"
`fetch_page` hands any URL to the renderer chain, which starts with Jina
Reader and renders it as clean Markdown optimized for LLM consumption. It
falls back to native HTTP when the primary renderer is slow, throttled, or
errors. Wikipedia and Internet Archive have dedicated
renderers for source-specific extraction. Ask a page a question — pass
`question` to `fetch_page` and it returns the passages that answer it, each
scored and ranked, instead of the whole document. Fetch several URLs at once
and each result keeps its own renderer, ranked passages, and top score. Pass
`raw: true` to get the page text directly, without the JSON wrapper. Long
pages are truncated to 50,000 characters by default; set `max_length` to
change the cap. Set `crawl` to walk same-origin links from a page: a crawl is
bounded by configurable page-count and depth caps, and the page-count cap
counts outbound attempts, so a page full of dead links cannot multiply
requests.
Built-in web fetchers return raw HTML; Infobroker gives you clean, readable
content from any source — ready for summarization or analysis. Fetch also
reports the page's date when it can determine one, on plain fetches, crawls,
and structured extraction alike, so you know how current your source is; on a
crawl or an extract the date comes from document metadata, so a page dated only
by a response header reports none there. When a page is paywalled, access-restricted, or
bot-blocked, `fetch_page` reports `access_blocked` and falls back to Crossref
metadata or an open-access copy for a DOI, and to an Internet Archive
snapshot when no metadata record exists.
### Citations
> "Give me BibTeX references for papers on hyperdrive field dynamics."
> "Cite the paper that first described the hyperdrive field equations."
`get_citations` searches scholarly sources and returns each reference as a formatted
BibTeX entry with its fields — title, authors, year, venue, and URL — ready
to paste into a reference list.
### Provider Intelligence
> "Which source should I use to research the Death Star's weakness?"
> "Show me all available sources and their quota status."
The server knows its own capabilities. `search_web` auto-selects the
best backend for your task, weighing capability, quota, and latency —
or routes by your intent when you ask for privacy, speed, or free-only
sources. When the automatic choice misses, pass `task_type` to force a
dispatch chain (for example `academic`), and `meta.task_type` reports the
chain that served the query. `inspect_providers` surfaces every configured
source, reports its
derived privacy posture, and drills into a single provider's uptime and error
history; a provider that has served traffic also reports its last result count,
whether the last attempt yielded `ok` or `zero`, and the consecutive
zero-result streak, so a silently drifting parser is visible before the fallback
chain is exhausted. The generated `skills/infobroker/references/provider-privacy.md`
documents query forwarding, retention, account requirements, and resale for
every provider, marking what configuration cannot establish as unknown rather
than assuming privacy. No other search MCP server gives you operational
visibility into every backend.
### Multi-Source Verification
> "Verify whether the Empire really destroyed Alderaan."
> "Find the consensus on who fired first — Han or Greedo."
`verify_claims` runs a multi-pass truth-finding loop: broad
search across your highest-authority providers — search engines,
encyclopedias, and scholarly indexes — then claim extraction,
cross-source reconciliation, and targeted follow-up for gaps, dispatched
in parallel and stopping early once the truth is pinned down. Hand it a draft
and it takes a claim list, returning one finding per distinct claim in your
order — with every input index for a repeated claim — and an explicit
`unverified` row for a claim nothing supports, rather than dropping it. Claims
corroborated across independent sources score high
confidence, weighted
by each source's authority; every source is bound to the claim it
supports, with a span locating the supporting sentence and the claim's
modality (`asserted`, `reported`, `speculative`) so a hedged source is never
rendered as flat fact. A report that repeats a hedged claim must carry that
attribution in its body. Republished wire copy and mirrors are collapsed into one source
family, so confidence counts origins, not hosts, and a secondary-only
finding is capped rather than overstated. Contradictions are surfaced with
all perspectives. Gaps trigger refined queries that broaden to the rest of
your providers. It also remembers: prior findings in your knowledge base
participate as corroborating sources before it queries the network, but a
finding is marked `confirmed` only when its confidence clears the threshold and
at least one agreeing source comes from outside your knowledge base. You get a
structured report — confirmed, contested, and unverified findings — with
source provenance, per-source claims and spans, and confidence scores. Every
other search tool returns a list of links; Infobroker finds the truth and
tells you how sure it is.
### Knowledge Base
> "Search what you already found about the Rebel Alliance fleet."
> "Ingest this article so it's cached for next time."
Every search, fetch, and corroboration run is cached; `manage_kb` checks the
cache before external providers, falling back when results aren't fresh or
relevant, and ingests, reports, or removes content. Content is age-scored,
expired on a schedule, and deduplicated by source and meaning. Retrieval runs
locally with a configurable embedding model; your content never leaves the
machine. `manage_kb` archives reports: ingest with `source_type: "report"` and
a receipt, and it returns a `report_id`. Revisit them with `manage_kb` list/get,
or write them to a local directory. `search_web` scopes recall to a named
`collection`, and `fresh: "blend"` keeps cached results beside fresh ones.
Corroboration results are also kept as claim records, one per finding, linked
to their sources' retrieval times. Cited sources are copied in as retrievable,
hashed snapshots, so a report can be rechecked after the page changes. Deep reading reports a snapshot hash and freshness tier per page;
each snapshot reports its basis (document or snippet) and truncation. An
archived report must carry a receipt, and the receipt is graded: structural
failures plus the share of claims backed by a stored document rather than a
snippet. No stored sources means ungraded, not ungrounded.
`preservation.archive: false` keeps snapshots and disables Wayback archiving,
which is bounded and overlapped with snapshot storage, so a slow capture never
delays the response.
Read them with `manage_kb` action=claims, filtered by `query` or `source_url`
and capped by `max_results` (default 8, max 50). The ledger is sealed at rest
when encryption is on.
A watchlist runner records due-topic claim deltas, retains a topic's claims
across a failed or empty result, and advances `last_run`; cron owns the
schedule. A report can carry a verification receipt: ingest claims, cited
sources, and the Source Register, which the server hashes. `verify_report`
rechecks it offline and reports
drift when the report or a source changed, unverifiable for an uncached source,
and a digest mismatch for a tampered manifest. The manifest carries report
metadata and a revision chain. `monitor-delta --receipt` revalidates a baseline
before comparing and marks a receiptless run unverified. The manifest is sealed
at rest, and encryption transitions reseal it.
### Research Pipeline
> "Research the construction of the Death Star, then draft a summary."
> "Fact-check these claims about Darth Vader's origin."
Infobroker doesn't stop at search results. Bundled client skills chain
its tools into writing pipelines, routing every request through a solved
workflow shape and the writing sub-skills until a finished document comes
out the other end. Everything lives in the repository — no external paths
or separate install. The full pipeline — the six skills, the workflow
shapes, and the escalation path — is detailed in the [Skills
section](#skills). Other search MCP servers produce search results;
Infobroker produces finished work.
### Operational Visibility
> "Show server health."
> "Hot-reload my config without restarting."
Quota counters persist to disk and survive restarts. Rate limits are
enforced per-provider, not globally. Configuration is hot-reloadable
via `reload_config` — change providers, adjust chains, or tweak
thresholds without dropping connections, or pass a `patch` to merge a
change into your user layer with a backup. `search_web` doubles as
DuckDuckGo query autocomplete. `inspect_providers` reports the server's build
health, request stats, and local state health — configuration drift,
pending migrations, backend capabilities, and update status. When something
needs your attention — configuration drift, a pending migration, or a
provider cooling down — successful tool responses carry a bounded `notices`
array with the condition and, where one exists, the fix, so a stale user
layer does not stay invisible. Any response carrying retrieved text also
carries a top-level `content_trust` marker naming that text as untrusted
external content, so an agent reading a page body can tell data from
instructions; the marker is additive and never alters a retrieved body. You always know what your search server is
doing and how much capacity remains. The `check-tdqs` gate reports each tool's
parameter counts, schema description coverage, invocation cost, and definition
size, and fails when a definition breaks the deterministic TDQS bar.
## Skills
The MCP server is one half of the product. The bundled skills are the
other. Six client skills ship in the repository and turn raw research into
finished work.
The orchestrator skill (`infobroker`) opens with a classify gate that
maps your request to a workflow shape: research-and-write, fact-check,
deep-dive, competitive evaluation, literature review, monitoring,
red-team, vetting, or gated analysis. Each shape composes the same
primitives — recall from the knowledge base, search, extract, verify,
write, validate, and cite — into its own sequence and ends with a grep-able
completion token. Every report carries a
machine-readable manifest and a graded Source Register; a validation gate
checks its sections, citations, and manifest values before delivery, and a
shared reference fixes one confidence, likelihood, and source-grade scale.
Four writing sub-skills execute the writing phases: `summarization`
condenses findings before writing, `technical-writing` drafts reports and
docs, `proofreading` polishes language, and `translation` produces
multilingual output.
The writing pipeline requires a client that loads bundled skills; without
skill loading, Infobroker provides tool-level research, not a finished report.
Gated analysis is the escalation shape. When a question is high-stakes or
decision-driving, the classify gate routes to the `analysis-loop` skill —
a disciplined path with confidence-scored findings, source-reliability
grading, and structured analytic techniques chosen by fit and named with a
rationale — rather than the lighter research-and-write route. It shares the
same primitives and Infobroker tools but runs its own gated workflow, so you
get the rigor without leaving the pipeline.
A single instruction file, `search-preferences.md`, routes your client
toward these tools: the knowledge base first, external providers only
when the cache falls short. Wire it and the skills directory into your
OpenCode config once — the Quick Start section shows the exact snippet —
and every research request follows the pipeline automatically.
Validated reports export as HTML, JSON, or CSV for reading and archiving. Write your own skill into `skills/` to add a workflow shape of your own.
The pipeline diagram lives in `references/pipeline-map.md` and the
workflow-shape definitions in `references/workflows.md`. Other search MCP
servers return links; Infobroker ships the writers that turn them into
documented answers.
## Providers
Twenty-six providers. Twenty-one work with zero configuration.
| Provider | Tier | Type | Key Required |
|----------|------|------|-------------|
| DuckDuckGo | Built-in | Web search | No |
| Jina Reader | Free HTTP | Content extraction | No |
| Wikipedia | Free HTTP | Encyclopedia | No |
| Wiktionary | Free HTTP | Dictionary | No |
| Wikidata | Free HTTP | Structured facts | No |
| OpenStreetMap | Free HTTP | Geocoding | No |
| Internet Archive | Free HTTP | Historical | No |
| arXiv | Free HTTP | Academic | No |
| Semantic Scholar | Free HTTP | Academic | Optional |
| Stack Exchange | Free HTTP | Code Q&A | Optional |
| GitHub | Free HTTP | Code search | Optional |
| CORE | Free HTTP | Open access | Required (free) |
| OpenAlex | Free HTTP | Academic | No |
| Europe PMC | Free HTTP | Academic | No |
| Crossref | Free HTTP | Academic | No |
| Hacker News | Free HTTP | News | No |
| GDELT | Free HTTP | News | No |
| SEC EDGAR | Free HTTP | Financial filings | No |
| World Bank | Free HTTP | Economic data | No |
| Marginalia | Built-in | Small web | No |
| Mojeek | Built-in | Independent index | No |
| Wiby | Built-in | Small web | No |
| Exa | Keyed HTTP | Semantic | Yes |
| Tavily | Keyed HTTP | Synthesis | Yes |
| Yep | Keyed HTTP | Web, Semantic | Yes |
| SearXNG | Self-hosted | Self-hosted search backend | Yes (self) |
Built-in providers and most free-HTTP providers are active out of the box;
CORE needs a free API key. Exa, Tavily, and Yep ship disabled; set
`"enabled": true` for those in your user layer
(`~/.config/infobroker/config.local.json` by default, or the path in
`INFOBROKER_CONFIG_LOCAL`), and export the matching key. A
keyed provider whose key is absent is excluded from dispatch, so nothing
changes for a keyless install. Self-hosted providers point at a server you run
yourself:
```bash
export INFOBROKER_SEARXNG_URL="http://localhost:8080"
```
Keyed providers also accept an ordered credential pool via
`INFOBROKER_<NAME>_API_KEYS` (comma-separated). Infobroker rotates to the
next key when one is rejected or rate-limited, and reports per-key
availability through `inspect_providers` without ever surfacing key
material.
SearXNG is the only shipped self-hosted provider, and it is optional
through and through. Nothing in the server requires it, and nothing is
bundled or installed on its behalf — SearXNG runs as a container you
operate, and Infobroker queries its JSON endpoint like any other backend.
Leave it disabled (the default) and you lose nothing: the
privacy-critical chain still serves via Mojeek and DuckDuckGo. Enable it
to control the search path: the instance you run receives each query
first and forwards it to its configured upstream engines, so disable the
engines you do not want to reach.
## Configuration
Environment variables tune a deployment. `INFOBROKER_CONFIG` overrides
the shipped default config (resolved from the installed package when unset),
`INFOBROKER_CONFIG_LOCAL` points at a user config layer,
`INFOBROKER_<NAME>_API_KEY` supplies a keyed provider's credential, and
`INFOBROKER_<NAME>_URL` points at a self-hosted provider or an alternate
renderer endpoint (`INFOBROKER_JINA_URL` for the Jina Reader).
`config.json` ships with the package and the repository and holds the
defaults: which providers are enabled, their priority in fallback chains,
rate limits, corroboration parameters, and the task-to-provider dispatch
table. Hot-reloadable via `reload_config` — edit the file and call the tool,
or pass a `patch` to merge configuration programmatically; changes take
effect without a restart. A patch is merged over your user layer as it exists
on disk when you call the tool, and a `null` value removes that key — the
supported way to clear a field your layer declares, such as a provider's
`auth_env`. A field the shipped `config.json` also declares comes back after
removal, because that declaration is the provider's own requirement; set
`auth_optional` to `true` where the provider allows a keyless use.
Your own overrides live in a separate user layer —
`~/.config/infobroker/config.local.json` by default, or a path you set via
`INFOBROKER_CONFIG_LOCAL`. An existing `config.local.json` beside the
resolved config still wins, so clone deployments keep their current layout.
The layer is preserved across updates. Values in the user layer take
precedence over the shipped defaults; anything left out falls back to
`config.json`.
`config.json` carries a schema stamp (`config_version`). If your user layer
was written for an older schema, or holds a key the current schema no longer
recognizes, the server reports the drift at startup and in every
`reload_config` response without changing your file. Apply the registered
migrations on demand by calling `reload_config` with `migrate` true: the
server first copies your layer to a timestamped `*.bak-*` file, then updates
it atomically, leaving anything it does not recognize untouched. Set
`state.auto_migrate_config` to true to apply those migrations automatically at
startup after the merged result validates; the same backup is written first.
If a user layer is invalid, the server starts on shipped defaults, leaves the
file untouched, and reports the error instead of refusing to start.
Provider entries are strict: a key outside the provider schema — for example
`result_path` where the schema expects `results_path` — makes the whole user
layer invalid instead of being ignored, so a single typo can suppress every
override in the file. The server reports the offending key and the invalid
value, and the fix belongs in `config.local.json`; a key the current schema no
longer recognizes is reported as drift rather than silently dropped.
`state.update_check` (off by default) enables an update-availability check
against the published npm package. When enabled, the check runs in the
background, caches its result for a day, and never downloads or applies an
update. The result appears in `inspect_providers` action `spec` and, when a
newer release exists, as a notice.
The knowledge base ships empty. Retrieval runs on a configurable in-process
embedding model selected by `kb.embedding_model`. By default, the store
writes to a user-scoped path (`~/.local/share/infobroker/knowledge-base`)
outside the repository, so the content you research and cache stays on your
machine and is never committed. Each deployed instance accumulates its own
store. A legacy `vector-store.json` store is migrated automatically on first
open and preserved as `vector-store.json.migrated-<timestamp>`; when encryption
is enabled the plaintext archive is removed instead. There is no legacy backend
to roll back to: recover with a key backup or rekey.
### Knowledge base encryption
Research reports and cached pages can be sensitive, and the knowledge
base stores them in a SQLite database (plus `-wal`/`-shm` sidecars) in your
home directory. Enable optional
at-rest encryption by adding a `kb.encryption` block and supplying a key:
```json
{
"kb": {
"encryption": { "enabled": true, "key_file": "~/.config/infobroker/kb.key" }
}
}
```
The key file (plain, 0600) is the most reliable source across MCP clients
and operating systems; `INFOBROKER_KB_KEY` (a 32-byte key) or
`INFOBROKER_KB_PASSPHRASE` (a passphrase) also work. Generate a key with
`openssl rand -base64 32`. Encryption protects the store and disk-saved
reports from anyone who obtains the files without the key — device theft,
backup or cloud-sync leaks, other local accounts. It does not protect
against a malicious MCP client on the same machine, or malware, which
full-disk encryption covers.
Two rules keep this safe. First, encryption is your opt-in: if the key is
missing or wrong, the knowledge base locks and reports an error rather
than touching your data — so back up the key (a forgotten key or
passphrase means the store is unrecoverable by design). Second, the server
never writes a partial file: every save is atomic, and an unrecognized or
newer store format is never overwritten.
The `manage_kb` tool's `encryption` action is the day-to-day surface for this
journey, and it never echoes secret material — `generate_key` and `backup`
return file paths, and `rekey` reads a key file rather than a raw key.
`generate_key` refuses a key-file path that already exists, so it can never
overwrite the only copy of a key.
**Enable** by generating a key, backing it up, adding the `kb.encryption`
block, and reloading; the store is encrypted in place immediately.
**Disable** by removing the block and reloading; the store is decrypted to
plaintext immediately (keep the key available during the transition so the
server can read the store to decrypt it). **Recover** a locked store with
`status` to see the state, `verify` to confirm a candidate key before
committing it, `backup` to restore a copy of your key file, and `rekey` to
move to a new key without losing content. After re-keying, point
`kb.encryption.key_file` at the new key, reload, then run `verify` again to
confirm the new key opens the store.
```
infobroker_manage_kb action=encryption operation=generate_key key_file=~/.local/share/infobroker/keys/kb.key
infobroker_manage_kb action=encryption operation=backup key_file=~/.local/share/infobroker/keys/kb.key.bak
infobroker_reload_config
```
Tool-surface key operations (`generate_key`, `backup`, `rekey`'s target)
are confined to the keys directory: `kb.keys_dir` when configured, else the
`keys` sibling of the knowledge base storage path
(`~/.local/share/infobroker/keys` by default). A path outside that
directory is refused. The `kb.encryption.key_file` *configuration* value is
operator-owned and not subject to the confinement.
Add the `kb.encryption` block to `config.local.json` before reloading to
enable, or remove it before reloading to disable. When the store is locked,
`status`, `verify`, and `rekey` remain reachable so you can recover without
first unlocking.
### Content policy
Infobroker reads the open web and caches what it retrieves, so retrieved
content is assessed against a configurable policy before it is stored (and,
in the strictest mode, before it is returned). The policy flags content
that matches heuristic categories — prompt-injection instructions,
credential phishing, malware/exploit material, and adult content — and can
consult an external assessment service when one is configured. It is on by
default in `flag` mode: flagged content is still returned to you for
legitimate research, but it is never written to the knowledge base, and
every flag is recorded in the audit trail.
```json
{
"content_policy": {
"mode": "flag",
"threshold": 0.2,
"patterns": { "prompt_injection": ["ignore previous instructions"] }
}
}
```
Modes: `off` disables assessment; `flag` (default) returns but never stores
flagged content; `block` refuses flagged content to the caller. `threshold`
tunes sensitivity (0–1, default 0.2 — a single match flags). `patterns`
extend or override the built-in categories per category name. `external_url_env`
names an environment variable holding the URL of an external assessor, and
`external_api_key_env` optionally names one holding its bearer key; when the
external service is unreachable the built-in assessment applies.
Security-relevant events — refused network targets, policy flags, config
reloads, encryption transitions, key operations, and quota exhaustion — are
appended to an owner-only audit log at `output.audit_log_path` (default
`~/.local/share/infobroker/audit.log`). Per-provider privacy posture is
generated from `config.json` into
`skills/infobroker/references/provider-privacy.md`, including whether the
declared credential makes an account necessary; the gate fails when that
document drifts from configuration.
Operational records are separate: every tool call and outbound provider
request logs its name, status, and elapsed time, never the query, URL, or
content. A multi-query search or a `verify_claims` batch writes one record
per call plus one per provider request, so a batch multiplies the volume;
`output.call_log_max_bytes` (default 2 MB) bounds the file before rotation.
Set `output.call_log` to `"stderr"` (the default), `"file"`, or
`"off"`; the file sink is owner-only and rotates at
`output.call_log_max_bytes`. `inspect_providers action=spec` reports the
session summary, and a successful response carries a `provider_cooldown`
notice while a provider is held off after a rate limit.
### Bring your own endpoint
Any HTTP search endpoint can become an Infobroker provider without
touching the source tree. Declare it in `config.local.json` as a
`generic_http` provider, then append it to a dispatch chain: `dispatch_append`
adds the slug after the shipped providers instead of replacing the chain.
```json
{
"providers": {
"my_search": {
"tier": "generic_http",
"capabilities": ["web_search"],
"enabled": true,
"priority": 20,
"endpoint": "https://api.example.com/search",
"query_param": "q",
"results_path": "data.items",
"health_endpoint": "https://api.example.com/health",
"auth_env": "INFOBROKER_MYSEARCH_API_KEY",
"field_map": { "title": "name", "url": "link", "snippet": "summary" }
}
},
"dispatch_append": { "general_web": ["my_search"] }
}
```
The server GETs `endpoint?query_param=<query>`, walks `results_path`
(dot-separated into the response JSON), and maps each result to the
common shape using `field_map`. `field_map` values are dot paths; besides
`title`, `url`, `snippet`, `published_date`, `source_type`, and
`original_source`, it accepts the scholarly keys `authors` (a string or
array), `doi`, `venue`, `abstract`, and `citation_count`. Relative result
URLs resolve against the endpoint.
Set `auth_env` to an environment variable name to send its value as
`Authorization: Bearer …`; the key never appears in configuration. For an API
that expects a different header or no scheme, set `auth_header` (default
`Authorization`) and `auth_scheme` (default `Bearer`; set `""` to send the raw
key). For example, `{"auth_header": "X-API-Key", "auth_scheme": ""}` sends the
key alone in `X-API-Key`. Set
`health_endpoint` to a query-free URL so `inspect_providers` health does
not spend a real search against a metered API — without it the probe is a
search query. A generic provider's capabilities must be `web_search` or a
search task type such as `academic`; `suggest` and `content_fetch` are not
implemented by the shared generic backend. A slug that matches a built-in
provider is rejected. Add the entry to `config.local.json` and call
`reload_config` to use it immediately.
`priority` routes the `verify_claims` pool by intent without leaving the
provider list: `privacy` restricts it to providers that do not forward queries
to third parties, `quality` orders it by configured provider priority, `speed`
orders it by recent response latency with an unmeasured provider placed after
the measured ones, and `free_only` drops the keyed and self-hosted tiers. A
list that satisfies no intent is used unchanged. It does not reorder
`search_web`, which follows dispatch-chain order.
### Per-provider status and provenance
Two optional keys tune per-provider behavior in `config.json`:
- `degraded_latency_ms` — a provider whose recent average latency exceeds
this many milliseconds is reported `degraded` by the `inspect_providers` health
action, even while reachable. A global `output.degraded_latency_ms` acts
as the fallback when a provider omits its own.
- `resells` — set `true` on aggregator/reseller backends (search engines
that surface other publishers' pages, like DuckDuckGo or
SearXNG). The server reports each result's `original_source` where the
backing API exposes one (e.g. Yep's `source` field); first-party
sources (Wikipedia, arXiv) leave it empty because the page is the
origin.
### Source quality and blocklisting
Search results are ordered by relevance, then adjusted by a configurable
source-quality weight. Primary sources (default `.gov`, `.mil`, `.edu`, and
`.int`) and domains marked trusted rank higher; domains marked low-quality
rank lower. The default weight is small enough that relevance stays
dominant. A blocklist removes a host and its subdomains before ordering and
reports the count in `meta.blocked_count`; a `*.` pattern matches subdomains
only. The blocklist applies to `search_web` results, including a
knowledge-base recall used to answer a search, and does not apply to
`fetch_page` or `verify_claims`.
```json
{
"source_quality": {
"enabled": true,
"weight": 0.15,
"primary_source_suffixes": [".gov", ".edu"],
"trusted_domains": ["nature.com"],
"low_quality_domains": ["contentfarm.example"],
"blocklist": ["spam.example", "*.tracker.example"]
}
}
```
Set `weight` to `0` to keep pure semantic ordering, or `enabled` to `false`
to disable both ranking and blocklisting.
### Hedged fallback
`search_web` and `fetch_page` fall back with a hedge instead of waiting
out a slow provider's full timeout: the primary (first-choice) provider
runs alone for a latency-derived window, then the remaining providers
race and the first result wins. The common path uses one provider call;
the hedge fires only when the primary is slow or failing. `fetch_page`
additionally prefers the primary renderer in a short grace window so a
marginally slow `jina` is not displaced by a lower-quality `native_fetch`.
A renderer whose content is an anti-bot challenge page (a CAPTCHA or
verification interstitial rather than the target page) is treated as a
failed render, so `fetch_page` falls through to the next renderer instead
of serving the challenge as content. When a `fetch_page` renderer race
settles, the losing renderer is cancelled, so it makes no further request
and spends no quota.
Tune the window with `output.hedge_enabled`, `hedge_min_delay_ms`,
`hedge_max_delay_ms`, and `hedge_grace_ms`; set `hedge_enabled` to
`false` for the sequential chain. A provider that returns a rate-limit
or anti-bot response is held in a per-provider cooldown (`output.rate_limit_cooldown_ms`)
so a burst of requests stops re-hammering it, and when a non-`general_web`
chain exhausts, the server retries the `general_web` chain before failing.
## How It Compares
| Tool name | What you're used to | How Infobroker differs |
|-----------|--------------------|-----------------------|
| Built-in `websearch` / `webfetch` | One search engine, one fetch mode, no configuration, no visibility into what backend is used | Twenty-one zero-config providers with a unified tool surface. Choose the right source for each task. Fall back automatically on failure. See every provider's status and quota. |
| Raw API calls | Manual HTTP requests, per-provider auth, per-provider response parsing, no fallback, no quota tracking | One interface for every provider. API keys configured once. Results normalized to a common shape. Rate limits and quota tracked automatically. |
| Dedicated search APIs | Pay-per-query, vendor lock-in, opaque routing | Free-first design. DuckDuckGo, Wikipedia, and nineteen other providers work with zero configuration. Upgrade paths for Exa, Tavily, and Yep. A self-hosted SearXNG to keep the front door on your own machine. |
| Other search MCP servers | Single-provider focus, no fallback, no corroboration, no writing pipeline | Multi-provider with automatic fallback. Corroboration engine cross-references independent sources. Bundled writing skills transform research into finished documents. |
| AI with built-in search | The model picks the search engine, serves stale cache, no reproducibility | You control the provider chain. Queries are reproducible. Fallback behavior is visible. The corroboration engine verifies facts across independent sources. |
Every other search MCP server asks you to pick a provider and trust it.
Infobroker gives you a fleet — and picks the right one for each task.
When a provider fails, the next one takes over without you noticing.
When a claim matters, the corroboration engine finds agreement,
contradiction, and gaps. The bundled skills close the loop from raw
research to finished writing. One server. Every source. Research that
delivers.
Last updated: 2026-11-16.
## Contribute
- **Node.js 24+.** `node --version`. Get it at
[nodejs.org](https://nodejs.org).
- `npm install && npm run typecheck`
- Bundle your own skill in `skills/` to extend the research pipeline.
- Validate README structure: `npm run validate-readme`
- **Versioning:** CalVer (`YYYY.M.D`, no leading zeros). `npm run version-bump`
stamps today's date into the package, server manifest, and version stamps so
the package, tag, and npm-published version all name the same release; update
the spec stamp and README citation alongside it. Pre-commit hooks verify
consistency. `npm run push` checks, tags, and pushes.
- MCP protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- Providers: [DuckDuckGo](https://duckduckgo.com) ·
[Jina Reader](https://jina.ai/reader) ·
[Wikipedia API](https://en.wikipedia.org/w/api.php)
Canonical origin: [git.gay/flukeatzerocool/Infobroker](https://git.gay/flukeatzerocool/Infobroker). This GitHub repository is a read-only mirror.
## License
MIT. Free to use, modify, and redistribute. The bundled client skills and
instruction files ship under the same license, so the full research pipeline
— server, skills, and documentation — is freely reusable in commercial and
open-source work alike. Third-party providers remain subject to their own
terms and API keys.
## Spec
The server is built from a single source specification, `infobroker.md`
(v2026.11.16), which defines every requirement and the gates that verify it.
Each requirement traces to an implementation file, and `npm run check`
reconciles the code, the spec, and this README so what is documented is what
the server actually delivers. The routing gate resolves every cited tool and
operation against the live schema, and requires each registered tool to be
cited at least once.
TDQS
Scored across 7 tools
Each tool targets a distinct stage of the research pipeline (search, fetch, verify, cite, KB manage, config reload, provider inspect), and the descriptions go further by naming the sibling tool to use instead for near-miss cases. Even the multi-action manage_kb and inspect_providers tools are scoped to clearly different objects (local store vs. provider backends).
All seven tools share the infobroker_ prefix and a snake_case verb_noun pattern (search_web, fetch_page, verify_claims, manage_kb, reload_config, get_citations, inspect_providers). No mixed casing or inconsistent verb styles.
Seven tools is tightly scoped for a research/infobroker server; every tool covers an orthogonal concern and no tool is redundant. Multi-action tools consolidate what would otherwise be a much larger surface.
The surface covers the full research lifecycle: discovery, retrieval, verification, citation, persistent KB CRUD with encryption, plus operational config and provider health. Minor gaps remain, such as no dedicated batch/async job management or explicit collection administration beyond the action parameters in manage_kb.