This guide covers integrating the eggsearch MCP server into coding-agent harnesses such as codegg. It is written for harness developers, not end users. All examples use JSON code blocks; truncated values are clearly marked.
eggsearch version: see Cargo.toml for the live release number.
- Quick Start
- MCP Server Startup and Configuration
- Configuration Examples
- Legacy External-Search Provider Migration
- Tool Selection Policy
- Progressive disclosure integration
- Required Task Workflows
- Trust Boundary Rules
- Warning and Error Handling
- Evidence Bundle Handoff
- Performance and Response-Size Controls
- Agent UI/UX Guidance
- Failure and Degradation Policy
- Versioning and Compatibility
- Readiness Checklist
# 1. Start the MCP server (stdio transport)
eggsearch mcp stdio
# 2. Optionally inspect capabilities during bootstrap (diagnostic only)
# Call: provider_status({})
# Response includes: providers, code_hosts, health, server_capabilities,
# tool_capabilities, and workflow_recipes
# Agents skip this in the normal flow and start with the search primitive.
# 3. Search for code in a repo
# Call: repo_search({"query": "middleware", "host": "github", "owner": "tokio-rs", "repo": "axum", "goal": "understand"})
# Legacy profile/mode/workflow/include_* /providers/timeout_ms remain accepted but are hidden from the ordinary schema; see docs/tool-matrix.md.
# 4. Fetch a specific file
# Call: repo_fetch({"host": "github", "owner": "tokio-rs", "repo": "axum", "path": "src/routing/mod.rs", "symbol": "Router::layer", "expand_to_block": true})CodeGG's default integration remains MCP over stdio. The harness starts the server as a child process and communicates via stdin/stdout JSON messages.
For an explicitly configured persistent local server, eggsearch also supports Streamable HTTP:
eggsearch mcp serve --bind 127.0.0.1:11320 --path /mcpUse the endpoint http://127.0.0.1:11320/mcp in CodeGG's explicit remote MCP
declaration. This does not change the default stdio bootstrap. The listener is
loopback-only and GET /healthz is the identity-safe readiness check.
# Start the server
eggsearch mcp stdio
# Or specify a config file explicitly
eggsearch --config /path/to/config.toml mcp stdioDefault: $XDG_CONFIG_HOME/eggsearch/config.toml
On macOS this is typically ~/.config/eggsearch/config.toml.
[search]
mode = "live" # "live" or "off"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave", "yahoo"]
sanitize_output = true
multiquery_concurrency = 8
multiquery_provider_concurrency = 2
[search.providers]
duckduckgo = true
brave = true
startpage = true
yahoo = true
[search.exact_error]
enabled = true
max_subqueries = 6
max_error_chars = 8000
redact_sensitive_tokens = true
[fetch]
enabled = true
timeout_ms = 8000
max_bytes = 2000000
max_chars_default = 12000
max_chars_cap = 50000 # document/extraction budget and cost knob; max_chars bounds the returned-text window
redirect_limit = 5
allow_private_network = false
allow_localhost = false
include_links_default = false
sanitize_output = true
pdf_enabled = true
batch_max_items = 8
batch_max_items_cap = 20
batch_max_chars_per_item = 12000
batch_max_total_chars = 50000
batch_max_total_chars_cap = 120000
batch_concurrency = 4# HTML scraper providers (enabled by default)
default_providers = ["duckduckgo", "brave", "yahoo"]
# Individual provider toggles (all enabled unless noted)
[search.providers]
duckduckgo = true
brave = true
startpage = true
yahoo = true
mojeek = false # disabled by default
osv = true
# SearXNG instance (optional)
[search.searxng]
enabled = false
base_url = "https://search.example.com"
# API-key providers (all disabled by default)
[search.api.brave_api]
enabled = false
api_key_env = "BRAVE_API_KEY"
base_url = "https://api.search.brave.com/res/v1/web/search"
[search.api.github_code]
enabled = false
api_key_env = "GITHUB_TOKEN"
[search.api.github_issues]
enabled = false
api_key_env = "GITHUB_TOKEN"
[search.api.github_releases]
enabled = false
api_key_env = "GITHUB_TOKEN"
[search.api.gitlab_code]
enabled = false
api_key_env = "GITLAB_TOKEN"
base_url = "https://gitlab.com"
[search.api.gitlab_issues]
enabled = false
api_key_env = "GITLAB_TOKEN"
base_url = "https://gitlab.com"
[search.api.gitlab_releases]
enabled = false
api_key_env = "GITLAB_TOKEN"
base_url = "https://gitlab.com"
[search.api.gitea_code]
enabled = false
api_key_env = "FORGEJO_TOKEN"
base_url = "https://git.example.com"
[search.api.gitea_issues]
enabled = false
api_key_env = "FORGEJO_TOKEN"
base_url = "https://git.example.com"
[search.api.gitea_releases]
enabled = false
api_key_env = "FORGEJO_TOKEN"
base_url = "https://git.example.com"[search]
mode = "off"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave", "yahoo"]
[fetch]
enabled = false
[local]
enabled = true
roots = ["/Users/dev/projects/my-app"]
max_indexed_files = 5000Use case: air-gapped environments where only local workspace files are
available. repo_search will return local results only. web_search
and web_fetch will deny requests with a policy message.
For direct local file reads, call repo_fetch with
host = "workspace", owner set to the configured workspace root
directory name, and path set to the root-relative file path. The
prefer_local = true mode is different: it accepts a normal remote
locator (host, owner, repo, path) and resolves to a matching
local checkout when one is available.
[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave"]
[search.providers]
duckduckgo = true
brave = true
[fetch]
enabled = trueNo API keys required. DuckDuckGo and Brave HTML scrapers are used by default.
[search]
mode = "live"
default_max_results = 10
max_results_cap = 25
max_query_chars = 512
timeout_ms = 20000
default_providers = ["duckduckgo", "brave"]
sanitize_output = true
[search.api.github_code]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.github_issues]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.github_releases]
enabled = true
api_key_env = "GITHUB_TOKEN"
[fetch]
enabled = true
timeout_ms = 12000
max_chars_default = 20000
batch_max_items = 15
batch_concurrency = 8
[local]
enabled = true
roots = ["/Users/dev/projects"]
max_indexed_files = 100000
respect_gitignore = true[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
default_providers = ["duckduckgo", "brave"]
timeout_ms = 20000
[search.providers]
duckduckgo = true
brave = true
[fetch]
enabled = true
max_chars_default = 20000
[local]
enabled = falseNo special config is needed for security_search; OSV is enabled by default
unless config disables it. Include assess_applicability: true in requests for
version-range matching.
[search]
mode = "live"
default_max_results = 15
max_results_cap = 30
max_query_chars = 512
timeout_ms = 25000
default_providers = ["duckduckgo", "brave"]
multiquery_concurrency = 12
[search.providers]
duckduckgo = true
brave = true
[fetch]
enabled = true
max_chars_default = 25000
max_chars_cap = 75000 # document/extraction budget and cost knob (not the returned-text ceiling)
[local]
enabled = false[search.api.brave_api]
enabled = true
api_key_env = "BRAVE_API_KEY" # set this env var
[search.api.github_code]
enabled = true
api_key_env = "GITHUB_TOKEN" # set this env var
[search.api.github_issues]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.github_releases]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.gitlab_code]
enabled = true
api_key_env = "GITLAB_TOKEN" # set this env var
base_url = "https://gitlab.com" # or self-hosted instanceNever commit real keys. Always use env-var indirection.
A harness retiring its own external-search stack maps legacy provider ids to
eggsearch provider ids. The "legacy id" column lists ids that existed only in
the retired in-tree stack; it is not an eggsearch inventory, and the eggsearch
inventory is whatever provider_status reports.
This matrix is frozen: it is derived from implemented provider ids, not from
planning intent, and every row is pinned by tests/docs_provider_inventory.rs
and tests/provider_capability_contract.rs.
Disposition classes, which are not interchangeable:
| Class | Meaning |
|---|---|
routing |
Not a provider. A selection mode, not an upstream source. |
exact |
Same upstream source, same id. Results are interchangeable. |
renamed |
Same upstream source, different id. Only the spelling changed. |
equivalent |
Same provider, but a current contract replaces a deprecated one. Constraint coverage is not identical; read the notes. |
capability |
The capability survives, but no single provider stands behind the old id. The caller must choose a source. |
retired |
Deliberately removed with no replacement. The harness must delete or reject the hint. |
| Legacy source id | eggsearch provider id | Class | Disposition |
|---|---|---|---|
auto |
(no providers array) |
routing |
Send no providers field at all. An empty array is also treated as "no explicit selection", but omitting the field is the canonical form. |
duckduckgo |
duckduckgo |
exact |
Unchanged |
mojeek |
mojeek |
exact |
Unchanged (still opt-in) |
openalex |
openalex |
exact |
Unchanged |
brave |
brave |
exact |
Unchanged: the keyless HTML-scrape engine. |
brave_api |
brave_api |
exact |
Unchanged: API-key semantics. Prefer it when a key is configured. |
exa |
exa |
exact |
Unchanged; opt-in credentialed |
tavily |
tavily |
exact |
Unchanged; opt-in credentialed |
wikipedia |
wikipedia |
exact |
Retained as a keyless provider |
arxiv |
arxiv |
exact |
Retained as a keyless provider |
pubmed |
pubmed |
exact |
Retained as a keyless provider with an optional NCBI key |
hn_algolia |
hn_algolia |
exact |
Retained as a keyless provider |
github repository discovery |
github_repositories |
renamed |
Same upstream GitHub repository search, renamed to avoid collision with the code/issues/releases engines. Distinct from github_code, github_issues, and github_releases. |
serpapi |
serpapi |
exact |
Current SerpApi Google Search contract; opt-in credentialed |
kagi |
kagi |
equivalent |
Not contract-identical. eggsearch uses the current Search API v1 (POST /api/v1/search, Authorization: Bearer, workflow: "search"). The legacy v0 endpoint is deprecated and is never used. Only data.search is read, so a news workflow is unavailable here, and there is no language field. See the constraint notes below. |
google_news (RSS) |
none | retired |
Retired with no replacement provider (see below). The news capability survives as capability via intent: "news". |
There is no capability-class row whose provider is an interchangeable
substitute for the retired id. google_news is the only non-exact retirement,
and it has no stand-in provider: news is reached by declaring an intent and, if
source control matters, naming a provider that natively advertises news support.
Rules for the retiring harness:
- Never remap a legacy id silently. Unknown ids are rejected by
resolve_providerswith a typed error; that rejection is the signal to fix the caller, not to substitute a different provider. wikipedia,arxiv,pubmed,hn_algolia, andgithub_repositoriesare disabled by default and are never members ofdefault_providers. Enabling them in[search.providers]makes them routable but does not add them to default fan-out; select them per request withproviders: ["<id>"].pubmedandgithub_repositorieswork without any credential. An optionalNCBI_API_KEYorGITHUB_TOKENonly raises upstream rate limits and never gates routing.- arXiv results are subject to a shared minimum-interval request gate; repeated arXiv calls in one process are spaced out rather than issued concurrently.
serpapiandkagiare opt-in credentialed providers. They are enabled only through[search.api.<id>]with anapi_key_env;[search.providers].<id>does not enable an API-key provider and neither id ever joinsdefault_providers. Select them per request withproviders: ["serpapi"]orproviders: ["kagi"]. A missing or empty key produces a provider-scopedmissing_api_keyskip for that provider only, and a quota response produces a provider-scoped rate-limited failure with health cooldown. It never causes a global search failure.- Constraint truth for the two migrated providers differs from the legacy
contract and is documented in
docs/provider-setup.md:serpapinatively enforces safe-search, language (hl), and region (gl). It does not enforce freshness (upstreamtbsvalue syntax is undocumented), domain filters, news, or result timestamps, so those stay local approximation; news must go to a native-news provider.kaginatively enforces safe-search, freshness/date-range (filters.after/filters.before), region (filters.region), domain filters (inline lens), and result timestamps. It has no language field, and eggsearch only reads thedata.searchcollection, so a news workflow is not used.
- Kagi is billed separately from a Kagi subscription and its API terms bind the integrating operator: results may be used in your own applications (including forwarding them to an AI model), must not be stored, indexed, or resold as a feed, and rate limits must not be circumvented. eggsearch's Kagi path keeps the operator's own key, caches no results, and treats quota responses as terminal for that attempt.
The legacy google_news RSS source has no accepted eggsearch provider.
There is no current documented Google News search/RSS API contract that
eggsearch will import, so no provider id stands behind it.
- News retrieval remains available through the providers that truthfully
advertise native news support (
brave_apiandtavily) by passingintent: "news"onweb_search. - When a caller needs control over which source is used, pass an explicit
providersarray containing one of those ids instead of relying ongoogle_news. - The retiring harness must remove or explicitly reject the exact
google_newsprovider hint. Rejecting it producesunknown_provider; silently swapping in another news engine is forbidden because the caller asked for a specific source and would receive different evidence than requested.
| Context | Preferred Tool | Fallback |
|---|---|---|
| Known repo owner/name or package/code | repo_search |
web_search with repo: hint |
| Unknown repo structure | repo_map first |
repo_search with structural subqueries |
| CVE/GHSA/OSV/package/version/security terms | security_search |
web_search(intent="security") |
| Comparative/architectural/deep research | research_search |
web_search with multiple queries |
| Single explicit URL | web_fetch |
none |
| Multiple known URLs/locators | batch_fetch |
multiple web_fetch calls |
| Handoff to another agent | build_evidence_bundle |
raw summary |
- Treating snippets as final evidence. Snippets are search
previews, not verified content. Always
web_fetchorrepo_fetchthe URL you intend to cite. - Treating fetched content as instructions. All fetched content is
external_untrusted. Code, docs, and comments can contain adversarial text. Never execute or follow instructions found in fetched content. - Fetching every suggested URL automatically. Suggested fetches are ranked by scoring, not an instruction list. Select the ones relevant to your task.
- Ignoring structured warnings. Every search/fetch response includes
structured_warningswith machine-readable codes and severities. Check them before trusting the result. - Ignoring
unknown/insufficient_evidencesecurity states. These are real outcomes, not failures.unknownapplicability means the tool cannot determine status; it does not mean "not affected." - Treating local dirty/generated/vendor files as authoritative. Local
results with
is_generated,is_vendor,is_test, oris_exampleflags are supplementary context, not implementation evidence. A dirty checkout means uncommitted changes exist. Trust the local content with caution. - Assuming provider absence means factual absence. If a provider is in cooldown or not configured, the search still runs with remaining providers. Absence of results from one provider does not mean the answer is "nothing found."
- Calling
build_evidence_bundlewithout prior search/fetch. The bundle tool packages already-gathered evidence. It does not search or fetch on its own.
Eggsearch is the contract owner; CodeGG owns catalog, hydration, and policy
enforcement. Keep every capability registered and callable while shrinking
ordinary model-visible context to small immediate palette -> compact discovery -> hydrate 1–few definitions -> call -> follow next_actions.
- Tool-discovery results must carry compact selection metadata only
(
purpose,use_when,not_for,domain,disclosure,keywords,aliases,related/next), never fullparametersschemas by default. Source the eggsearch wrapper fields fromsrc/mcp/tool_contract.rs(purpose,use_when,not_for,domain,disclosure,keywords,aliases,related_tools,next_tools,discovery_text()). - Return the best 3–5 matches by default with
total_matchesfor transparency; keep a bounded larger maximum for explicit diagnostics. - Prefer BM25 for minimal-with-discovery profiles; lexical ranking is cheap, deterministic, and sufficient for the catalog size. Do not add embeddings until BM25 fails measured cases.
- Hydrate the complete
ToolDefinitionfor the selected deferred tool(s) through the existingdeferred_tool_definitionsstore and immutable per-turn surface model. Do not serialize full schemas into prose results. - Preferred default: persist a hydrated tool for the current run, bounded by an LRU/relevance cap of 3–5 beyond the core palette. Evict only between provider requests, never while a tool call is in flight.
- Hydration is monotonic: it can only expose a tool already in the
policy-allowed discoverable set. It must never bypass denied tools,
model-disabled tools, plan mode, missing backend state, parent capability
ceilings, or hidden disclosure. Raw
mcp__eggsearch__*tools stay hidden behind stable native wrappers.
- Parse canonical
next_actions(tool,reason_code,priority1–5,input_template,source_ids) and retain target names plus argument templates in structured results.sanitize_next_actions()drops unknown tools, empty reasons, and over-limit entries; harnesses must apply the same filter. - After a successful call, mark high-priority
next_actionstargets as eligible for immediate hydration on the next model request without another discovery round trip:web_search→web_fetch,batch_fetch;repo_search→repo_fetch,repo_map,batch_fetch;research_search→web_fetch,repo_fetch,batch_fetch,build_evidence_bundle;security_search→web_fetch,batch_fetch,build_evidence_bundle. - Treat next actions as hints, not forced execution. Filter every target through the same policy as tool discovery; ignore malicious or unknown names.
- Ordinary coding:
web_search,repo_search, optionallyweb_fetchdepending on measured frequency/context cost. - Research role:
research_search,repo_search, plus selected fetch/evidence tools. - Security-review role:
security_searchplus only the fetch/evidence tools required by the workflow. - Do not auto-expose every research/evidence wrapper to specialist roles when evaluation shows hydration from next actions is cheaper.
- Prefer native
structuredContent; keep the legacy text fallback for older servers. ValidateoutputSchemawhen practical, distinguish MCP tool-levelisError=true(repairablecode+ boundedrepair) from transport/protocol failure, and retain stable structured data before display clamping. - Cache
tools/listby the FNV-1a content fingerprint (tool_fingerprint()covers names, descriptions, annotations, input/output schemas, and canonical discovery metadata) plus the server version, not tool count. Apply hydration state after retrieving a cached base surface. Seearchitecture/codegg-contract.mdsections 0–0.1 and 4 for the stable shapes.
This is the primary codegg flow for repository investigation. Hosts may
inspect provider_status(recipe_detail = "summary") once during bootstrap
or when provider availability itself is in question; it is diagnostic, not a
normal first research step. Agents start with the task-appropriate primitive
below.
Step 1: repo_map({ host, owner, repo })
-> root layout, important files, important directories
-> local_checkout field if matching local git repo exists
Step 2: repo_search({ query, host, owner, repo, goal = "understand" })
-> grouped source cards (SourceFiles, Issues, Releases, etc.)
-> next_actions with priority-1 fetch suggestions
-> suggested_fetches with ranked URLs
Step 3: repo_fetch({ host, owner, repo, path, symbol, expand_to_block })
-> source content with code context (imports, enclosing symbol)
-> code_span with deterministic span_id for cross-referencing
Step 4: batch_fetch({ items: [selected suggested locators] })
-> bounded parallel fetch of selected evidence
-> per-item trust markers
Step 5: build_evidence_bundle({ goal, sources, fetches })
-> deterministic bundle_id, source_links, trust_summary, gaps
Example transcript:
// Step 1: Map the repo
// -> repo_map({ "host": "github", "owner": "tokio-rs", "repo": "axum" })
// Response (abbreviated):
{
"host": "github",
"owner": "tokio-rs",
"repo": "axum",
"important_files": [
{ "path": "Cargo.toml", "kind": "manifest" },
{ "path": "README.md", "kind": "readme" },
{ "path": "CHANGELOG.md", "kind": "changelog" }
],
"important_directories": [
{ "path": "src/", "kind": "source_root" },
{ "path": "examples/", "kind": "examples" },
{ "path": "tests/", "kind": "tests" }
],
"local_checkout": {
"root": "/Users/dev/projects/axum",
"branch": "main",
"dirty": false,
"workspace_id": "abc123"
},
"suggested_fetches": [
{ "url": "https://raw.githubusercontent.com/tokio-rs/axum/main/README.md", "reason": "Project readme", "priority": 1 }
]
}// Step 2: Search for code (canonical goal; legacy profile/mode/workflow/include_*
// remain accepted but hidden)
// -> repo_search({
// "query": "Router::layer middleware",
// "host": "github",
// "owner": "tokio-rs",
// "repo": "axum",
// "goal": "understand"
// })
// Response (abbreviated):
{
"query": "Router::layer middleware",
"groups": [
{
"kind": "SourceFiles",
"label": "Source Files",
"results": [
{
"id": "src_a1b2c3d4e5f6a7b8",
"stable_id": "src_f1e2d3c4b5a69780",
"url": "https://github.com/tokio-rs/axum/blob/main/src/routing/mod.rs",
"title": "axum/src/routing/mod.rs",
"snippet": "pub fn layer<L>(self, layer: L) -> Router<...>",
"trust": "external_untrusted",
"metadata": {
"source_kind": "source_file",
"domain": "github.com",
"rank_reasons": ["rrf_multi_provider", "intent_match"]
},
"quality": {
"confidence": "high",
"relevance": "exact",
"authority": "maintainer"
},
"code_evidence": {
"source_role": "implementation",
"evidence_confidence": "exact",
"matched_symbol": "Router::layer",
"provider_text_match": true
}
}
],
"truncated": false
}
],
"next_actions": [
{
"tool": "repo_fetch",
"reason_code": "inspect_top_source",
"priority": 1,
"input_template": {
"host": "github",
"owner": "tokio-rs",
"repo": "axum",
"path": "src/routing/mod.rs",
"symbol": "Router::layer",
"expand_to_block": true
},
"source_ids": ["src_a1b2c3d4e5f6a7b8"]
}
],
"suggested_fetches": [
{
"url": "https://raw.githubusercontent.com/tokio-rs/axum/main/src/routing/mod.rs",
"reason": "Implementation: Router::layer",
"group": "SourceFiles",
"priority": 1,
"source_id": "src_a1b2c3d4e5f6a7b8"
}
],
"structured_warnings": [],
"routing_decision": {
"selected_providers": ["duckduckgo", "github_code"],
"degraded": false
}
}// Step 4: Fetch the specific symbol
// -> repo_fetch({
// "host": "github",
// "owner": "tokio-rs",
// "repo": "axum",
// "path": "src/routing/mod.rs",
// "symbol": "Router::layer",
// "expand_to_block": true
// })
// Response (abbreviated):
{
"locator": { "host": "github", "owner": "tokio-rs", "repo": "axum", "path": "src/routing/mod.rs" },
"text": "pub fn layer<L>(self, layer: L) -> Router<...> {\n ...\n}",
"line_start": 42,
"line_end": 58,
"browser_url": "https://github.com/tokio-rs/axum/blob/main/src/routing/mod.rs",
"raw_url": "https://raw.githubusercontent.com/tokio-rs/axum/main/src/routing/mod.rs",
"permalink_url": "https://github.com/tokio-rs/axum/blob/abc123def/src/routing/mod.rs",
"raw_permalink_url": "https://raw.githubusercontent.com/tokio-rs/axum/abc123def/src/routing/mod.rs",
"trust": "external_untrusted",
"trust_markers": {
"text_sanitized": true,
"control_chars_removed": 0,
"injection_hits": 0
},
"selected_span": {
"line_start": 42,
"line_end": 58,
"selection_kind": "SymbolDefinition",
"confidence": "Exact"
},
"code_context": {
"language": "rust",
"imports": ["use tower::ServiceBuilder;", "use tower_layer::Layer;"],
"enclosing_symbol": "impl<S> Router<S>",
"enclosing_symbol_kind": "impl"
},
"code_span": {
"span_id": "span_a1b2c3d4e5f6a7b8",
"language": "rust",
"line_start": 42,
"line_end": 58,
"symbol_name": "Router::layer",
"symbol_kind": "function",
"source_id": "src_a1b2c3d4e5f6a7b8",
"fetch_id": "fetch_f1e2d3c4b5a69780"
}
}// Step 1: Search with canonical debug goal (legacy mode/profile remain accepted)
// -> repo_search({
// "query": "error[E0308]: mismatched types - expected `String`, found `i32`",
// "host": "github",
// "owner": "tokio-rs",
// "repo": "axum",
// "goal": "debug"
// })
//
// The planner generates error-aware subqueries preserving the exact
// phrase, extracting the error code (E0308), and targeting docs/issues.
// Sensitive tokens (local paths, API keys) are redacted.
// Response includes:
// - groups: ErrorDocs, Issues, Releases, SourceFiles
// - error_context: { parsed_parts: { error_code: "E0308", phrase: "..." }, redactions_applied: [...] }
// - structured_warnings: [ { code: "ExactErrorPhraseMatch", severity: "Info" } ]
// - next_actions: [ { tool: "web_fetch", reason_code: "fetch_official_docs", priority: 1 } ]
// Step 2: Fetch official error docs or relevant issue
// Select the highest-priority suggested fetch from the response.
// Step 3: Bundle evidence for handoff
// -> build_evidence_bundle({ goal: "debug E0308 mismatched types", sources: [...], fetches: [...] })// Step 1: Security search with applicability (canonical include set; legacy
// include_* booleans remain accepted)
// -> security_search({
// "query": "axum",
// "ecosystem": "crates.io",
// "package": "axum",
// "version": "0.7.0",
// "include": ["kev", "defensive_guidance"],
// "assess_applicability": true,
// "dependency_files": ["Cargo.lock"]
// })
// Response includes:
// - vulnerabilities: [ { id, severity, affected_ranges, patched_ranges, ... } ]
// - applicability: [ { status: "not_affected", confidence: "high", advisory_ids: [...] } ]
// - remediation_actions: [ { category: "Upgrade", description: "..." } ]
// - security_evidence_summary: { total_vulnerabilities, highest_severity, has_authoritative_source }
// - groups: AuthoritativeAdvisories, VendorAdvisories, PackageAdvisories, ...
// - structured_warnings: [ { code: "kev_match", ... } ]
// Step 2: Fetch primary advisory
// web_fetch the advisory URL from suggested_fetches[0]
// Step 3: Bundle
// -> build_evidence_bundle({ goal: "security triage for axum 0.7.0", sources: [...], fetches: [...] })Key fields to inspect:
applicability[].status:affected/not_affected/unknown/insufficient_evidenceapplicability[].confidence:high/medium/lowvulnerability_metadata.severity: CVSS severityvulnerability_metadata.kev: whether in CISA KEV catalogsource_quality.has_authoritative_source: Tier 1 source present
// Step 1: Research with goal scaffolding (canonical goal/include; legacy
// workflow/include_* remain accepted)
// -> research_search({
// "query": "axum vs actix-web for high-performance REST API",
// "research_domain": "software_architecture",
// "goal": "compare",
// "depth": "standard",
// "compare_targets": ["axum", "actix-web"],
// "include": ["counterpoints", "primary_sources"],
// "desired_source_types": ["benchmarks", "official_docs"]
// })
// Response includes:
// - claims: [ { id, text, claim_type, confidence, supporting_source_ids, conflicting_source_ids } ]
// - conflicts: [ { id, topic, side_a_source_ids, side_b_source_ids } ]
// - evidence_gaps: [ { kind: "no_benchmark_source", message: "...", recommended_actions: [...] } ]
// - source_quality: [ { source_id, source_class, quality_signals, is_stale } ]
// - groups: OfficialDocs, Benchmarks, DesignDiscussions, Counterpoints, ...
// - workflow_context: { dimensions, coverage, gaps }
// - next_actions: [ { tool: "web_fetch", reason_code: "fetch_counterpoint", priority: 1 } ]
// Step 2: Fetch counterpoint or benchmark source
// web_fetch the URL from next_actions[0].input_template.url
// Step 3: Fetch primary docs
// web_fetch the URL from the OfficialDocs group suggested_fetches
// Step 4: Bundle
// -> build_evidence_bundle({ goal: "axum vs actix-web comparison", sources: [...], fetches: [...] })Key fields to inspect:
claims[].confidence:high/medium/low/unknownconflicts[].topic: what the disagreement is aboutevidence_gaps[].kind:no_primary_source,no_benchmark_source, etc.source_quality[].quality_signals:primary_source,reproducible_benchmark, etc.workflow_context.gaps: missing coverage dimensions
Prefer local results only when a matching checkout exists, is clean enough, and is not solely generated/vendor code.
Step 1: repo_search with host/owner/repo
-> local results appear with trust = "local_trusted"
-> inspect local_repo_match.match_confidence (exact/strong/weak)
-> inspect is_generated, is_vendor, is_test, is_example flags
Step 2: repo_fetch(prefer_local = true)
-> resolves to local filesystem when a matching checkout exists
-> returns trust = "local_trusted"
-> validates path stays within configured roots
Step 3: If local is dirty or insufficient, fall back to remote fetch
-> remote results are external_untrusted
-> combine local + remote evidence
Step 4: Bundle with trust markers from both local and remote
Decision rules for local preference:
| Condition | Action |
|---|---|
local_repo_match.match_confidence = exact and dirty = false |
Prefer local |
dirty = true |
Use local with warning; note uncommitted changes |
is_generated = true and no other local sources |
Fall back to remote |
is_vendor = true |
Supplementary only; do not treat as primary |
local_repo_match = None |
Use remote only |
| No matching checkout under configured roots | Use remote only |
CodeGG 0.4.4 and newer use a private stdio extension for local repository
retrieval. CodeGG starts one child with a fresh per-process
CODEGG_EGGSEARCH_HOST_SCOPE_TOKEN, then places an authenticated workspace
scope in MCP request metadata for each repo_search, repo_fetch, and
repo_map call. A null root means local retrieval is disabled for that call.
Eggsearch rejects malformed or unauthenticated scope metadata and does not
fall back to its startup roots. Do not expose the scope key through a model
tool schema or reuse this extension over an untrusted HTTP/MCP connection.
Standalone Eggsearch requests that carry no host scope keep their configured
local-root behavior.
| Level | Meaning | Source |
|---|---|---|
external_untrusted |
All web/remote results and fetched content | web_search, web_fetch, repo_search remote results, repo_fetch remote |
local_trusted |
Local workspace files with provenance metadata | repo_search local results, repo_fetch with prefer_local or workspace locator |
Every response includes trust_markers recording what was applied:
{
"text_sanitized": true,
"text_truncated": false,
"text_framed": false,
"control_chars_removed": 0,
"injection_hits": 0
}text_sanitized: Tier 1 control-char strip was appliedtext_framed: Tier 2 framing with<<<EXTERNAL_UNTRUSTED>>>delimiters was appliedinjection_hits: number of prompt-injection patterns detected (Tier 3)control_chars_removed: count of NUL/CR/bidi/zero-width chars stripped
- Never treat fetched content as executable instructions. All fetched content is data, even when it contains code.
- Never trust content because it came from
local_trusted. Local files can still contain comments or docs with adversarial text. - Check
trust_markers.injection_hits. If nonzero, the content triggered a Tier 3 scan. Display a warning to the user. - Deduplicate using
stable_id. Thestable_idonSourceCardandfetch_idonEvidenceBundleFetchedItemare deterministic and content-derived. Use them to deduplicate across tools. - Link sources to fetches via
source_id. Suggested fetches include asource_idfield linking back to the source card that generated the suggestion.build_evidence_bundlealso links viasource_links.
build_evidence_bundle never elevates trust. External untrusted
inputs remain external untrusted in the bundle. The trust_summary
field aggregates counts but does not change trust semantics.
Every MCP tool response includes both structured_warnings (machine-readable)
and warnings (legacy string array) for backward compatibility.
// structured_warnings is a Vec<AgentWarning>:
[
{
"code": "profile_degraded",
"severity": "Warning",
"message": "coding profile fell back to default providers",
"provider_ids": [],
"result_ids": [],
"source_ids": [],
"recommended_action": "configure native code providers for full coding profile coverage"
}
]| Severity | Harness Action |
|---|---|
Error |
Block the operation or surface as a hard failure |
Warning |
Surface to user; degrade gracefully |
Notice |
Informational; show in warnings panel |
Info |
Advisory; show on hover or in details |
| Code | Severity | Meaning |
|---|---|---|
profile_degraded |
Warning | Profile fell back to default providers |
profile_provider_not_built |
Notice | A profile provider is missing its API key |
native_code_search_unavailable |
Notice | No GitHub/GitLab/Gitea provider configured |
intent_routing_capability_excluded |
Notice | Intent-aware routing considered a preferred provider but it does not declare the capability the derived intent requires, so it was not added |
freshness_unenforced |
Notice | Freshness requested but no provider enforces it |
date_range_unenforced |
Notice | Exact date range requested but no provider enforces it |
language_unenforced |
Notice | Language hint requested but no provider enforces it |
region_unenforced |
Notice | Region hint requested but no provider enforces it |
domain_filters_local |
Notice | Domain filters applied locally to result URLs, not provider-natively |
safe_search_unenforced |
Notice | Safe search requested but not enforced |
kev_match |
Warning | CVE found in KEV catalog |
version_match_unavailable |
Notice | Affected version could not be determined |
applicability_not_exploitability |
Notice | Applicability is metadata-only, not runtime analysis |
source_quality_low |
Notice | Only low-tier sources found |
MCP tools return Result<serde_json::Value, ToolError> via the single
map_tool_result() seam in src/mcp/tools/common.rs. Success uses native
structuredContent with a text fallback. Repairable semantic failures are
MCP tool errors (isError: true) with a stable code
(invalid_semantic_value, conflicting_arguments,
capability_unavailable, provider_unavailable, policy_denied,
budget_invalid, locator_invalid, manual_interaction_required,
upstream_failed, plan_mismatch, document_unavailable) and a bounded
repair { field, accepted[], suggested_value }. Only uninterpretable
invocation shapes are JSON-RPC invalid_params; server faults are
internal_error. The harness should:
- Display the error message to the user.
- Check if partial results are still available (e.g.
repo_searchreturns groups even when some providers fail). - Surface
providers_failedandrouting_decisionin diagnostics. - Never silently swallow errors.
Bundle evidence before handing off to:
- A manager/reviewer agent
- A security review agent
- A documentation agent
- Any agent that needs to inspect gathered evidence without re-searching
// 1. Gather evidence via search tools
// 2. Fetch selected URLs via fetch tools
// 3. Bundle:
{
"goal": "understand axum router middleware architecture",
"sources": [
{
"id": "src_a1b2c3d4e5f6a7b8",
"url": "https://docs.rs/axum/latest/axum/struct.Router.html",
"title": "Router - axum",
"providers": ["duckduckgo"],
"trust": "external_untrusted",
"metadata": { "source_kind": "official_docs", "domain": "docs.rs" }
}
],
"fetches": [
{
"source_id": "src_a1b2c3d4e5f6a7b8",
"url": "https://docs.rs/axum/latest/axum/struct.Router.html",
"text": "pub struct Router<S = ()> { ... }",
"truncated": false,
"trust": "external_untrusted"
}
]
}
// Response (abbreviated):
{
"bundle_id": "bundle_9f8e7d6c5b4a3210",
"goal": "understand axum router middleware architecture",
"sources": [
{
"source_id": "src_a1b2c3d4e5f6a7b8",
"url": "https://docs.rs/axum/latest/axum/struct.Router.html",
"trust": "external_untrusted"
}
],
"fetched_items": [
{
"fetch_id": "fetch_1a2b3c4d5e6f7890",
"source_id": "src_a1b2c3d4e5f6a7b8",
"url": "https://docs.rs/axum/latest/axum/struct.Router.html",
"truncated": false
}
],
"source_links": [
{
"source_id": "src_a1b2c3d4e5f6a7b8",
"fetch_id": "fetch_1a2b3c4d5e6f7890",
"link_reason": "url_match"
}
],
"trust_summary": {
"external_untrusted_count": 1,
"local_trusted_count": 0,
"total_injection_hits": 0
},
"provider_summary": {
"providers_used": ["duckduckgo"],
"per_provider_counts": [
{ "provider_id": "duckduckgo", "count": 1 }
]
},
"gaps": [],
"limits": {
"max_sources": 50,
"max_fetched_items": 20,
"max_total_chars": 100000,
"sources_truncated": false,
"fetched_items_truncated": false,
"total_chars_exceeded": false
}
}| Field | Default | Cap |
|---|---|---|
max_sources |
50 | 200 |
max_fetched_items |
20 | 100 |
max_total_chars |
100,000 | 500,000 |
When limits are exceeded, the bundle is truncated with a warning. Check
limits.sources_truncated, limits.fetched_items_truncated, and
limits.total_chars_exceeded.
- Inspect
source_linksto understand source-to-fetch relationships. - Check
trust_summaryfor aggregate trust levels. - Review
gapsfor missing evidence categories. - Do not re-fetch already-fetched URLs unless freshness is required.
- Treat all evidence as untrusted data, not verified facts.
| Tool | Field | Default | Cap |
|---|---|---|---|
web_search |
max_results |
10 | 50 (max_results_cap) |
web_fetch |
max_chars (returned-text window; also accepted as max_length) |
12,000 | 50,000 (max_chars_cap document/extraction budget and cost knob) |
batch_fetch |
max_chars (per item) |
12,000 | No separate hard cap; bounded by total budget |
batch_fetch |
max_total_chars |
50,000 | 120,000 |
batch_fetch |
items count | 8 | 20 |
repo_fetch |
max_chars |
12,000 | 50,000 |
repo_search |
max_results |
10 | 50 |
repo_search |
max_per_group |
4 | 10 |
web_fetch also accepts start_index for offset and question or prompt
for focus as wire compatibility aliases; the canonical field names remain the
documented ones.
| Field | Default | Purpose |
|---|---|---|
multiquery_concurrency |
8 | Global max in-flight subquery jobs |
multiquery_provider_concurrency |
2 | Per-provider max concurrent jobs |
batch_concurrency |
4 | Max concurrent fetches in batch_fetch |
| Tool | Field | Default |
|---|---|---|
| Search | timeout_ms |
8,000 |
| Fetch | timeout_ms |
8,000 |
| Batch | timeout_ms |
Uses the per-item fetch timeout |
- Set
max_charson fetch calls to limit the returned-text window; the document is still extracted atmax_chars_cap. - Set
max_resultson search calls to limit result count. - Use
include_links = false(default) on fetch to skip link extraction. - Use
metadata_onlyextract mode onweb_fetchto get metadata without body content. - Use
response_detail: "compact"for ordinary search and fetch,"standard"for specialist research or security work, and"diagnostic"for troubleshooting. If omitted, the full schema profile defaults todiagnosticand the compact profile tobrief.provider_statusis diagnostic-only;build_evidence_bundlereturns the same content in every mode. - Store full
structuredContentinternally and inject only the selected projection into model-visible context; never discard stable IDs, trust markers, warnings, or retrieval status when compacting display.
Display structured warnings grouped by severity. For each warning, show:
- Severity badge (Error / Warning / Notice / Info)
- Warning code (e.g.
profile_degraded) - Human-readable message
- Affected provider IDs, result IDs, or source IDs (when present)
- Recommended action (when present)
Group source cards by source_kind and trust level. Display:
- Title and domain
- Trust badge (
external_untrusted/local_trusted) - Quality confidence (if present): high / medium / low / unknown
- Source kind label (official_docs, source_repository, etc.)
code_evidencesource_role and matched_symbol (when present)
Display next_actions as selectable actions, not automatic
executions. Each action card should show:
- Target tool name
- Reason code as a label (e.g. "Inspect top source")
- Priority indicator (1 = most productive)
- Source IDs it relates to
For security_search applicability results, display verdict chips:
- Affected (red): status =
affected - Not affected (green): status =
not_affected - Unknown (yellow): status =
unknown - Insufficient evidence (gray): status =
insufficient_evidence
Include confidence level and advisory IDs.
Display evidence_gaps as a checklist:
- Gap kind as a label (e.g. "No primary source found")
- Recommended action as a follow-up step
- Affected claim IDs for traceability
For local results, display flags in the evidence panel:
is_generated: generated file indicatoris_vendor: vendor/third-party indicatoris_test: test file indicatoris_example: example file indicatoris_config: configuration file indicatorlocal_repo_match.match_confidence: exact / strong / weak- Dirty state badge when
dirty = true
When code_span is present on a fetch response:
- Display
span_idfor cross-referencing - Link to
permalink_urlfor source view - Show
symbol_nameandsymbol_kindas labels - Show language badge
For evidence bundle handoff:
- Export: serialize
EvidenceBundleas JSON for subagent input - Import: deserialize and display
sources,fetched_items,trust_summary, andgaps - Show bundle ID for traceability
- Link source IDs to their original search results
Each failure case should map to a user-visible status, not a silent failure.
| Failure | Response | Harness Behavior |
|---|---|---|
| Provider unavailable | providers_failed in response, partial results |
Show degraded badge; results from remaining providers are still valid |
| API key missing | routing_decision.skipped_providers with reason_code: "not_built" |
Show "API key not configured" notice; suggest configuration |
| Live mode disabled | web_search denies with policy message |
Show "Offline mode" status; suggest enabling [search].mode = "live" |
| Safe search unenforced | structured_warnings with safe_search_unenforced |
Show notice; results may not be filtered |
| Freshness unenforced | structured_warnings with freshness_unenforced |
Show notice; results may be stale |
| Request deadline exceeded | telemetry.deadline_exceeded = true, subqueries_interrupted/subqueries_skipped |
Show timeout warning; partial results may still be valid |
| Fetch truncated | text_truncated = true on fetch response |
Show "Content truncated" notice; offer to re-fetch with higher max_chars |
| PDF unsupported | Error: pdf_disabled (or pdf_not_compiled_in in a source build without the feature) |
Show "PDF extraction not enabled"; suggest enabling pdf_enabled in config |
| Local workspace mismatch | No local_repo_match on local results |
Fall back to remote; inform user no local checkout was found |
| Local workspace dirty | local_repo_match with dirty state |
Show warning; local results may contain uncommitted changes |
| Research evidence gaps | evidence_gaps in response |
Display gap checklist; offer to fetch missing sources |
| Security applicability unknown | applicability.status = "unknown" or insufficient_evidence |
Show "Cannot determine applicability" status; suggest fetching advisory directly |
| All providers fail | Empty results with error warnings | Show "Search failed" with error details; suggest retrying or checking network |
routing_decision.degraded = true: profile fell back to defaultsrouting_decision.partial = true: some profile providers skippedtelemetry.deadline_exceeded = true: request timed outproviders_failed: list of provider IDs that failed entirely
Never treat partial results as total failure. If groups or source cards are present, they are valid evidence from the providers that succeeded.
- With Mode Off, an enabled local workspace, and
include_local = true,repo_searchsearches configured local roots only. It does not call remote providers or package resolvers. - If local search is disabled, unavailable, or excluded by
include_local,repo_searchreturns a policy denial. It does not fall back to remote search. web_searchandsecurity_searchremain denied in Mode Off.
These changes break existing harnesses:
- Removing fields from any response type
- Renaming serialized enum variants (e.g. changing
"source_file"to"source_file_v2"inSourceKind) - Changing ID algorithms without a version bump (e.g. changing the
FNV-1a hash of
SourceKey) - Changing default trust semantics (e.g. marking local results as
external_untrustedby default) - Changing warning severities for existing
WarningCodevalues - Changing recipe IDs or removing recipes
- Changing reason codes on
AgentNextActionorFetchRankReason - Changing
provider_statusdefault detail behavior (e.g. requiringrecipe_detailwhere it was previously optional)
These changes do not break existing harnesses:
- Adding optional fields to response types (serde
skip_serializing_if) - Adding new
WarningCodevariants (harnesses should handle unknown codes gracefully) - Adding new
FetchRankReasonvariants (existing fallback behavior preserved) - Adding new recipes (harnesses ignore unknown recipe IDs)
- Adding new
source_kindvalues (harnesses should have a default handling for unknown kinds) - Adding new
AgentNextAction.reason_codevalues (harnesses treat unknown reasons as informational) - Adding new
SecurityRemediationCategoryorSecuritySourceClassvariants
- Treat unknown enum variants as
"unknown"or skip them. Never hard-fail on an unrecognized string value. - Treat missing optional fields as absent. All optional fields
use
skip_serializing_if = "Option::is_none". - Use
stable_idfor cross-tool deduplication, notid. Theidis a random UUID per response. Thestable_idis deterministic and content-derived. - Check
WarningCodevalues programmatically when possible. The 58 stable snake_case variants are the contract. Themessagefield is human-readable and may change. - Do not depend on field ordering. JSON fields are unordered.
- Handle partial responses gracefully. A search may return some groups empty and others populated.
Before shipping codegg integration, verify:
- Documentation complete: the deep docs set exists and covers configuration, safety, tool routing, recipes, and the response contract
- Examples are schema-valid or clearly abbreviated: every JSON
example either matches the current MCP schema or is marked
(abbreviated)/(truncated) - CI covers offline verification:
cargo test --features mockpasses with all integration and corpus tests - Local workspace policy is explicit: decision rules for local preference are documented (see "Local Workspace Investigation")
- Security output is defensive-only:
security_searchoutput provides evidence and guidance, not exploit instructions - Recipes/next-actions usable without hardcoded prompt prose:
codegg can discover recipes via
provider_statusand follownext_actionsfrom search responses - Evidence bundles preserve enough state for subagents:
build_evidence_bundleoutput includessource_links,trust_summary, andgapssufficient for a receiving agent to continue work without re-searching - Generic non-codegg MCP clients remain supported: all tools, types, and responses are generic. No codegg-specific fields or behavior exist in the server
- Trust semantics documented:
external_untrustedvslocal_trustedare defined and the harness handles both - Warning codes documented: the 58 stable
WarningCodevariants are the contract for programmatic handling - Configuration examples provided: minimal, generic, coding, security, research, and API-provider configs are documented
- Failure modes mapped: every known failure case has a user-visible status, not a silent failure
| Entity | Prefix | Example |
|---|---|---|
| Source card | src_<16hex> |
src_f1e2d3c4b5a69780 |
| Fetch result | fetch_<16hex> |
fetch_1a2b3c4d5e6f7890 |
| Suggested fetch | suggested_<16hex> |
suggested_9f8e7d6c5b4a3210 |
| Batch item | batch_<16hex> |
batch_a1b2c3d4e5f6a7b8 |
| Repo locator | loc_<16hex> |
loc_f1e2d3c4b5a69780 |
| Document | doc_<16hex> |
doc_1a2b3c4d5e6f7890 |
| Document chunk | chunk_<16hex> |
chunk_9f8e7d6c5b4a3210 |
| Code span | span_<16hex> |
span_a1b2c3d4e5f6a7b8 |
| Evidence bundle | bundle_<16hex> |
bundle_9f8e7d6c5b4a3210 |
IDs are FNV-1a 64-bit hashes with a versioned input prefix
(eggsearch-id-v1\0). URL canonicalization normalizes scheme, strips
www., removes default ports, strips fragments, and normalizes
percent-encoding before hashing.
| Tool | Primary Use | Trust |
|---|---|---|
web_search |
General metasearch with intent/freshness hints | external_untrusted |
web_fetch |
Bounded extraction of one HTTP(S) URL | external_untrusted |
batch_fetch |
Bounded batch fetch over explicit URLs/locators | external_untrusted |
provider_status |
Capability discovery, recipe catalog, health | local_trusted |
repo_search |
Structured repo evidence with grouped bundles | external_untrusted + local_trusted |
repo_fetch |
Structured repo file fetch by locator | external_untrusted + local_trusted |
repo_map |
Repository structure discovery | external_untrusted + local_trusted |
security_search |
Security retrieval with normalized advisory metadata | external_untrusted |
research_search |
Research evidence with claims/conflicts/gaps | external_untrusted |
build_evidence_bundle |
Package evidence for multi-agent handoff | preserves input trust |
| Recipe ID | Purpose | Key Tools |
|---|---|---|
generic_web_lookup |
General web search and fetch | web_search, web_fetch |
documentation_api_lookup |
Authoritative docs and API references | web_search(intent="docs"), web_fetch |
repository_investigation |
Code, issues, releases in a repo | repo_map, repo_search(goal="understand"), repo_fetch, batch_fetch |
exact_error_investigation |
Debug compiler/runtime errors | repo_search(goal="debug"), web_fetch |
security_package_triage |
Vulnerability lookup and applicability | security_search, web_fetch |
dependency_upgrade_research |
Changelogs, migration guides, breaking changes | repo_search, research_search |
architecture_deep_research |
Multi-source comparison and decisions | research_search(goal="compare"), web_fetch |
local_workspace_investigation |
Local source file investigation | repo_search(include_local=true), repo_fetch(prefer_local=true) |
Each recipe's support status (available, partial, unavailable)
is evaluated against the current provider configuration at runtime.
Call provider_status(recipe_detail = "summary") to check.
Negotiate 2026-07-28 when supported (server/discover, stateless request metadata); keep the legacy initialize fallback for older servers. Prefer structuredContent over parsing JSON from text blocks, validate outputSchema when practical, distinguish tool-level isError (repairable code + bounded repair) from transport/protocol failure, and cache deterministic tool definitions by content fingerprint rather than count.