bookmark-research 0.6.0 → 0.7.0

package/src/mcp_server.py

@@ -5,16 +5,22 @@ implements initialization, ping, tools/list and tools/call, not resources,
 prompts, sampling, tasks, HTTP transports or arbitrary SQL/command execution.
 """
 
+import copy
 import hashlib
 import json
 import math
 import os
+import re
 import sys
 import threading
+from collections import OrderedDict
 from pathlib import Path
 
 from release import release_version
 from settings import Settings
+from credentials import Credentials
+from locate import continuation_scope, locate as locate_core, locate_ref
+from ref_codec import resolve as resolve_ref
 
 
 PROTOCOLS = ("2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25")
@@ -47,16 +53,18 @@ SETTINGS_SCHEMA = _object_schema({
         "strategy": {"type": "string", "enum": ["hedged", "staggered", "sequential", "wait_all"]},
         "grace_seconds": {"type": ["number", "null"], "minimum": 0, "maximum": 60},
         "deadline_seconds": {"type": ["number", "null"], "minimum": 0, "maximum": 60},
-        "cache_seconds": {"type": "integer", "minimum": 0, "maximum": 3600}}),
-    "fetch": _object_schema({"provider": {"type": "string", "enum": list(PROVIDER_NAMES)},
-        "providers": PROVIDERS,
+        "cache_seconds": {"type": "integer", "minimum": 0, "maximum": 3600,
+                          "description": "Search result cache TTL in seconds. 0 disables cache (always fresh network requests). Maximum 3600s (1 hour)."}}),
+    "fetch": _object_schema({"provider": {"type": "string", "enum": list(Settings.FETCH_PROVIDERS)},
+        "providers": dict(_array_schema({"type": "string", "enum": list(Settings.FETCH_PROVIDERS)}, len(Settings.FETCH_PROVIDERS), 1), uniqueItems=True),
         "max_characters": {"type": "integer", "minimum": 100, "maximum": 100000},
         "max_total_characters": {"type": "integer", "minimum": 100, "maximum": 800000},
         "fair_share_min": {"type": "integer", "minimum": 0, "maximum": 100000},
         "strategy": {"type": "string", "enum": ["sequential", "staggered", "hedged"]},
         "grace_seconds": {"type": ["number", "null"], "minimum": 0, "maximum": 60},
         "deadline_seconds": {"type": ["number", "null"], "minimum": 0, "maximum": 60},
-        "reuse_seconds": {"type": "integer", "minimum": 0, "maximum": 86400}}),
+        "reuse_seconds": {"type": "integer", "minimum": 0, "maximum": 86400,
+                          "description": "Fetch page body reuse window in seconds. 0 disables reuse (always re-fetch). Default 0; up to 86400s (24 hours)."}}),
     "server": _object_schema({"network_workers": {"type": "integer", "minimum": 1, "maximum": 16},
         "max_pending_calls": {"type": "integer", "minimum": 1, "maximum": 64}}),
     "archive": _object_schema({"enabled": {"type": "boolean"}, "directory": _text_schema(4096)}),
@@ -70,9 +78,22 @@ SETTINGS_SCHEMA = _object_schema({
             "max_tool_calls": {"type": "integer", "minimum": 1, "maximum": 1000},
             "allow_untested_model": {"type": "boolean"}}),
         "parallel": _object_schema({"processor": _text_schema(64)})}),
+    "custom_agentic": _object_schema({
+        "enabled": {"type": "boolean"}, "base_url": _text_schema(1024),
+        "model": _text_schema(192),
+        "api_mode": {"type": "string", "enum": ["chat_completions", "responses"]},
+        "search_mode": {"type": "string", "enum": ["prompt", "native"]}}),
+    "browser": _object_schema({
+        "enabled": {"type": "boolean"},
+        "driver": {"type": "string", "enum": ["auto", "playwright", "cdp", "mock"]},
+        "cdp_url": _text_schema(1024),
+        "headless": {"type": "boolean"},
+        "timeout_seconds": {"type": "integer", "minimum": 1, "maximum": 60},
+        "max_concurrency": {"type": "integer", "minimum": 1, "maximum": 8}}),
     "wiki": _object_schema({"directory": _text_schema(4096),
         "max_source_age_days": {"type": "integer", "minimum": 1, "maximum": 3650},
-        "after_research": {"type": "string", "enum": ["suggest", "auto", "off"]}}),
+        "after_research": {"type": "string", "enum": ["suggest", "auto", "off"]},
+        "aliases": _array_schema(_array_schema(_text_schema(100), 50, 1), 50)}),
     "wiki_preflight": {"type": "boolean"},
     "freshness_days": {"type": "integer", "minimum": 1, "maximum": 3650},
     "plan": _object_schema({"max_characters": {"type": "integer", "minimum": 1000, "maximum": 50000},
@@ -105,11 +126,35 @@ TOOL_SCHEMAS = {
         ["source_id"]),
     "source_merge": _object_schema({"source_id": IDENTIFIER, "into_source_id": IDENTIFIER,
         "confirm": {"type": "boolean", "default": False}}, ["source_id", "into_source_id"]),
+    "locate": _object_schema({
+        "text": _text_schema(2000),
+        "url": _text_schema(8192),
+        "in": _array_schema({"type": "string", "enum": ["canvas", "wiki", "archive"]}, 3, 1),
+        "source_id": IDENTIFIER,
+        "section": IDENTIFIER,
+        "folder_id": {**IDENTIFIER, "description": "Filter matches to a folder subtree; with source_id and no text/url, list this folder's direct children."},
+        "package_path": {**IDENTIFIER, "description": "Import this local Canvas package, single section JSON, or bookmark HTML export (snapshot) and query it; omit to use an already-imported source_id."},
+        "tags": _array_schema(_text_schema(), 100),
+        "tag_colors": _array_schema(_text_schema(), 20),
+        "has_note": {"type": "boolean", "description": "Filter for bookmarks with (true) or without (false) a non-empty note. Usable alone, without text/url, to enumerate."},
+        "has_tags": {"type": "boolean", "description": "Filter for bookmarks with (true) or without (false) one or more tags. Usable alone, without text/url, to enumerate."},
+        "metadata_match": {"type": "string", "enum": ["all", "any"], "default": "all"},
+        "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 8},
+        "offset": {"type": "integer", "minimum": 0, "default": 0},
+        "handle": _text_schema(16384),
+        "refresh": {"type": "boolean", "default": False},
+    }),
     "search_bookmarks": _object_schema({
         "source_id": IDENTIFIER, "targets": _array_schema(_text_schema(), 100),
         "section": IDENTIFIER, "group_id": IDENTIFIER, "folder_id": IDENTIFIER,
         "tags": _array_schema(_text_schema(), 100),
         "tag_colors": _array_schema(_text_schema(), 20),
+        "has_note": {"type": "boolean", "description": "Filter for bookmarks with (true) or without (false) a non-empty note. Usable alone, without text/url, to enumerate."},
+        "has_tags": {"type": "boolean", "description": "Filter for bookmarks with (true) or without (false) one or more tags. Usable alone, without text/url, to enumerate."},
+        "metadata_match": {"type": "string", "enum": ["all", "any"], "default": "all",
+                           "description": "Combine has_note and has_tags with AND (all) or OR (any)."},
+        "sort_by": {"type": "string", "enum": ["default", "added_at_desc", "added_at_asc"], "default": "default",
+                    "description": "Sort by canvas order or indexed added_at date. Unknown dates remain last."},
         "item_types": {"type": "array", "items": {"type": "string", "enum": ["bookmark", "folder"]},
                        "minItems": 1, "maxItems": 2, "uniqueItems": True,
                        "description": "Defaults to bookmark; pass [\"folder\"] to enumerate folders."},
@@ -117,8 +162,16 @@ TOOL_SCHEMAS = {
         "offset": {"type": "integer", "minimum": 0, "maximum": 1000000000, "default": 0},
         "count_only": {"type": "boolean", "default": False},
         "compact": {"type": "boolean", "default": False},
+        "score": {"type": "boolean", "default": False,
+                  "description": "Return non-binding ranking score and field_hits hints; literal match set is preserved."},
         "refresh": {"type": "boolean", "default": True},
     }, ["source_id"]),
+    "lookup_url": _object_schema({
+        "url": _text_schema(8192),
+        "source_id": IDENTIFIER,
+        "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100},
+        "offset": {"type": "integer", "minimum": 0, "maximum": 1000000000, "default": 0},
+    }, ["url"]),
     "get_context": _object_schema({
         "source_id": IDENTIFIER, "section": IDENTIFIER, "group_id": IDENTIFIER,
         "item_id": IDENTIFIER, "refresh": {"type": "boolean", "default": True},
@@ -127,6 +180,15 @@ TOOL_SCHEMAS = {
         "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 200},
         "compact": {"type": "boolean", "default": False},
     }, ["source_id"]),
+    "traverse_graph": _object_schema({
+        "source_id": IDENTIFIER, "section": IDENTIFIER, "group_id": IDENTIFIER,
+        "item_id": IDENTIFIER, "node_id": IDENTIFIER,
+        "max_depth": {"type": "integer", "minimum": 1, "maximum": 10, "default": 2},
+        "direction": {"type": "string", "enum": ["all", "out", "in"], "default": "all"},
+        "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100},
+        "offset": {"type": "integer", "minimum": 0, "maximum": 1000000000, "default": 0},
+        "refresh": {"type": "boolean", "default": True},
+    }, ["source_id"]),
     "plan_research": _object_schema({
         "source_id": IDENTIFIER, "question": _text_schema(2000),
         "max_cards": {"type": "integer", "minimum": 1, "maximum": 3, "default": 3},
@@ -153,9 +215,38 @@ TOOL_SCHEMAS = {
         "providers": PROVIDERS,
         "limit_per_target": {"type": "integer", "minimum": 1, "maximum": 20},
     }, ["targets"]),
+    "merge_search_results": _object_schema({
+        "batches": _array_schema(_object_schema({
+            "target": _text_schema(2000),
+            "provider": _text_schema(100),
+            "query": _text_schema(2000),
+            "status": {"type": "string", "enum": ["ok", "error"]},
+            "results": _array_schema(_object_schema({
+                "url": _text_schema(2048),
+                "title": {"type": "string", "maxLength": 500},
+                "snippet": {"type": "string", "maxLength": 100000},
+                "content": {"type": "string", "maxLength": 100000},
+                "rank": {"type": "integer", "minimum": 1, "maximum": 100000}
+            }, ["url"]), 500),
+            "error": {"type": "string", "maxLength": 2000}
+        }, ["target", "provider", "query", "status"]), 50, 1),
+        "targets": _array_schema(_text_schema(2000), 50),
+        "limit_per_target": {"type": "integer", "minimum": 1, "maximum": 50},
+        "archive": {"type": "boolean", "default": False}
+    }, ["batches"]),
+    "agentic_search": _object_schema({
+        "query": _text_schema(12000),
+        "provider": {"type": "string", "enum": ["grok", "custom"], "default": "grok"},
+        "include_x": {"type": "boolean", "default": False,
+                      "description": "Also search public X posts. This may incur additional provider charges."},
+        "rewrite_query": {"type": "boolean", "default": False,
+                          "description": "Decompose and reformulate search queries before searching."},
+        "max_iterations": {"type": "integer", "minimum": 1, "maximum": 5, "default": 1,
+                           "description": "Budget bound for multi-step agentic refinement iterations (1-5)."}
+    }, ["query"]),
     "fetch_web": _object_schema({
         "urls": _array_schema(_text_schema(8192), 16, 1),
-        "provider": {"type": "string", "enum": list(PROVIDER_NAMES)},
+        "provider": {"type": "string", "enum": list(Settings.FETCH_PROVIDERS)},
         "archive": {"type": "boolean"},
         "max_characters": {"type": "integer", "minimum": 100, "maximum": 100000},
         "max_total_characters": {"type": "integer", "minimum": 100, "maximum": 800000,
@@ -178,6 +269,8 @@ TOOL_SCHEMAS = {
             "description": "Occurrences listed per merged body. Each result reports occurrence_count, occurrences_truncated and occurrences_next_offset."},
         "occurrence_offset": {"type": "integer", "minimum": 0, "maximum": 10000000, "default": 0,
             "description": "Continue a body's occurrence list from this offset."},
+        "expand_versions": {"type": "boolean", "default": False,
+            "description": "When true, expand all version captures by SHA-256 instead of grouping by URL."},
     }, ["query"]),
 }
 
@@ -189,15 +282,20 @@ TOOL_DESCRIPTIONS = {
     "source_history": "List saved source versions and managed snapshot paths, including partial-import data. Reimport a snapshot to recover it. Does not refresh sources or rewrite research inventories.",
     "source_remove": "Preview deletion of an imported source, index rows and managed snapshots; confirm=true performs it. Frozen research inventories remain, but item resolution stops and citing Wiki pages need review. For identical duplicates, prefer source_merge.",
     "source_merge": "Preview merging an identical source into into_source_id; confirm=true transfers path aliases and drops the duplicate. Synchronized content versions must match; synchronize legacy sources first.",
-    "search_bookmarks": "Literal all-term search with independent target totals/pages; canvas_matches reports text/group/edge hits separately. compact=true returns shared rows plus ordered result_refs per page; row raw_json/metadata then contain extra/conflicting fields. Default false keeps full rows. Keep instances distinct from unique_urls and shared copies. count_only or limit=0 omits rows; item_types=[\"folder\"] includes synthetic roots. Live inputs refresh by default; inspect source.state. refresh=false reads the saved index.",
+    "locate": "Find matches in one local scope: Canvas bookmarks, Wiki revisions, or archived captures. Canvas returns direct title/URL/note/tag matches before inherited folder_path matches; inherited-only items fold into the nearest matching folder with a count and up to three samples. Three query shapes: text or url; folder_id with source_id and no text/url lists that folder's direct children; metadata filters (tags/tag_colors/has_note/has_tags) with no text/url/folder enumerate matching bookmarks newest-first. If total exceeds limit, continue with more.handle and more.offset; handles survive CLI/MCP process restarts. Pass text or url, not both.",
+    "search_bookmarks": "Literal all-term search with independent target totals/pages; canvas_matches reports text/group/edge hits separately. compact=true returns shared rows plus ordered result_refs per page; row raw_json/metadata then contain extra/conflicting fields. Default false keeps full rows. score=true returns non-binding ranking score and field_hits hints while preserving literal match set. Keep instances distinct from unique_urls and shared copies. count_only or limit=0 omits rows; item_types=[\"folder\"] includes synthetic roots. Live inputs refresh by default; inspect source.state. refresh=false reads the saved index.",
+    "lookup_url": "Reverse index: find all bookmark item instances for an exact URL across sections and sources, with chronological added_at, parent folders and copy anchor cards. source_id is optional.",
     "get_context": "Read section headers, bookmark metadata, folder ancestry, groups and directed edges. Defaults to 200 rows per collection; follow each collection's next_offset with the same scope. Counts cover the full scope. Copy anchors share their primary tree. Live inputs refresh by default. compact=true drops raw_json, description_md and revision; pair it with a collection to reach the smallest budget.",
+    "traverse_graph": "Multi-hop graph traversal along canvas edges and group memberships starting from a node, section, group or bookmark item. Returns the impact surface: reached sections, groups, text annotations and edge paths up to max_depth hops with deterministic sorting and pagination.",
     "plan_research": "Read local candidates for a question: matching bookmarks and canvas text/group/edge labels, independently searched Wiki pages and archived sources, and source dates. source_id is optional. max_cards accepts 1–3 (default 3); max_urls accepts 1–8 (default 8). Larger values are rejected. Scores rank candidates without rejecting them; the host decides relevance, depth and whether to search. question_urls lists known URLs to read directly. No network or research task is started.",
     "discovery_bundle": "Assemble the route-② evidence bundle and decide the budget. Pass every source the host collected: only content_state=usable pages become evidence, the rest are listed with the reason they cannot be cited. The bundle is built at the richest level that fits max_characters (excerpts, then digest, then a plain URL list) and always keeps the URL list, so it degrades instead of returning nothing. steps, fetches, variants and elapsed_seconds are the host's own counters, and the plugin owns the decision: stop when budget.continue is false (steps ≤ 6, fetches ≤ 8, variants ≤ 3, 90 seconds). Cite evidence[].id in the answer; never cite a URL that has no evidence entry.",
     "index_status": "Read source modes, snapshots, counts, input availability, pending changes and monitor errors. No refresh or web fetch; unchecked means a live directory needs a recent check.",
     "search_web": "Discover sources for public queries with saved primary providers, then fallbacks for unresolved queries. search.strategy selects hedged (default), staggered, sequential or wait_all. Hedged/staggered primary search has a 10-second default search.deadline_seconds; routing lists providers abandoned at the deadline. Raise this setting or set it to null with update_settings when slower providers need more time. Provider failures remain visible in batches; quota_exhausted providers enter cooldown (using provider retry_after when supplied), while other configured fallbacks are still attempted. Explicit providers restrict the call. Targets accept target/query objects or plain query strings. Results are discovery snippets; pages are not fetched. Each result carries provider_count and corroborated: two or more providers returning one URL means link overlap, never confirmation of its content.",
+    "merge_search_results": "Fuse and deduplicate search results from host-native tools or other MCPs. Deduplicates by URL and text SHA-256, computes RRF scores, preserves provider provenance, and optionally archives extracts into knowledge storage.",
+    "agentic_search": "Optional model answer/search channel, separate from search_web URL fusion. provider=grok (default) uses xAI Responses and XAI_API_KEY; include_x enables X Search. provider=custom uses the configured custom_agentic OpenAI-compatible endpoint and CUSTOM_AGENTIC_API_KEY; native web search is only requested for Responses mode when explicitly configured. Prompt mode cannot guarantee the upstream actually searches. Citations are not independently verified. Use only when selected by the user or workflow.",
     "fetch_web": "Read known URLs directly (up to 16 per call) with per-page and total text budgets. Continue saved text using capture_id and offset without refetching. Omit provider for the saved fallback order (fetch.strategy overlaps a stalled provider); specifying one restricts it. raw returns provider envelopes; archive=false skips saving. Check page identity before citing. Every page carries content_state, the page's own shape: usable, content_insufficient (under 400 characters or an empty-page marker), js_shell_suspected (a title and navigation but no prose), challenge_blocked, login_required (an SSO or sign-in wall), soft_404 or paywall_suspected; only usable pages are worth citing, and unavailable means no body was obtained. published_at is a day-precision date with published_at_source (provider_metadata, structured_metadata or body_date) and published_at_confidence; a bare date in the text is low confidence and never later than the fetch day. A URL with no body carries liveness: dead only for 404/410, otherwise unknown, and dead_urls lists them.",
-    "search_providers": "Describe retrieval capabilities and per-operation auth. probe=true checks MCP catalogs, not successful retrieval. Jina Reader allows anonymous access; Jina Search needs a key. Configure credentials through CLI setup, never chat.",
-    "search_archive": "Search saved page text across local archives and research tasks using literal terms. No network. Identical bodies are merged by hash; occurrences have their own pagination. Hash-mismatched bodies are skipped and counted; the index refreshes incrementally.",
+    "search_providers": "Describe configured retrieval capabilities and per-operation auth. Includes Exa, Parallel, Tavily, Jina, DeepSeek and optional Perplexity structured Search. probe=true checks remote MCP catalogs, not successful retrieval; HTTP APIs (Jina, DeepSeek, Perplexity) are reported as not probed. Perplexity is search-only and requires PERPLEXITY_API_KEY. Configure credentials through CLI setup, never chat.",
+    "search_archive": "Search saved page text across local archives and research tasks using literal terms. No network. By default, results are grouped by URL, reporting version counts, time span, and distinct versions. Set expand_versions=true to view separate captures merged by body hash. Occurrences have their own pagination. Hash-mismatched bodies are skipped and counted; the index refreshes incrementally.",
 }
 
 RESEARCH_ID = _text_schema(80)
@@ -356,9 +454,13 @@ TOOL_SCHEMAS.update({
     "wiki_write": _object_schema({"page_id": RESEARCH_ID, "page": WIKI_PAGE, "change_note": _text_schema(4000),
         "sources": _array_schema(_object_schema({"id": RESEARCH_ID, "url": _text_schema(8192),
             "text": _text_schema(2000000), "capture_id": _text_schema(128), "title": _text_schema(2000),
-            "retrieved_at": _text_schema(64), "kind": {"type": "string", "enum": ["page", "local_document", "external_report"]}},
+            "retrieved_at": _text_schema(64), "kind": {"type": "string", "enum": ["page", "local_document", "external_report"]},
+            "bookmark_refs": _array_schema(_object_schema({"source_id": IDENTIFIER, "section_id": IDENTIFIER,
+                                                            "item_id": IDENTIFIER}, ["source_id", "section_id", "item_id"]), 100),
+            "inventory_ids": dict(_array_schema(RESEARCH_ID, 10000), uniqueItems=True)},
             ["id", "url"]), 16, 1),
         "expected_revision": {"type": "integer", "minimum": 0, "maximum": 1000000},
+        "ignore_duplicate_warning": {"type": "boolean", "description": "When true, suppresses duplicate concept warnings if URLs or titles overlap with existing pages."},
         "reviewed_input_version": {**_text_schema(200), "description": "The already-synchronized input version this page was checked against; closes source_input_changed for cited tasks at that version."}},
         ["page_id", "page", "change_note"]),
     "wiki_acknowledge": _object_schema({"page_id": RESEARCH_ID, "note": _text_schema(4000),
@@ -383,6 +485,51 @@ TOOL_SCHEMAS.update({
         "limit": {"type": "integer", "minimum": 1, "maximum": 100}}, ["query"]),
     "wiki_lint": _object_schema({"page_id": RESEARCH_ID}),
 })
+
+# P0b primitive names. The legacy schemas remain available during the
+# compatibility window; these aliases provide one stable surface while the
+# underlying providers and evidence rules are migrated incrementally.
+TOOL_SCHEMAS.update({
+    "search": _object_schema({
+        "query": _text_schema(2000), "providers": PROVIDERS,
+        "limit": {"type": "integer", "minimum": 1, "maximum": 20, "default": 8},
+    }, ["query"]),
+    "fetch": TOOL_SCHEMAS["fetch_web"],
+    "ingest": copy.deepcopy(TOOL_SCHEMAS["merge_search_results"]),
+    "spawn": _object_schema({**SERVICE_INPUT, "operation_id": RESEARCH_ID,
+        "task": {"type": "string", "enum": ["deep_research", "fetch", "ingest", "research"],
+                 "default": "deep_research"},
+        "args": {"type": "object",
+                 "description": "Local job payload: fetch {urls, provider?, archive?}, ingest {batches}, research {input, provider?}."},
+        "priority": {"type": "integer", "minimum": -100, "maximum": 100, "default": 0}}),
+    "job": _object_schema({
+        "job_id": _text_schema(128),
+        "external_id": RESEARCH_ID,
+        "action": {"type": "string", "enum": ["status", "result", "cancel"], "default": "status"},
+        "refresh": {"type": "boolean", "default": False},
+        "offset": {"type": "integer", "minimum": 0, "maximum": 10000000, "default": 0},
+        "limit": {"type": "integer", "minimum": 1, "maximum": 50000, "default": 12000},
+    }),
+    "health": _object_schema({}),
+    "read": copy.deepcopy(TOOL_SCHEMAS["get_context"]),
+    "walk": copy.deepcopy(TOOL_SCHEMAS["traverse_graph"]),
+    "save": TOOL_SCHEMAS["wiki_write"],
+})
+TOOL_SCHEMAS["ingest"]["properties"]["batches"]["maxItems"] = 16
+# The primitive surfaces accept a short ref as an alternative to repeating
+# source/section/item identifiers returned by locate.  Legacy schemas keep
+# their source_id requirement and remain available for compatibility calls.
+for _primitive_name in ("read", "walk"):
+    TOOL_SCHEMAS[_primitive_name]["required"] = []
+    TOOL_SCHEMAS[_primitive_name]["properties"]["ref"] = _text_schema(128)
+TOOL_SCHEMAS["read"]["properties"].update({
+    "research_id": RESEARCH_ID, "evidence_source_id": RESEARCH_ID,
+    "evidence_source_ids": dict(_array_schema(RESEARCH_ID, 8, 1), uniqueItems=True),
+    "page_id": RESEARCH_ID,
+    "revision": {"type": "integer", "minimum": 1, "maximum": 1000000},
+    "v": _text_schema(32),
+})
+TOOL_SCHEMAS["read"]["properties"]["collection"]["enum"].append("all")
 TOOL_DESCRIPTIONS.update({
     "research_route": "Describe available quick, agentic or deep routes without starting work. Collaboration and external services are optional; explicit provider is exclusive. failed_routes is cumulative and requires confirmed failures; observe active/unknown runs before choosing another route.",
     "research_services": "Describe optional OpenAI Deep Research and Parallel Task API configuration offline. Configured keys do not prove auth; anonymous Search MCP access is separate.",
@@ -401,8 +548,44 @@ TOOL_DESCRIPTIONS.update({
     "wiki_refresh": "Fetch and archive up to 16 cited webpage URLs from one Wiki revision. Reports changed/unchanged/unverified captures and affected pages; follow continuation for more. Uses retrieval quota. Read saved captures and review new claims before wiki_write; authored text and bookmark packages stay unchanged.",
     "wiki_search": "Find authored Wiki text using an incremental character index, literal/spacing matching and explicit aliases. Validates matching candidates; invalid/retracted evidence is excluded. Freshness warnings remain visible. No embeddings or network calls.",
     "wiki_lint": "Audit all selected Wiki evidence, hashes, source freshness, crosslinks and history. Mechanical integrity and declared semantic review are reported separately; no network.",
+    "search": "Search public sources and return discovery results with provider failures and coverage visible. Results are not page正文; fetch known URLs before citing.",
+    "fetch": "Fetch known URLs with provider fallback, bounded text budgets, content_state and optional archived capture continuation. A returned body is not automatically a verified citation.",
+    "ingest": "Fuse host or provider search batches by canonical URL and body SHA-256, preserving provider provenance, failures and coverage. This is deterministic result ingestion, not Agentic Search planning.",
+    "spawn": "Submit work that outlives one tool step. task=deep_research (default) starts a provider-managed Deep Research run and returns an external id; task=fetch/ingest/research enqueues a durable local job and returns job_id, processed by `br job worker`. The host owns iteration and decides when to observe it with job.",
+    "job": "Observe or cancel a job. Accepts a local job_id (j-...) or a provider external_id. action=status reads state, result returns the stored result (artifact_path for large output), cancel requests cancellation; no new task is submitted. For local jobs, state=succeeded means the worker finished; read result.status and per_url for the actual fetch outcome.",
+    "health": "Return a compact local health summary for indexed sources and the source watcher. It performs no network fetch and is safe to call before research.",
+    "read": "Read a target Canvas bookmark and its folder ancestors by default; use collection='all' for full section context. Also reads a pinned Wiki revision, archived capture, or saved research evidence. Canvas refs are source-version-bound; Wiki and archive refs preserve revision/capture identity and content state.",
+    "walk": "Traverse Canvas edges and memberships through the shared walk primitive, preserving direction, depth, paths and pagination.",
+    "save": "Save a reviewed Wiki revision through the shared save primitive. Citation checks, expected_revision and review requirements remain enforced by WikiStore.",
 })
 
+DEPRECATED_TOOL_TARGETS = {
+    "search_bookmarks": "locate", "lookup_url": "locate", "search_archive": "locate",
+    "wiki_search": "locate", "wiki_list": "locate", "get_context": "read",
+    "traverse_graph": "walk", "search_web": "search", "fetch_web": "fetch",
+    "merge_search_results": "ingest", "wiki_write": "save", "wiki_acknowledge": "save",
+    "research_service_start": "spawn", "research_service_status": "job",
+    "research_service_result": "job", "research_service_cancel": "job",
+    "research_source": "read", "wiki_get": "read",
+}
+for _legacy_name, _replacement_name in DEPRECATED_TOOL_TARGETS.items():
+    TOOL_DESCRIPTIONS[_legacy_name] = "[deprecated→%s] %s" % (
+        _replacement_name, TOOL_DESCRIPTIONS[_legacy_name])
+
+
+def _legacy_compatibility_expired(version):
+    """Return whether a stable release has reached the 0.8.0 cutoff."""
+    match = re.fullmatch(
+        r"(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?",
+        str(version or ""))
+    if match is None:
+        return False
+    current = tuple(int(match.group(index)) for index in (1, 2, 3))
+    cutoff = (0, 8, 0)
+    if current != cutoff:
+        return current > cutoff
+    return match.group(4) is None
+
 
 class RpcError(Exception):
     def __init__(self, code, message):
@@ -478,34 +661,109 @@ class StdioMcpServer:
         self.protocol = None
         self.ready = False
         self._index = None
+        self._read_index = None
         self._source_manager = None
+        self._read_source_manager = None
         self._source_watcher = None
         self._providers = None
         self._research_sessions = None
         self._research_services = None
         self._wiki_store = None
         self._raw_library = None
+        self._job_store = None
         self._initialization_lock = threading.RLock()
         self._log_lock = threading.Lock()
         self._cancel_pending = None
+        self._envelope_versions = OrderedDict()
+        self._envelope_handles = {}
         self.settings = settings if settings is not None else Settings()
 
+    def _compact_source_envelope(self, result):
+        """Collapse repeated source diagnostics while retaining identity per response."""
+        if not isinstance(result, dict) or not isinstance(result.get("source"), dict):
+            return result
+        source = result["source"]
+        identity = {key: source[key] for key in ("source_id", "version_id") if key in source}
+        diagnostics = {key: value for key, value in source.items()
+                       if key not in ("source_id", "version_id")}
+        refresh = result.get("refresh")
+        sync = refresh.get("sync") if isinstance(refresh, dict) else None
+        dynamic_refresh = ({key: value for key, value in refresh.items() if key != "sync"}
+                           if isinstance(refresh, dict) else None)
+        payload = {"identity": identity, "source": diagnostics, "sync": sync}
+        encoded = json.dumps(payload, ensure_ascii=False, allow_nan=False,
+                             sort_keys=True, separators=(",", ":"))
+        digest = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+        handle = self._envelope_handles.get(digest)
+        if handle is None:
+            prefix = "v-" + digest[:4]
+            sequence = 1
+            handle = prefix + "-" + str(sequence)
+            while handle in self._envelope_versions and self._envelope_versions[handle]["digest"] != digest:
+                sequence += 1
+                handle = prefix + "-" + str(sequence)
+            self._envelope_handles[digest] = handle
+        existing = handle in self._envelope_versions
+        self._envelope_versions[handle] = {"digest": digest, **payload}
+        self._envelope_versions.move_to_end(handle)
+        while len(self._envelope_versions) > 128:
+            old_handle, old_value = self._envelope_versions.popitem(last=False)
+            if self._envelope_handles.get(old_value["digest"]) == old_handle:
+                del self._envelope_handles[old_value["digest"]]
+        result["v"] = handle
+        if existing:
+            result["source"] = identity
+            if dynamic_refresh is not None:
+                result["refresh"] = dynamic_refresh
+        return result
+
     def close(self):
         if self._source_watcher is not None:
             self._source_watcher.close()
             self._source_watcher = None
         self._source_manager = None
+        self._read_source_manager = None
         if self._index is not None:
             self._index.close()
             self._index = None
+        if self._read_index is not None:
+            self._read_index.close()
+            self._read_index = None
+        if self._job_store is not None:
+            self._job_store.close()
+            self._job_store = None
+
+    def _local(self, readonly=False):
+        """Return the shared index handle; reads use a read-only connection.
 
-    def _local(self):
+        A second MCP process used to open the read-write handle for every
+        ``read``/``walk`` and pay the schema/WAL write lock each time (4-15s
+        under concurrency).  Read-only handles skip schema writes and never
+        block the writer.
+        """
+        if readonly:
+            if self._read_index is None:
+                from bookmark_index import BookmarkIndex
+                self._read_index = BookmarkIndex(self.db_path, readonly=True)
+            return self._read_index
         if self._index is None:
+            # SQLite cannot run the read-write schema bootstrap while a read-only
+            # handle on the same file is open (it surfaces as "disk I/O error"), so
+            # an upgrade to the writer drops the cached reader first.
+            if self._read_index is not None:
+                self._read_index.close()
+                self._read_index = None
+                self._read_source_manager = None
             from bookmark_index import BookmarkIndex
             self._index = BookmarkIndex(self.db_path)
         return self._index
 
-    def _sources(self):
+    def _sources(self, readonly=False):
+        if readonly:
+            if self._read_source_manager is None:
+                from source_manager import SourceManager
+                self._read_source_manager = SourceManager(self._local(readonly=True))
+            return self._read_source_manager
         if self._source_manager is None:
             from source_manager import SourceManager
             self._source_manager = SourceManager(self._local())
@@ -554,6 +812,12 @@ class StdioMcpServer:
                                              research_sessions=self._research())
             return self._wiki_store
 
+    def _jobs(self):
+        if self._job_store is None:
+            from jobs import JobStore
+            self._job_store = JobStore()
+        return self._job_store
+
     def _raw(self):
         # Rebuilt per call so archive/output setting changes apply without restart.
         if self._raw_library is not None:
@@ -587,11 +851,36 @@ class StdioMcpServer:
         small without deleting any implementation.
         """
         scope = self._tool_scope()
-        return [name for name in TOOL_SCHEMAS if not scope or name in scope]
+        expired = _legacy_compatibility_expired(release_version())
+        available = [name for name in TOOL_SCHEMAS
+                     if not expired or name not in DEPRECATED_TOOL_TARGETS]
+        if not scope:
+            return available
+        allowed = set(available)
+        return list(dict.fromkeys(name for name in scope if name in allowed))
+
+    @staticmethod
+    def _legacy_tool_removed(name):
+        return (name in DEPRECATED_TOOL_TARGETS
+                and _legacy_compatibility_expired(release_version()))
 
     def _tool_enabled(self, name):
-        scope = self._tool_scope()
-        return not scope or name in scope
+        """Explicit scopes restrict calls; quick/deep presets only filter discovery.
+
+        The quick preset must keep deprecated handlers callable during the
+        compatibility window even though they are omitted from tools/list.
+        A host environment override or an explicit user allowlist remains a
+        hard capability boundary.
+        """
+        override = os.environ.get("BOOKMARK_RESEARCH_TOOL_SCOPE")
+        if override is not None:
+            scope = [item.strip() for item in override.split(",") if item.strip()]
+            return not scope or name in scope
+        preferences = self.settings.load()
+        explicit = preferences.get("tool_scope") or []
+        if explicit:
+            return name in explicit
+        return preferences.get("tool_scope_preset", "quick") in ("quick", "deep", "all")
 
     def _hydrate_sources(self, sources):
         """Turn capture pointers into verified evidence before bundling.
@@ -651,6 +940,42 @@ class StdioMcpServer:
             hydrated.append(row)
         return hydrated
 
+    def _locate_canvas(self, arguments):
+        """Thin MCP adapter around the shared Canvas locate primitive."""
+        arguments = dict(arguments)
+        package_path = arguments.pop("package_path", None)
+        imported = None
+        if package_path is not None:
+            if arguments.get("source_id"):
+                raise ValueError("pass package_path or source_id, not both")
+            if arguments.get("handle"):
+                raise ValueError("package_path cannot be combined with a continuation handle")
+            if not isinstance(package_path, str) or not package_path.strip():
+                raise ValueError("package_path must be a non-empty string")
+            resolved_path = Path(package_path).expanduser()
+            if not resolved_path.is_absolute():
+                raise ValueError("package_path must be an absolute path; pass the full path to the export or package")
+            imported = self._sources().sync(str(resolved_path), mode="snapshot", completeness="partial")
+            arguments["source_id"] = imported["source_id"]
+            self._start_watcher()
+            query_keys = ("text", "url", "folder_id", "tags", "tag_colors", "has_note", "has_tags")
+            if not any(arguments.get(key) is not None for key in query_keys):
+                summary = self._local(readonly=True).source_summary(imported["source_id"])
+                summary["imported"] = {"input_path": imported.get("input_path"),
+                                       "counts": imported.get("counts"),
+                                       "changed_files": imported.get("changed_files")}
+                summary["next"] = ("call locate(source_id=%r, text=...) to search, or read(ref=...) "
+                                   "on a hit" % imported["source_id"])
+                return summary
+        requested = arguments.get("in", ["canvas"])
+        if arguments.get("handle"):
+            requested = continuation_scope(arguments["handle"], self.db_path)
+        wiki = self._wiki() if requested == ["wiki"] else None
+        raw = self._raw() if requested == ["archive"] else None
+        refresh = bool(arguments.get("refresh", False))
+        return locate_core(self._local(readonly=not refresh), self._sources(readonly=not refresh),
+                           arguments, wiki=wiki, raw=raw)
+
     def _call(self, name, arguments):
         # Explicit dispatch ensures input can never select a Python method,
         # executable, SQL statement, or unadvertised capability.
@@ -697,12 +1022,222 @@ class StdioMcpServer:
             return self._sources().remove(**arguments)
         if name == "source_merge":
             return self._sources().merge(**arguments)
+        if name == "locate":
+            return self._locate_canvas(arguments)
+        if name == "search":
+            return self._web().search(
+                targets=[{"target": arguments["query"], "query": arguments["query"]}],
+                providers=arguments.get("providers"),
+                limit_per_target=arguments.get("limit", 8),
+            )
+        if name == "fetch":
+            return self._call("fetch_web", dict(arguments))
+        if name == "ingest":
+            batches = arguments.get("batches")
+            if isinstance(batches, list) and len(batches) > 16:
+                raise ValueError("ingest accepts at most 16 batches; use the CLI file path for larger input")
+            encoded = json.dumps(arguments, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+            if len(encoded) > 8000:
+                raise ValueError("ingest payload exceeds 8,000 characters; use the CLI file path for larger input")
+            return self._call("merge_search_results", dict(arguments))
+        if name == "spawn":
+            task = arguments.get("task") or "deep_research"
+            if task in ("fetch", "ingest", "research"):
+                payload = arguments.get("args") or {}
+                if not isinstance(payload, dict):
+                    raise ValueError("spawn args must be an object")
+                job = self._jobs().submit(task, payload,
+                                          idempotency_key=arguments.get("operation_id"),
+                                          priority=int(arguments.get("priority", 0)))
+                return {"job_id": job["job_id"], "state": job["state"], "kind": job["kind"],
+                        "note": "queued; run `br job worker` (or it already runs) and observe with job(job_id)"}
+            if not arguments.get("input") or not arguments.get("operation_id"):
+                raise ValueError("spawn(task='deep_research') requires input and operation_id")
+            options = {key: value for key, value in arguments.items()
+                       if key not in ("task", "args", "priority")}
+            return self._call("research_service_start", options)
+        if name == "job":
+            options = dict(arguments)
+            action = options.pop("action", "status")
+            identifier = options.pop("job_id", None) or options.pop("external_id", None)
+            if not identifier:
+                raise ValueError("job requires job_id")
+            if identifier.startswith("j-"):
+                store = self._jobs()
+                job = store.get(identifier)
+                if job is None:
+                    raise ValueError("Unknown job: " + identifier)
+                if action == "status":
+                    return {"job": job}
+                if action == "result":
+                    return {"job_id": job["job_id"], "state": job["state"],
+                            "result": job["result"], "artifact_path": job["artifact_path"],
+                            "error": job["error"]}
+                return {"job": store.cancel(identifier)}
+            if action == "status":
+                return self._services().status(identifier, options.get("refresh", False))
+            if action == "result":
+                return self._services().result(identifier, options.get("refresh", False),
+                                                options.get("offset", 0), options.get("limit", 12000))
+            return self._services().cancel(identifier)
+        if name == "health":
+            source_report = self._sources(readonly=True).status()
+            sources = []
+            for source in source_report.get("sources", []):
+                sources.append({key: source.get(key) for key in ("source_id", "mode", "state", "version_id")
+                                if source.get(key) is not None})
+            watcher = self._source_watcher.status() if self._source_watcher else {"running": False}
+            return {"status": "ok" if not source_report.get("errors") else "degraded",
+                    "sources": sources, "watcher": {"running": bool(watcher.get("running"))}}
+        if name == "read":
+            options = dict(arguments)
+            version_handle = options.pop("v", None)
+            if version_handle:
+                cached = self._envelope_versions.get(version_handle)
+                if cached is None:
+                    raise ValueError("unknown or expired source metadata ref")
+                self._envelope_versions.move_to_end(version_handle)
+                metadata = {"v": version_handle, "source": {**cached["source"], **cached["identity"]}}
+                if cached.get("sync") is not None:
+                    metadata["refresh"] = {"sync": cached["sync"]}
+                return metadata
+            ref = options.pop("ref", None)
+            canvas_ref = False
+            default_canvas_read = False
+            if ref:
+                resolved = resolve_ref(ref)
+                if resolved is None:
+                    raise ValueError("Unknown or expired ref; call locate again")
+                if resolved["kind"] == "w":
+                    page_id, revision = resolved["identity"]
+                    options.setdefault("page_id", page_id)
+                    options.setdefault("revision", int(revision))
+                elif resolved["kind"] == "b":
+                    canvas_ref = True
+                    default_canvas_read = "collection" not in options
+                    source_id, version_id, section_id, item_id = resolved["identity"]
+                    current = self._sources(readonly=True).source_status(source_id)
+                    if version_id and current.get("version_id") != version_id:
+                        raise ValueError("stale_ref: source version changed; call locate again")
+                    options.setdefault("source_id", source_id)
+                    options.setdefault("section", section_id)
+                    options.setdefault("item_id", item_id)
+                elif resolved["kind"] == "a":
+                    capture_id, expected_sha, url = resolved["identity"]
+                    if not capture_id or not url:
+                        raise ValueError("Archive ref has no readable capture; use fetch on the hit URL")
+                    from archive import SourceArchive
+                    prefs = self.settings.load()["fetch"]
+                    archived = SourceArchive(self.settings.load()["archive"]["directory"]).read_capture(
+                        capture_id, [url], max_characters=prefs["max_characters"],
+                        max_total_characters=prefs["max_total_characters"],
+                        fair_share_min=prefs["fair_share_min"])
+                    page = archived.get("pages", [{}])[0]
+                    if expected_sha and page.get("sha256") != expected_sha:
+                        raise ValueError("stale_ref: archived capture hash changed")
+                    return archived
+                else:
+                    raise ValueError("Unsupported ref kind")
+            if options.get("page_id"):
+                page_id = options.pop("page_id")
+                revision = options.pop("revision", None)
+                return self._wiki().get(page_id, revision)
+            if options.get("research_id"):
+                research_id = options.pop("research_id")
+                evidence_source_id = options.pop("evidence_source_id", None)
+                evidence_source_ids = options.pop("evidence_source_ids", None)
+                if options.keys() - {"offset", "limit"}:
+                    raise ValueError("research evidence read accepts research_id, source IDs, offset and limit")
+                return self._research().source(research_id, source_id=evidence_source_id,
+                                               offset=options.get("offset", 0),
+                                               limit=options.get("limit", 12000),
+                                               source_ids=evidence_source_ids)
+            if "source_id" not in options:
+                raise ValueError("read requires a Canvas ref/source_id, Wiki ref/page_id, or research_id")
+            if canvas_ref and options.get("collection") == "all":
+                options.pop("collection")
+            elif canvas_ref and "collection" not in options:
+                options.setdefault("collection", "items")
+                options.setdefault("limit", 1)
+                options.setdefault("compact", True)
+            options.setdefault("refresh", False)
+            result = self._call("get_context", options)
+            if default_canvas_read and isinstance(result, dict):
+                pagination = result.get("pagination", {})
+                items = result.get("items", [])
+                result = {
+                    "source_id": result.get("source_id"),
+                    "items": items,
+                    "source": result.get("source", {}),
+                    "refresh": result.get("refresh", {}),
+                    "read_scope": "target_item_and_folder_ancestors",
+                    "pagination": {"items": pagination.get("items", {})},
+                }
+                # A folder ref is a request for its children, not for one row.
+                folder_item = (items[0] if len(items) == 1
+                               and items[0].get("item_type") == "folder" else None)
+                if folder_item is not None:
+                    index = self._local(readonly=True)
+                    listing = index.folder_children(
+                        options["source_id"], folder_item["item_id"],
+                        section=folder_item.get("section_id"), limit=5)
+                    version = self._sources(readonly=True).source_status(
+                        options["source_id"]).get("version_id")
+                    children = []
+                    for child in listing["results"]:
+                        entry = {"ref": locate_ref(options["source_id"], child["section_id"],
+                                                   child["item_id"], version),
+                                 "kind": child["item_type"], "item_id": child["item_id"],
+                                 "title": child.get("title") or "",
+                                 "position": child.get("position")}
+                        for field in ("url", "note", "note_color", "tags"):
+                            if child.get(field):
+                                entry[field] = child[field]
+                        children.append(entry)
+                    result["folder"] = {"folder_id": folder_item["item_id"],
+                                        "title": folder_item.get("title") or "",
+                                        "path": folder_item.get("path") or []}
+                    result["children"] = children
+                    result["child_count"] = listing["total"]
+                    result["read_scope"] = "folder_children"
+                    result["next"] = ("%d direct children; read a child ref for its card"
+                                      % listing["total"]) if listing["total"] else "Folder is empty"
+            if isinstance(result, dict) and isinstance(result.get("source"), dict):
+                result["source"].setdefault("source_id", options["source_id"])
+            return self._compact_source_envelope(result)
+        if name == "walk":
+            options = dict(arguments)
+            ref = options.pop("ref", None)
+            if ref:
+                resolved = resolve_ref(ref)
+                if resolved is None:
+                    raise ValueError("Unknown or expired ref; call locate again")
+                if resolved["kind"] != "b":
+                    raise ValueError("walk supports Canvas bookmark refs only")
+                source_id, version_id, section_id, item_id = resolved["identity"]
+                current = self._sources(readonly=True).source_status(source_id)
+                if version_id and current.get("version_id") != version_id:
+                    raise ValueError("stale_ref: source version changed; call locate again")
+                options.setdefault("source_id", source_id)
+                options.setdefault("section", section_id)
+                options.setdefault("item_id", item_id)
+            if "source_id" not in options:
+                raise ValueError("walk requires ref or source_id")
+            options.setdefault("refresh", False)
+            return self._call("traverse_graph", options)
+        if name == "save":
+            return self._call("wiki_write", dict(arguments))
         if name == "plan_research" and not arguments.get("source_id"):
             from research_plan import ResearchPlan
             options = dict(arguments)
             options.pop("refresh", None)
             return ResearchPlan(settings=self.settings, wiki=self._wiki(), raw=self._raw()).build(**options)
-        if name in ("search_bookmarks", "get_context", "plan_research"):
+        if name == "lookup_url":
+            index = self._local()
+            with index.read_snapshot():
+                return index.lookup_url(arguments["url"], source_id=arguments.get("source_id"),
+                                        limit=arguments.get("limit", 100), offset=arguments.get("offset", 0))
+        if name in ("search_bookmarks", "get_context", "traverse_graph", "plan_research"):
             options = dict(arguments)
             refresh = options.pop("refresh", True)
             pagination = {key: options.pop(key, default) for key, default in (
@@ -711,7 +1246,7 @@ class StdioMcpServer:
             scope_notes = None if name != "get_context" or "item_id" in options else {
                 "items": "get_context fills items only for one item_id; read a card's bookmarks with "
                          "search_bookmarks(section=...) or plan_research."}
-            index = self._local()
+            index = self._local(readonly=not refresh)
             update = self._sources().refresh(options["source_id"]) if refresh else None
             if update and update["state"] in ("error", "unavailable"):
                 raise ValueError(update["error"] + "; use refresh=false to read the saved index")
@@ -720,6 +1255,8 @@ class StdioMcpServer:
                     from research_plan import ResearchPlan
                     result = ResearchPlan(index=index, settings=self.settings,
                                           wiki=self._wiki(), raw=self._raw()).build(**options)
+                elif name == "traverse_graph":
+                    result = index.traverse(**options)
                 else:
                     method = index.search if name == "search_bookmarks" else index.context
                     result = method(**options)
@@ -729,17 +1266,26 @@ class StdioMcpServer:
                         result = page_context(result, scope_notes=scope_notes, **pagination)
                         if compact:
                             result = compact_context(result)
-                result["source"] = self._sources().source_status(options["source_id"])
+                result["source"] = self._sources(readonly=not refresh).source_status(options["source_id"])
             result["refresh"] = {"performed": bool(refresh and result["source"]["mode"] == "live"),
                 "index_updated": bool(update and update.get("performed")),
                 "requested": refresh, "mode": "checked_package" if refresh and result["source"]["mode"] == "live" else "saved_snapshot", "sync": update}
             return result
         if name == "index_status":
-            result = self._sources().status(**arguments)
+            result = self._sources(readonly=True).status(**arguments)
             result["monitor"] = self._source_watcher.status() if self._source_watcher else {"running": False, "mechanism": "poll"}
             return result
         if name == "search_web":
             return self._web().search(**arguments)
+        if name == "agentic_search":
+            from grok_search import GrokSearch, OpenAICompatibleAgenticSearch
+            provider = arguments.pop("provider", "grok")
+            if provider == "grok":
+                return GrokSearch(Credentials(self.settings), self.settings.load()["timeout_seconds"]).search(**arguments)
+            if arguments.get("include_x"):
+                raise ValueError("include_x is available only for the Grok provider")
+            return OpenAICompatibleAgenticSearch(
+                self.settings, Credentials(self.settings), self.settings.load()["timeout_seconds"]).search(**arguments)
         if name == "fetch_web":
             from archive import SourceArchive
             options = dict(arguments)
@@ -758,7 +1304,8 @@ class StdioMcpServer:
                     max_total_characters=total, offset=offset, fair_share_min=fair)
             if offset:
                 raise ValueError("offset requires capture_id so continued reads use the same saved evidence")
-            result = self._web().fetch(**options)
+            engine = self._web()
+            result = engine._fetch(**options) if raw else engine.fetch(**options)
             return result if raw else SourceArchive.compact_fetch(
                 result, max_total_characters=total, fair_share_min=fair)
         if name == "search_archive":
@@ -767,6 +1314,9 @@ class StdioMcpServer:
             options = dict(arguments)
             probe = options.pop("probe", False)
             return self._web().probe(**options) if probe else self._web().describe(**options)
+        if name == "merge_search_results":
+            from search_results import fuse_results
+            return fuse_results(arguments, archive=arguments.get("archive", False), settings=self.settings)
         raise RpcError(-32602, "Unknown tool: " + name)
 
     def _tool_result(self, value, is_error=False):
@@ -788,7 +1338,7 @@ class StdioMcpServer:
             params = _params(message.get("params", {}), ("name", "arguments"), ("name",))
             name, arguments = params["name"], params.get("arguments", {})
             _validate(_text_schema(128), name, "name")
-            if name not in TOOL_SCHEMAS:
+            if name not in TOOL_SCHEMAS or self._legacy_tool_removed(name):
                 return False
             if not self._tool_enabled(name):
                 return False
@@ -801,7 +1351,7 @@ class StdioMcpServer:
             return arguments.get("probe", False)
         if name == "research_readiness":
             return not arguments.get("offline", False)
-        return name in {"search_web", "research_search", "research_fetch", "wiki_refresh",
+        return name in {"search_web", "agentic_search", "research_search", "research_fetch", "wiki_refresh",
                         "research_service_start", "research_service_status", "research_service_result",
                         "research_service_cancel", "research_service_attach", "research_service_import"}
 
@@ -873,7 +1423,7 @@ class StdioMcpServer:
                 _params(params, ("name", "arguments"), ("name",))
                 name = params["name"]
                 _validate(_text_schema(128), name, "name")
-                if name not in TOOL_SCHEMAS:
+                if name not in TOOL_SCHEMAS or self._legacy_tool_removed(name):
                     raise RpcError(-32602, "Unknown tool: " + name)
                 if not self._tool_enabled(name):
                     raise RpcError(-32602, "Tool is outside this profile's tool_scope: " + name)