smart-web-mcp 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -9,8 +9,11 @@ The format is based on Keep a Changelog[^1] and this project uses SemVer.
 ### Added
 
 - `smartfetch` now accepts an MCP `output_budget` preset (`compact`, `balanced`, or `full`) and `fetch.outputBudget.preset` settings, so token-sensitive hosts can request smaller structured payloads without hand-tuning every numeric cap.
+- Added MCP host-profile guidance for Hermes/Raon, Codex, OpenCode, and Claude Code, including budget-control precedence and compact/balanced/full follow-up retrieval guidance.
+- Added deterministic MCP smoke coverage proving large `smartfetch` structured payloads stay out of `content[0].text` unless `format: "json"` is explicitly requested.
 - Added `docs/roadmap.md` with long-term provider strategy, lane replacement criteria, and benchmark planning for optional external provider lanes.
 - Added a CI-safe provider evaluation skeleton script (`scripts/provider-benchmark.mjs`) with corpus definitions and explicit available/skipped lane reporting.
+- Added deterministic provider benchmark measurement mode (`--run-measurements`) with fixture metrics and build-vs-wrap recommendation sections.
 
 ### Changed
 
@@ -30,6 +33,13 @@ The format is based on Keep a Changelog[^1] and this project uses SemVer.
 - Korean public API helpers now validate outbound URLs and redirects before fetching, blocking localhost, private, and reserved targets unless `network.allowPrivateHosts` is explicitly enabled.
 - CI now declares read-only default repository permissions, Dependabot auto-merge pins the reusable workflow without forwarding all caller secrets, and the workflow check enforces those guards.
 
+## [0.19.0](https://github.com/jojo-labs/smart-web/compare/v0.18.0...v0.19.0) (2026-06-17)
+
+
+### Features
+
+* add provider benchmark measurements ([#199](https://github.com/jojo-labs/smart-web/issues/199)) ([6e10eef](https://github.com/jojo-labs/smart-web/commit/6e10eef921b7d204d066ef82ffd7b4b393cbab9e))
+
 ## [0.18.0](https://github.com/jojo-labs/smart-web/compare/v0.17.0...v0.18.0) (2026-06-17)
 
 

package/README.md

@@ -68,6 +68,14 @@ This lets hosts decide whether deterministic retrieval was good enough or whethe
 
 For `smartfetch`, MCP `structuredContent` always carries the projected JSON result. MCP calls default to `output_budget: "compact"` so agent hosts do not ingest large page/thread/link payloads unless they ask for them. The human-readable `content[0].text` defaults to compact text instead of duplicating that JSON payload, with separate caps for long body text, result, comment, link, and asset sections. Omitted counts are reported in the text view while the projected fields remain available through `structuredContent`; set `format: "json"` only when a host needs JSON repeated in the text channel. Set `output_budget: "balanced"` or `"full"` only for follow-up calls that explicitly need more structured content. For host-side integration, prefer `preferred_budget_chars`; use `context_mode` only as a backward-compatible coarse alias when numeric hints are not supplied. If neither is present, `headroom_tokens` keeps compact output by default and uses `balanced` only when there is enough room. `format: "markdown"` keeps the compact response shape and requests Markdown extraction when available.
 
+Use budget presets this way:
+
+- `compact`: default first pass for agent hosts, link triage, social/thread previews, and "is this page enough?" checks.
+- `balanced`: follow-up when the first pass found the right page but omitted useful body, result, comment, or link detail.
+- `full`: explicit retrieval pass for a known relevant URL when the host can afford the larger `structuredContent` payload.
+
+When compact output omits needed content, make a follow-up `smartfetch` call for the same URL with a larger budget control instead of asking the model to infer from the compact text. Prefer `preferred_budget_chars` when the host knows its available response budget, or use `output_budget: "balanced"` / `"full"` for manual retries.
+
 ## Supported high-signal surfaces
 
 - communities: Reddit, DCInside, LinkedIn public posts with public fallback recovery, Algumon
@@ -98,6 +106,8 @@ When `smartfetch` or `smartcrawl` needs Playwright-backed page loading, `smart-w
 claude mcp add smart-web -- npx -y smart-web-mcp
 ```
 
+Suggested tool-use profile: default to `smartfetch` without `format` and without a budget control for compact first-pass retrieval; retry with `output_budget: "balanced"` or `"full"` only when the user asks for deeper extraction. If Claude Code exposes a host response budget, send it as `preferred_budget_chars`.
+
 ### Codex
 
 ```bash
@@ -112,6 +122,8 @@ command = "npx"
 args = ["-y", "smart-web-mcp"]
 ```
 
+Suggested tool-use profile: keep default compact text for normal browsing. For targeted follow-up retrieval, pass `preferred_budget_chars` from the remaining response/tool budget when available; otherwise pass one explicit `output_budget` preset.
+
 ### OpenCode
 
 ```json
@@ -127,6 +139,34 @@ args = ["-y", "smart-web-mcp"]
 }
 ```
 
+Suggested tool-use profile: call `smartfetch` with no `format` for normal retrieval, `format: "markdown"` only when Markdown extraction is useful, and `format: "json"` only for hosts that intentionally require the full JSON duplicated into `content[0].text`.
+
+### Hermes/Raon
+
+For Hermes/Raon-style hosts, keep the MCP server command standard and set budget controls per tool call:
+
+```json
+{
+  "tool": "smartfetch",
+  "arguments": {
+    "url": "https://example.com/post",
+    "preferred_budget_chars": 40000
+  }
+}
+```
+
+Use `preferred_budget_chars` as the primary host-profile control when Hermes/Raon knows the response budget. Use `headroom_tokens` only when the host has token headroom but no character budget, and use `context_mode` only for older integrations that cannot send numeric budget metadata.
+
+Budget-control precedence is deterministic:
+
+1. `output_budget`
+2. `preferred_budget_chars`
+3. `headroom_tokens`
+4. `context_mode`
+5. compact default
+
+Send only one control when possible. If older host profiles send more than one, `evidence.selected_output_budget_source` reports which control won.
+
 ### Custom settings file
 
 To use a non-default settings path, append `--settings-file` to the command:
@@ -453,6 +493,18 @@ These keys live inside `settings.json` when you need to force one provider on or
 
 - `network.localOnly`: advanced override that forces local-only behavior regardless of profile
 
+## Provider benchmark
+
+Use the provider benchmark when deciding whether to build, wrap, or replace retrieval lanes:
+
+```bash
+npm run benchmark:providers
+node scripts/provider-benchmark.mjs --run-measurements
+node scripts/provider-benchmark.mjs --run-measurements --json
+```
+
+The default report is availability-only and safe for CI. `--run-measurements` adds deterministic fixture records for available local/core and optional no-key lanes: success, useful character counts, projected/text character counts, latency, extractor/provider id, confidence, partial status, error class, and recommendation sections grouped by lane and case. External lanes without credentials or commands remain explicit skips instead of silently failing.
+
 ## Quick verification
 
 Sanity-check the server with a few real calls:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-web-mcp",
   "mcpName": "io.github.jojo-labs/smart-web",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "packageManager": "npm@11.9.0",
   "description": "Local MCP for web search, direct-URL fetch, compact normalized output, site crawling, and docs export.",
   "homepage": "https://github.com/jojo-labs/smart-web",
@@ -42,7 +42,7 @@
     "dev:mcp": "node dist/dev.js",
     "dev:watch": "tsc -p tsconfig.json --watch --preserveWatchOutput",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --import tsx --test src/assessment.test.ts src/browser-session.test.ts src/shared.test.ts src/extraction.test.ts src/assets.test.ts src/dev-runtime.test.ts src/release-scripts.test.ts src/render.test.ts src/providers.test.ts src/smartcrawl.test.ts src/smartcrawl-export.test.ts src/provider-policy.test.ts src/archive-fallback.test.ts src/mcp.test.ts src/korea/korea.test.ts",
+    "test": "node --import tsx --test src/assessment.test.ts src/browser-session.test.ts src/shared.test.ts src/extraction.test.ts src/assets.test.ts src/dev-runtime.test.ts src/release-scripts.test.ts src/provider-benchmark-script.test.ts src/render.test.ts src/providers.test.ts src/smartcrawl.test.ts src/smartcrawl-export.test.ts src/provider-policy.test.ts src/archive-fallback.test.ts src/mcp.test.ts src/korea/korea.test.ts",
     "test:e2e": "node --import tsx --test src/packaged-mcp.test.ts",
     "test:file": "node --import tsx --test",
     "check:meta": "node scripts/check-metadata.mjs",