knowledge-bridge-labs · HwangJohn · Jul 17, 2026 · Jul 17, 2026
@@ -361,14 +361,14 @@ Response:
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/health` | Reports bridge readiness, selected runtime profile, runtime identity, model configuration, allowed-origin count, and source policy. |
-| `GET` | `/.well-known/agent-card.json` | Returns the A2A-style runtime card with the bridge identity and `message:send` URL. |
+| `GET` | `/health` | Reports bridge readiness, selected runtime profile, runtime identity, model configuration, allowed-origin count, source policy, and redacted `sourceRegistry` readiness counts. |
+| `GET` | `/.well-known/agent-card.json` | Returns the A2A-style runtime card with the bridge identity, `message:send` URL, and redacted `metadata.sourceRegistry` readiness counts. |
 | `POST` | `/message:send` | Accepts a query plus selected Knowledge Sources and returns a completed task with a `llmwiki_agent_result` artifact. |
 | `GET` | `/settings` | Serves the bridge-owned guided setup page: connect runtime, register Knowledge Sources, and verify with `POST /message:send`. |
 | `GET` | `/settings.json` | Returns redacted bridge settings and endpoint metadata. |
 | `PUT` | `/settings/config.json` | Persists runtime configuration plus advanced access, CORS, timeout, and source-policy settings. |
 | `GET/PUT` | `/settings/sources.json` | Reads or persists registered Knowledge Sources. |
-| `POST` | `/mcp` | Exposes bridge tools such as `llmwiki_agent_run` for MCP bridge clients. |
+| `POST` | `/mcp` | Exposes `llmwiki_agent_run` plus read-only source tools for MCP bridge clients. |
 
 When `LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN` is configured, every bridge HTTP
 request must include `Authorization: Bearer <token>`. Browser requests are also
@@ -395,15 +395,25 @@ provide its own source list.
   "agentRuntime": "generic",
   "modelConfigured": false,
   "configuredAllowedOrigins": 1,
-  "sourcePolicy": "private-http"
+  "sourcePolicy": "private-http",
+  "sourceRegistry": {
+    "registeredSourceCount": 1,
+    "selectedSourceCount": 1,
+    "selectedReadySourceCount": 1,
+    "unavailableSourceCount": 0
+  }
 }
 ```
 
 `modelConfigured: false` is valid for evidence-only bridge runs. Runtime-backed
 and hybrid runs require `modelConfigured: true` before the bridge can call the
 configured OpenAI-compatible endpoint.
 
-## Agent Bridge Message And MCP Tool
+`sourceRegistry` is intentionally a readiness summary. It lets clients know
+whether the bridge has registered, selected, and ready Knowledge Sources
+without returning local source endpoint URLs from `/health` or the agent card.
+
+## Agent Bridge Message And MCP Tools
 
 `llmwiki-agent-bridge` accepts the same logical run through A2A-style
 `POST /message:send` and MCP `tools/call` with `llmwiki_agent_run`. The bridge
@@ -413,6 +423,33 @@ normalized source-evidence artifact without calling a runtime. Delegated-runtime
 and hybrid requests call the configured OpenAI-compatible runtime and return a
 normalized result artifact.
 
+The bridge MCP surface has two layers:
+
+| Tool layer | Tools | Runtime call | Use when |
+| --- | --- | --- | --- |
+| Full grounded answer path | `llmwiki_agent_run` | Evidence-only mode skips the runtime; delegated-runtime and hybrid modes call the configured runtime. | The client wants the bridge to gather evidence, assemble trace steps, and return one `llmwiki_agent_result`. |
+| Progressive source exploration | `llmwiki_list_sources`, `llmwiki_context`, `llmwiki_search`, `llmwiki_read`, `llmwiki_graph`, `llmwiki_graph_neighbors`, `llmwiki_source_bundle` | No runtime call. | The host agent wants to list registered or inline Knowledge Sources, inspect context/search/read/graph/source-bundle data, then decide whether to keep exploring or call `llmwiki_agent_run`. |
+
+Source-specific tools accept `sourceId` or `source_id` and optional inline
+`knowledgeSources` or `knowledge_sources`. If no inline sources are supplied,
+the bridge uses sources registered through `/settings`. When more than one
+ready selected source is available, source-specific tools require `sourceId`.
+`llmwiki_list_sources` returns a URL-free text summary; structured descriptors
+are meant for local workbenches that need to pass selected bridge-managed
+sources back to `/message:send` or `llmwiki_agent_run`.
+
+Read-only source tool results use these structured keys:
+
+| Tool | Required arguments | Structured result |
+| --- | --- | --- |
+| `llmwiki_list_sources` | none | `structuredContent.llmwiki_sources` |
+| `llmwiki_context` | `query` | `structuredContent.llmwiki_context` |
+| `llmwiki_search` | `query` | `structuredContent.llmwiki_search` |
+| `llmwiki_read` | `pageId` | `structuredContent.llmwiki_read` |
+| `llmwiki_graph` | none | `structuredContent.llmwiki_graph` |
+| `llmwiki_graph_neighbors` | `nodeId` or `nodeIds` | `structuredContent.llmwiki_graph_neighbors` |
+| `llmwiki_source_bundle` | none | `structuredContent.llmwiki_source_bundle` |
+
 ```json
 {
   "data": {

@@ -97,6 +97,9 @@ answers itself.
 Use `llmwiki-agent-bridge` when a client needs one HTTP service that gathers
 evidence from selected sources and returns a stable artifact shape. Runtime
 synthesis is optional and only happens in runtime-backed bridge modes.
+Bridge MCP clients can also use read-only source tools to list, search, read,
+inspect graph neighborhoods, and fetch source-bundle metadata from registered
+or inline Knowledge Sources without calling the configured runtime.
 
 Use `llmwiki-chat` when a human needs to inspect sources, choose a bridge, ask
 questions, review trace steps, and view cited answers in a browser.
@@ -166,7 +169,7 @@ and trace normalization, use `llmwiki-agent-bridge`.
 | MCP source tools | `llmwiki-serve` | Tool-oriented direct source retrieval. | `llmwiki_context`, search, read, graph, and graph-neighbor tool results. |
 | A2A source compatibility | `llmwiki-serve`, opt-in | A2A-native source discovery when a client cannot call HTTP/MCP directly. | `llmwiki_context` source artifact. |
 | Agent Bridge A2A | `llmwiki-agent-bridge` | Bridge-facing evidence fan-out and optional answer synthesis from selected sources. | `llmwiki_agent_result` artifact. |
-| Agent Bridge MCP | `llmwiki-agent-bridge` | MCP clients that want one bridge tool for evidence-only or runtime-backed grounded answering. | `structuredContent.llmwiki_agent_result`. |
+| Agent Bridge MCP | `llmwiki-agent-bridge` | MCP clients that want `llmwiki_agent_run` for evidence-only or runtime-backed grounded answering, plus read-only source tools for progressive exploration of registered or inline Knowledge Sources. | `structuredContent.llmwiki_agent_result` for full answer runs, or structured source-tool results such as `llmwiki_context`, `llmwiki_search`, `llmwiki_read`, `llmwiki_graph`, `llmwiki_graph_neighbors`, and `llmwiki_source_bundle`. |
 
 ## Ownership Boundaries
 

@@ -253,6 +253,26 @@ citations, graph data, source bundles, trace steps, and per-source failures
 preserve the selected source order even when individual source calls finish out
 of order.
 
+Optional MCP source-tool smoke:
+
+```sh
+curl -s http://127.0.0.1:8788/mcp \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+
+curl -s http://127.0.0.1:8788/mcp \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"llmwiki_context","arguments":{"query":"release readiness","limit":4,"knowledgeSources":[{"id":"local-wiki","name":"Local Wiki","protocol":"llmwiki-http","status":"ready","url":"http://127.0.0.1:8765","selected":true}]}}}'
+```
+
+Use `llmwiki_agent_run` when the bridge should return a full grounded answer
+artifact. Use read-only source tools such as `llmwiki_list_sources`,
+`llmwiki_context`, `llmwiki_search`, `llmwiki_read`, `llmwiki_graph`,
+`llmwiki_graph_neighbors`, and `llmwiki_source_bundle` when your host agent
+wants progressive source exploration without a runtime call. If you register
+sources through `/settings`, source tools can omit inline `knowledgeSources`
+and use the registered source IDs.
+
 ## Optional Runtime-Backed Bridge
 
 Configure a runtime only after evidence-only bridge smoke passes. The bridge

@@ -7,6 +7,8 @@ first PyPI/npm packages are published.
 `llmwiki-serve` main includes the 0.2.0 source release contract from PR #11;
 use a current source checkout for the rich health discovery, graph
 neighborhood, MCP graph-neighbor, and producer freshness marker surfaces.
+`llmwiki-agent-bridge` main includes read-only MCP source tools and
+`sourceRegistry` readiness metadata for bridge-managed Knowledge Sources.
 
 The project is independent community tooling for LLM Wiki-style Markdown
 knowledge folders and agent-readable context. It is not an official project
@@ -53,15 +55,15 @@ pending until this matrix records package versions and install commands.
 | MCP JSON-RPC compatibility | `llmwiki-serve` | Compatibility surface | Legacy JSON-RPC tool calls for local integration testing, including `llmwiki_graph_neighbors`. | `llmwiki-serve` MCP smoke coverage. |
 | MCP Streamable HTTP | `llmwiki-serve` | SDK-backed source surface where implemented | Official MCP SDK-backed tool calls for source retrieval. | `llmwiki-serve` MCP SDK smoke coverage. |
 | A2A source compatibility | `llmwiki-serve` | Opt-in compatibility surface | Agent-card discovery and `message:send` for A2A-native source discovery. | A2A source smoke coverage when enabled. |
-| Bridge runtime endpoints | `llmwiki-agent-bridge` | Public-preview contract | A2A and MCP bridge endpoints that gather source evidence and return a grounded answer artifact. | `npm run check` in `llmwiki-agent-bridge`. |
+| Bridge runtime endpoints | `llmwiki-agent-bridge` | Public-preview contract | A2A and MCP bridge endpoints that gather source evidence, expose read-only source exploration tools, and return a grounded answer artifact when `llmwiki_agent_run` or `message:send` is used. | `npm run check` in `llmwiki-agent-bridge`. |
 | Browser workbench | `llmwiki-chat` | Public-preview UI | Source selection, graph inspection, bridge selection, trace display, citations, and answer review. | `llmwiki-chat` lint, typecheck, unit, E2E, build, and pack gates. |
 
 ## Runtime Adapter Status
 
 | Runtime path | Status | What works | What is not claimed | Validation gate |
 | --- | --- | --- | --- | --- |
 | Agent Bridge A2A | Public-preview path | Connects chat or clients to a bridge agent card and `message:send` endpoint. | Certified A2A conformance or hosted runtime operation. | Bridge and chat A2A smoke tests. |
-| Agent Bridge MCP | Public-preview path | Connects chat or MCP clients to `llmwiki_agent_run` on the bridge. | Certified MCP conformance or hosted runtime operation. | Bridge and chat MCP smoke tests. |
+| Agent Bridge MCP | Public-preview path | Connects chat or MCP clients to `llmwiki_agent_run` for full bridge answers, or to read-only source tools for progressive exploration of registered or inline Knowledge Sources. | Certified MCP conformance or hosted runtime operation. | Bridge and chat MCP smoke tests. |
 | Local Development Runtime | Supported for development | Deterministic UI flow, tool-call trace, citation rendering, and graph continuity. | Production answer quality. | `npm run test` and `npm run test:e2e` in `llmwiki-chat`. |
 | Hermes profile | Supported bridge profile | Uses the bridge runtime profile for Hermes-compatible gateways. | Product-certified Hermes integration. | Bridge profile tests plus operator smoke against a real Hermes-compatible gateway. |
 | DeepAgents profile | Supported bridge profile | Uses the bridge runtime profile for DeepAgents-compatible gateways. | Product-certified DeepAgents integration. | Bridge profile tests plus operator smoke against a real DeepAgents runtime. |

@@ -96,6 +96,32 @@ the run still has usable evidence from other sources, per-source failures appear
 as warning or error trace steps inside the returned answer artifact instead of
 failing the whole request.
 
+## Bridge MCP Source Tools Cannot Select a Source
+
+Check the bridge registry first:
+
+```sh
+curl -s http://127.0.0.1:8788/health
+```
+
+`sourceRegistry.selectedReadySourceCount` should be greater than zero when you
+expect registered sources from `/settings` to be usable. The same redacted
+readiness summary appears in the agent card metadata. It reports counts only;
+it does not expose Knowledge Source endpoint URLs.
+
+For MCP clients, call `tools/list` and then `llmwiki_list_sources`. The source
+list text is URL-free and useful for choosing a source ID. If more than one
+ready selected source is available, source-specific tools such as
+`llmwiki_context`, `llmwiki_search`, `llmwiki_read`, `llmwiki_graph`,
+`llmwiki_graph_neighbors`, and `llmwiki_source_bundle` require `sourceId` or
+an inline `knowledgeSources` array. Use `llmwiki_context` first for
+orientation; use `llmwiki_graph_neighbors` after you have a graph node or
+page/source-ref seed.
+
+These source tools do not call the configured runtime. If you need the bridge
+to produce one grounded answer artifact with citations and trace steps, call
+`llmwiki_agent_run` or `POST /message:send` instead.
+
 ## CI Fails After Documentation Edits
 
 Run the same local checks before pushing: