From 466fe23500b446513a40ba0f5f02b13724246de8 Mon Sep 17 00:00:00 2001 From: HwangJohn Date: Fri, 17 Jul 2026 19:01:11 +0900 Subject: [PATCH] Document bridge source tools --- docs/api-reference.md | 47 ++++++++++++++++++++++++++++++++++++----- docs/architecture.md | 5 ++++- docs/quickstart.md | 20 ++++++++++++++++++ docs/status.md | 6 ++++-- docs/troubleshooting.md | 26 +++++++++++++++++++++++ 5 files changed, 96 insertions(+), 8 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index c72fbd0..537161f 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -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 `. Browser requests are also @@ -395,7 +395,13 @@ 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 + } } ``` @@ -403,7 +409,11 @@ provide its own source list. 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": { diff --git a/docs/architecture.md b/docs/architecture.md index 636b2b1..553303d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 diff --git a/docs/quickstart.md b/docs/quickstart.md index dc99ce9..db9963f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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 diff --git a/docs/status.md b/docs/status.md index f56d613..f1c0fce 100644 --- a/docs/status.md +++ b/docs/status.md @@ -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,7 +55,7 @@ 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 @@ -61,7 +63,7 @@ pending until this matrix records package versions and install commands. | 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. | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7e6b9da..5b43e0f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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: