Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
5477a67
plan: register standalone MCP local-inference efficiency workstream
dbowm91 Oct 30, 2026
bf3a35f
feat: add compact MCP profiles and brief outputs
Oct 30, 2026
02a8af6
fix: keep brief failure summaries within budget
Oct 30, 2026
d983fa5
docs: close compact MCP advertisement milestone
Oct 30, 2026
5daec80
docs: close brief projection and record LM Studio gate
Oct 30, 2026
776f8ca
fix(mcp): advertise compact research argument values
Oct 30, 2026
1608fe9
docs(plans): record LM Studio corrective qualification status
Oct 30, 2026
54c0a1d
docs(plans): record M004 live requalification
Oct 30, 2026
7082d78
docs(plans): record serial gate stall
Oct 30, 2026
755008c
fix(mcp): preserve brief document text within budget
Oct 30, 2026
de69f1d
fix(mcp): expose compact security workflow goals
Oct 31, 2026
e40c8b4
docs(plans): close M005 and hosted M004 gate
Oct 31, 2026
e580e13
docs(plans): record LFM3 LM Studio trials
Oct 31, 2026
a2bda32
docs(plans): record LM Studio token permission probe
Oct 31, 2026
1490a16
docs(plans): record authenticated LM Studio MCP acceptance
Oct 31, 2026
3bd46b1
docs(plans): reconcile M003 LM Studio acceptance
Oct 31, 2026
a339cce
test(local): stabilize mode-off workspace search fixture
Oct 31, 2026
43ca0c9
docs(plans): record M003 hosted requalification
Oct 31, 2026
6dc63d5
fix(mcp): clarify compact direct fetch guidance
Oct 31, 2026
74442ca
docs(plans): close standalone MCP M006
Oct 31, 2026
fe677ff
fix(mcp): retain compact schema references
Oct 31, 2026
772a073
fix(mcp): expose browser rendering in compact schema
Oct 31, 2026
808f896
docs(plans): close compact schema correctives
Oct 31, 2026
5b5e644
docs(plans): record repeated small-model research trial
Oct 31, 2026
6f67a9a
docs(plans): close small-model qualification
Oct 31, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ on:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:

permissions:
contents: read
Expand Down Expand Up @@ -51,13 +52,27 @@ jobs:
- name: Check all features on Windows target
run: cargo check --locked --all-features --target x86_64-pc-windows-msvc
macos-portability:
name: macOS local filesystem portability
name: macOS canonical verification and local filesystem portability
runs-on: macos-15
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable snapshot 2026-09-28
with:
toolchain: "1.89"
components: rustfmt, clippy
- name: Run canonical verification
run: make ci
env:
GITHUB_TOKEN: ""
GH_TOKEN: ""
GITLAB_TOKEN: ""
CODEBERG_TOKEN: ""
GITEA_TOKEN: ""
FORGEJO_TOKEN: ""
SOURCEGRAPH_API_KEY: ""
BRAVE_API_KEY: ""
SEMANTIC_SCHOLAR_API_KEY: ""
NVD_API_KEY: ""
- name: Test unsupported symlink following behavior
run: cargo test --locked --no-default-features --test property_local_fs_extended -- safe_open_follow_symlink_is_unsupported
- name: Test host-scoped workspace root canonicalization
Expand Down
20 changes: 18 additions & 2 deletions architecture/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ falls back to `default_config_path()` otherwise, then delegates to

## Section / Field Map

Root type `AppConfig` holds four sections: `search`, `fetch`,
`local`, `egress`. Each section field on `AppConfig` carries
Root type `AppConfig` holds five sections: `search`, `fetch`,
`local`, `egress`, `mcp`. Each section field on `AppConfig` carries
`#[serde(default)]`, so an omitted table inherits production defaults.
Within a section, only fields with their own `#[serde(default = ...)]`
are optional: every `[fetch]`, `[local]`, and `[egress]` field is
Expand Down Expand Up @@ -166,6 +166,22 @@ environment variable. Raw passwords are never a config field, and
binary built without the `egress` feature fails validation instead of
being silently ignored.

### `[mcp]` — `McpSection`

| Field | Type | Default | Purpose |
|-------|------|---------|---------|
| `schema_profile` | `McpSchemaProfile` | `full` | `full` advertises the existing complete schemas; `compact` keeps all ten tool names while shortening descriptions and input schemas for context-heavy direct MCP clients |
| `brief_max_chars` | `usize` | `8000` | Maximum serialized character count for brief MCP responses, bounded to 512–32000 |

The compact profile is process-wide presentation configuration, shared by
stdio and loopback HTTP. It does not restrict tool execution or change
argument validation. Extra accepted properties remain callable. Compact
advertisement omits `outputSchema` metadata; tool responses continue to use
the same handlers. Omitted `response_detail` remains `diagnostic` under
`full` and becomes `brief` under `compact`; explicit per-call values win.
The default `full` profile keeps the existing advertisement and response
behavior unchanged.

---

## Provider Resolution
Expand Down
21 changes: 17 additions & 4 deletions architecture/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,23 @@ struct EggsearchServer {

Construction (`EggsearchServer::new`) builds the `#[tool_router]` router once, then decorates every entry via `apply_contract_metadata()` and freezes the result. `tool_definitions()` clones the frozen list; `tool_fingerprint()` returns the frozen FNV-1a content hash. Nothing is recomputed per call.

`build_server()` reads `[mcp].schema_profile` once when constructing the
server. `full` is the default and leaves the decorated list unchanged.
`compact` projects only advertised tool copies: all ten names and required
arguments remain, optional input fields and prose are reduced, extra accepted
properties stay allowed, and output schemas are omitted. The request router,
Serde argument types, validation and execution policies are shared. The
profile is presentation configuration, never a permission or dispatch gate;
the profile-specific serialized definitions produce a distinct fingerprint.

`ServerHandler` implementation:

- `get_info()` advertises `ServerCapabilities` with tools enabled, implementation `eggsearch` + crate version, and `EGGSEARCH_INSTRUCTIONS`.
- `list_tools()` returns the frozen decorated list. It touches `self.tool_router` only to keep the router linked; the payload comes from `advertised_tools`.

`EGGSEARCH_INSTRUCTIONS` carries global rules only: external content is untrusted data, search discovers while fetch inspects explicitly selected targets, start with the task-appropriate search primitive (never `provider_status`), specialist tools only when their domain semantics apply, one URL per `web_fetch` with `batch_fetch` for fan-out, follow `next_actions`, `build_evidence_bundle` packages without searching/fetching/summarizing. Tool-specific selection guidance lives in `tools/list` descriptions and schemas, sourced from `tool_contract.rs`.

`build_server()` (`mod.rs`) is the single factory both transports share: `ServerState::build(config)` wrapped in `EggsearchServer::new`. Tool registration, contract metadata, schemas, provider construction, and policy behavior exist in exactly one place.
`build_server()` (`mod.rs`) is the single factory both transports share: `ServerState::build(config)` wrapped in `EggsearchServer::new`, which reads the schema profile from the same immutable config. Tool registration, contract metadata, schemas, provider construction, and policy behavior exist in exactly one place.

---

Expand Down Expand Up @@ -124,7 +133,10 @@ Registration lives in `server.rs`; behavior lives in `tools/`; semantics live in
| `research_search` | Multi-source evidence discovery with grouped bundles, no synthesis | `query`, `depth` (`quick`/`standard`/`deep`), `domain`, `goal`, `include` (`counterpoints`, `primary_sources`, `recent_discussion`, `security_considerations`) | `MetadataSearchAdapter::research_search` |
| `build_evidence_bundle` | Deterministic packaging of already-selected evidence for handoff | `goal`, `sources`, `fetches`, `include_unfetched_sources`, `max_sources` (default 50, cap 200), `max_fetched_items` (default 20, cap 100), `max_total_chars` (default 100000, cap 500000), `response_detail` (accepted, identity-preserving) | Pure local: `meta::evidence_bundle::build_evidence_bundle`; no adapter, no fetch, no network |

All search/fetch tools except diagnostic-only `provider_status` accept optional `response_detail` (`compact`/`standard`/`diagnostic`, default `diagnostic`).
All response-bearing search/fetch tools accept optional `response_detail`
(`brief`/`compact`/`standard`/`diagnostic`). Omitted detail is
`diagnostic` in the `full` schema profile and `brief` in `compact`; explicit
per-call values win. `provider_status` remains diagnostic-only.

### Per-tool notes

Expand Down Expand Up @@ -243,13 +255,14 @@ Tool behavior modules carry unit coverage in-file plus the shared `tools/tests.r

## Projection: `ResponseDetail` and Identity-Preserving Bundles (`projection.rs`)

`ResponseDetail` (`Compact` / `Standard` / `Diagnostic`, default `Diagnostic`) is parsed case-insensitively (`parse_raw`) with a stable error for unknown values. Canonical typed responses are built first, then projected to JSON at the MCP boundary via the central `project(tool, value, detail)` function — structured values are never truncated before host capture.
`ResponseDetail` (`Brief` / `Compact` / `Standard` / `Diagnostic`) is parsed case-insensitively (`parse_raw`) with a stable error for unknown values. Canonical typed responses are built first, then projected to JSON at the MCP boundary. `full` defaults to diagnostic; opt-in `compact` defaults to the new `brief` projection. An explicit detail always wins.

- `diagnostic` — full observability payload, passthrough with no added keys.
- `standard` — specialist research/security default surface. Keeps full `retrieval_summary`, `conflict_metadata`, `workflow_coverage`, `evidence_role_summary`, `capability_enforcement`, and fetch/cache metadata; summarizes only `routing_decision` (→ `routing_summary`) and `telemetry.routing_decision`.
- `compact` — ordinary agent operation. Trims excerpts to 1 per card, replaces `routing_decision` with `routing_summary`, replaces `retrieval_summary`/`conflict_metadata` with `retrieval_status`/`conflict_indicator`, drops `workflow_coverage`/`telemetry`/`document`/`links`, strips per-vulnerability `references`/`details`, caps `repo_map` entries at 50. Every projection stamps `response_detail` plus an explicit truncation marker (`projection_excerpts_trimmed`, `projection_entries_truncated`, `links_omitted_in_compact`).
- `brief` — applies compact safety reductions, then retains identity, status, trust, warnings, applicability and citation fields using explicit allowlists. Content strings remain intact when the serialized response fits the configured `[mcp].brief_max_chars` budget; only oversized responses progressively clip strings at UTF-8 character boundaries before complete result records are omitted from the tail with `returned_count`, `omitted_count`, and `output_truncated`. Oversized applicability lists use an `applicability_summary` with affected, not-affected, unknown, total and omitted counts; provider failures expose `providers_failed_summary` when records are omitted. Omitted batch failure records retain their indexes in `failed_member_indices`. Text plus overlapping focus chunks are avoided through the existing compact fetch projection. The structured result and text fallback are both brief; callers request `diagnostic` for the full diagnostic payload.

The suite asserts `compact < standard < diagnostic` and that compaction never erases failure-vs-absence state, trust/injection markers, conflict/applicability semantics, truncation evidence, or stable IDs.
The suite measures diagnostic/standard/compact/brief serialized characters across the 15-case retrieval-quality corpus and asserts that brief never erases failure-vs-absence state, trust/injection markers, security applicability, PDF coordinates, truncation evidence, failed batch members or stable IDs. The sparse corpus report is descriptive; a separate nontrivial fixture enforces the 30% byte reduction target.

Per-tool reducers (`projection.rs`):

Expand Down
6 changes: 3 additions & 3 deletions architecture/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Use behavioral suite names. Historical phase-suite names are retired; do not int
| `provider_capability_contract` | Native-capability enforcement matrix (native versus local filtering), inventory counts, required-credential posture, default-fan-out exclusion, engine-builder reachability |
| `provider_workstream_regression` | Provider inventory, capability descriptors, URL dedup with stable IDs |
| `structured_local_code_intelligence` | Structured parsing, definition ranking, regex fallback, budgets, repo-map enrichment |
| `mcp_tool_contract`, `mcp_schema_slimming`, `mcp_2026_protocol`, `mcp_projection` | Registry parity, schema size budgets, structured error contract, response-detail projection |
| `mcp_tool_contract`, `mcp_schema_slimming`, `mcp_2026_protocol`, `mcp_projection` | Registry parity, full/compact schema budgets, structured error contract, bounded brief and response-detail projection |
| `fetch_safety` | URL validation and SSRF prevention at the fetch boundary |
| `forge_adapter` | Forge endpoint validation, redirect policy, URL construction from the resolved ref (`resolved_ref_name`) |
| `local_workspace_integration`, `inventory_freshness`, `retrieval_attempt_ledger`, `evidence_bundle_handoff`, `evidence_integration` | Workspace, inventory lifecycle, ledger validation, bundle pipeline |
Expand Down Expand Up @@ -214,7 +214,7 @@ which runs `cargo bench --locked --all-features --bench perf --no-run`.

## Tool-surface evaluation

`tests/tool_surface_evaluation.rs` runs a deterministic tool-selection regression over the labeled corpus in `tests/fixtures/tool_surface/cases.json` (43 fixtures across generic web, repo, fetch, exact-error, security, research, evidence, diagnostics, and ambiguity categories; every stable tool is an expected primary at least once). The runner scores each query against the live tool definitions, then asserts description, total, instructions, and compact byte budgets, top-1/recall@3/MRR thresholds, forbidden-primary exclusion, known-tool and next-action reference validity, and synthetic Layer 2 hydration mechanics (next actions stay within the ten stable tools and compact discovery stays below full definitions). The baseline fingerprint and per-category accuracy print with `-- --nocapture` or `make eval-tool-surface`:
`tests/tool_surface_evaluation.rs` runs a deterministic tool-selection regression over the labeled corpus in `tests/fixtures/tool_surface/cases.json` (43 fixtures across generic web, repo, fetch, exact-error, security, research, evidence, diagnostics, and ambiguity categories; every stable tool is an expected primary at least once). Full and compact advertised descriptions are scored independently against every case; both must meet top-1/recall@3/MRR thresholds and avoid forbidden-primary results. The suite also asserts description, total, instructions, and compact byte budgets, known-tool and next-action reference validity, and synthetic Layer 2 hydration mechanics (next actions stay within the ten stable tools and compact discovery stays below full definitions). The fingerprints and per-category accuracy print with `-- --nocapture` or `make eval-tool-surface`:

```bash
cargo test --locked --all-features --test tool_surface_evaluation
Expand Down Expand Up @@ -244,7 +244,7 @@ make eval-retrieval-quality

## Transport, egress, and browser suites

`tests/mcp_http.rs` covers the loopback Streamable HTTP lifecycle: health identity, current and legacy protocol flows, shared tool definitions, request hardening, session cleanup, and shutdown behavior. It runs under `--all-features`:
`tests/mcp_http.rs` covers the loopback Streamable HTTP lifecycle: health identity, current and legacy protocol flows, shared tool definitions, the compact-profile initialized `tools/list`, request hardening, session cleanup, and shutdown behavior. It runs under `--all-features`:

```bash
cargo test --locked --all-features --test mcp_http
Expand Down
25 changes: 25 additions & 0 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,31 @@ enabled = false
roots = []
```

## MCP Tool Schema Profile

The server advertises the complete ten-tool schema by default. Direct clients
with tight model contexts can opt into a smaller advertisement in the same
config file:

```toml
[mcp]
schema_profile = "compact"
brief_max_chars = 8000
```

Compact mode keeps all ten tool names and required inputs, trims optional
schema guidance, and omits `outputSchema` metadata. Runtime argument parsing
and tool behavior are unchanged; advanced accepted inputs can still be sent.
Omitted `response_detail` defaults to `brief` in compact mode; explicit
`diagnostic`, `standard`, or `compact` calls override it. `brief_max_chars`
defaults to 8,000 and must be between 512 and 32,000. Brief output preserves
status, source identity, trust, critical warnings and security applicability;
when applicability records exceed the budget, per-state totals remain in
`applicability_summary`; omitted provider failures and batch member indexes
are also counted. The structured result and text fallback are both brief.
Switch to `schema_profile = "full"` for complete
schema guidance and the existing diagnostic-by-default response behavior.

## Provider Requirements

All 44 built-in providers:
Expand Down
5 changes: 5 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,11 @@ cargo install eggsearch --locked
The pinned Unix installer requests assets from the exact `vX.Y.Z` release. The
unpinned form uses `releases/latest/download` for convenience.

For configuring Eggsearch as a local stdio server in LM Studio, see
[LM Studio integration](lm-studio.md). The compact profile requires an
executable built with that feature; older published versions use the full
profile.

## Release targets

| Host | Rust target | Public asset |
Expand Down
2 changes: 2 additions & 0 deletions docs/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ Current references: [Codex MCP CLI](https://developers.openai.com/codex/cli/mcp)

## Settings-file clients

For direct local inference with LM Studio, see [LM Studio](lm-studio.md).

Zed renders the current `context_servers` shape for its Settings Editor. Its
settings are JSONC-capable and there is no stable registration CLI, so
`--apply` intentionally remains print-only:
Expand Down
Loading
Loading