341 lines
14 KiB
Markdown
341 lines
14 KiB
Markdown
---
|
|
spec: docs/specs/platform/requirements/mcp-session-observability.md
|
|
decision: docs/decisions/2026-08-18-session-mcp-tool-definition-details.md
|
|
created: 2026-08-16
|
|
updated: 2026-08-18
|
|
status: implemented
|
|
---
|
|
|
|
# Implementation Plan: MCP Server Explorer
|
|
|
|
## Overview
|
|
|
|
The first implementation added a session-owned Kandev tool catalog and a
|
|
responsive explorer. This follow-up restores the rich status tooltip and fixes
|
|
the explorer layout.
|
|
|
|
The revised explorer uses three levels: servers, tools, and one tool. The tool
|
|
list gets most of the available space. A tool page shows its description,
|
|
arguments, and deterministic token estimate.
|
|
|
|
Third-party servers keep their current safe status details. Kandev does not
|
|
connect to those servers to collect tool metadata.
|
|
|
|
## Existing constraints
|
|
|
|
- `useSessionMcp` already selects the active session's attachment history.
|
|
- `MCPServerAttachment` already carries status, transport, target, summary,
|
|
and tool count through persistence, boot hydration, and WebSocket updates.
|
|
- `mcp.Server` observes the exact `tools/list` result in
|
|
`hooks.AddAfterListTools`.
|
|
- Third-party MCP connections bypass Kandev after agent configuration delivery.
|
|
- The existing desktop control uses a tooltip. The existing touch control uses
|
|
a drawer and a 44px trigger.
|
|
|
|
## Completed baseline
|
|
|
|
## Backend
|
|
|
|
### Safe tool catalog contract
|
|
|
|
Update `apps/backend/internal/agentctl/types/streams/mcp_attachment.go` with:
|
|
|
|
- `MCPToolSummary` fields `name` and `description`.
|
|
- `tools` and `tool_catalog_truncated` on `MCPServerAttachment`.
|
|
- `tools` on `MCPAttachmentEvidence` for a Kandev `tools_list_observed` event.
|
|
- limits of 128 entries and 1,024 UTF-8 bytes per description.
|
|
|
|
Normalize catalog entries before publication. Sort entries by name. Remove
|
|
empty names, bound descriptions on a valid UTF-8 boundary, and set the
|
|
truncation marker from the full `tool_count`.
|
|
|
|
When `StartAttempt` moves the current attempt into `Previous`, remove each
|
|
server catalog from that historical copy. Keep `tool_count` for diagnostics.
|
|
Keep schema version 1 because all new fields are optional and old reports stay
|
|
valid.
|
|
|
|
### Kandev `tools/list` observation
|
|
|
|
Update `apps/backend/internal/mcp/server/server.go`. Convert
|
|
`mcp.ListToolsResult.Tools` to the bounded summary inside
|
|
`AddAfterListTools`. Send that catalog with the existing attachment evidence.
|
|
|
|
Only the local Kandev MCP server can publish catalog entries. Do not add an
|
|
agentctl HTTP endpoint. Do not inspect third-party configurations or connect to
|
|
third-party MCP servers.
|
|
|
|
The existing lifecycle, orchestrator, boot, and WebSocket paths serialize the
|
|
new optional fields without a new event type. Extend their focused rehydration
|
|
and reducer fixtures to prove that the catalog survives reload for the current
|
|
attempt.
|
|
|
|
## Frontend
|
|
|
|
### Shared types and view model
|
|
|
|
Add the catalog fields to:
|
|
|
|
- `apps/web/lib/types/session-runtime-payloads.ts`.
|
|
- `apps/web/lib/state/slices/session-runtime/types.ts`.
|
|
|
|
Create a pure explorer view model under
|
|
`apps/web/components/task/chat/mcp-explorer/`. It owns:
|
|
|
|
- deterministic selection of `kandev`, then the first server.
|
|
- selection fallback when a live update removes the selected server.
|
|
- localized status labels and catalog availability states.
|
|
- the stored and total tool counts.
|
|
- plain-text tool names and descriptions.
|
|
|
|
### Desktop dialog
|
|
|
|
Extract `McpIndicator` from
|
|
`apps/web/components/task/chat/chat-input-toolbar-primitives.tsx` into the new
|
|
explorer folder.
|
|
|
|
Keep a short hover and focus tooltip for the trigger label. On click, open a
|
|
controlled `Dialog` with `enterConfirms={false}`. Use a bounded wide surface,
|
|
such as `sm:max-w-4xl`, with one internal body height.
|
|
|
|
Use a two-column body on desktop:
|
|
|
|
- a fixed-width server list with status dots and status labels.
|
|
- a flexible detail pane with server metadata and the tool catalog.
|
|
|
|
The detail pane owns vertical scrolling. Long names wrap or truncate inside
|
|
their pane. The document does not gain horizontal overflow.
|
|
|
|
### Phone and tablet drawer
|
|
|
|
Use `useResponsiveBreakpoint` and the existing `Drawer` primitive. Phones use
|
|
a full-height `100dvh` surface. Tablets with a coarse pointer use a bounded
|
|
drawer.
|
|
|
|
The first view lists servers. A 44px server row opens one focused detail view.
|
|
A visible 44px Back control returns to the list. The header stays fixed, and
|
|
the body is the only vertical scroll owner. Bottom content clears the safe-area
|
|
inset.
|
|
|
|
Desktop and touch surfaces share the same server selection, view model, status
|
|
metadata, and tool list components.
|
|
|
|
### Copy and localization
|
|
|
|
Move the existing hard-coded MCP status labels into the `task` namespace. Add
|
|
all new labels, empty states, catalog limits, and third-party explanations to
|
|
each task locale. Do not translate server names or tool names.
|
|
|
|
## Tests
|
|
|
|
- **Catalog normalization:** table-driven Go tests cover sorting, empty names,
|
|
UTF-8 description bounds, entry bounds, and truncation.
|
|
- **Attempt history:** a Go test proves that the current catalog persists and
|
|
a superseded attempt keeps only its count.
|
|
- **MCP hook:** a Go test proves that `tools/list` publishes names and
|
|
descriptions without schemas or other tool data.
|
|
- **Wire types:** existing lifecycle and orchestrator fixtures include a
|
|
current Kandev catalog and survive JSON rehydration.
|
|
- **View model:** Vitest covers default selection, live fallback, unavailable
|
|
catalogs, third-party limits, and truncated counts.
|
|
- **Responsive components:** Testing Library covers dialog open and close,
|
|
server selection, tool descriptions, phone list-to-detail navigation, Back,
|
|
focus return, and localized empty states.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** A desktop user clicks the MCP trigger and selects Kandev.
|
|
**File:** `apps/web/e2e/tests/chat/mcp-status.spec.ts`.
|
|
**Outcome:** A wide dialog shows the active Kandev tools and descriptions.
|
|
- **Scenario:** A desktop user selects a third-party server.
|
|
**File:** `apps/web/e2e/tests/chat/mcp-status.spec.ts`.
|
|
**Outcome:** The detail pane shows safe status and the catalog limitation.
|
|
- **Scenario:** A phone user opens the explorer and selects Kandev.
|
|
**File:** `apps/web/e2e/tests/chat/mobile-mcp-status.spec.ts`.
|
|
**Outcome:** A full-height drawer shows a focused tool list and a Back control.
|
|
- **Scenario:** Tool content exceeds the phone viewport.
|
|
**File:** `apps/web/e2e/tests/chat/mobile-mcp-status.spec.ts`.
|
|
**Outcome:** The drawer scrolls internally and the document has no horizontal
|
|
overflow.
|
|
|
|
## Public documentation
|
|
|
|
Update these explanation pages after the UI lands:
|
|
|
|
- `docs/public/automation-and-mcp.md` explains how to open the explorer and
|
|
what Kandev can show for each server type.
|
|
- `docs/public/agents-and-profiles.md` updates the missing-tool troubleshooting
|
|
step for the new dialog and drawer.
|
|
|
|
## Follow-up implementation
|
|
|
|
### Tool definition contract
|
|
|
|
Extend `MCPToolSummary` with these optional fields:
|
|
|
|
- `input_schema`, stored as valid JSON for the current Kandev attempt.
|
|
- `input_schema_truncated`, set when the schema exceeds a storage limit.
|
|
- `estimated_tokens`, calculated from the complete MCP tool JSON.
|
|
|
|
Add `tool_token_estimator` to `MCPServerAttachment`. Its value is
|
|
`o200k_base:mcp-tool-json-v1` when estimates are present.
|
|
|
|
Keep the existing 128-tool and 1,024-byte description limits. Add a 64 KiB
|
|
limit for one input schema and a 512 KiB combined schema limit. If a schema is
|
|
too large, omit the complete schema instead of storing invalid partial JSON.
|
|
|
|
Calculate the estimate before the schema projection removes fields. Use the
|
|
compact JSON that `mcp.Tool.MarshalJSON` sends for one tool. This includes the
|
|
complete MCP definition but excludes the surrounding `tools/list` response.
|
|
|
|
Use `github.com/tiktoken-go/tokenizer` with `o200k_base`. Keep tokenization in a
|
|
small backend package with a reusable codec. The package must work offline and
|
|
must not download vocabulary data at runtime. Do not use a character-count
|
|
fallback.
|
|
|
|
Record the binary-size change in Task 05. If the dependency adds an
|
|
unacceptable release cost, stop and revise the decision before replacement
|
|
with a heuristic.
|
|
|
|
### Explorer state and navigation
|
|
|
|
Replace the current server-detail composition with these page states:
|
|
|
|
1. The server page shows all session servers.
|
|
2. The tools page shows one server summary and its scrollable tool list.
|
|
3. The tool page shows one tool description and input schema.
|
|
|
|
Desktop keeps the server rail visible. Selecting a server opens its tools page
|
|
in the main pane. Selecting a tool replaces that pane with the tool page.
|
|
|
|
Phones use one page at a time. Back returns from the tool page to the tools
|
|
page. A second Back returns to the server page. Tablets use the same focused
|
|
navigation in the bounded drawer.
|
|
|
|
Store the selected server, selected tool, tool-list scroll offset, and return
|
|
focus target while the explorer is open. If a live catalog removes the selected
|
|
tool, return to the tools page and use the deterministic server fallback.
|
|
|
|
### Status tooltip and compact metadata
|
|
|
|
Restore the previous precise-pointer tooltip. It lists each current server with
|
|
its status dot, name, localized status label, and bounded summary. An Active
|
|
Kandev server uses the existing green status color.
|
|
|
|
Touch users get the same status data on the server and tools pages. No action
|
|
or status depends on hover.
|
|
|
|
Move transport, target, connection ID, and observation time into a compact
|
|
connection-details disclosure. Keep the server name, status, tool count, and
|
|
catalog notices visible. The tool list uses the remaining height.
|
|
|
|
Pass `showCloseButton={false}` to the desktop `DialogContent` when the custom
|
|
44px close control remains. The accessible dialog contains one close control.
|
|
|
|
Use a fixed explorer header and one page-body scroll owner. On desktop, add an
|
|
explicit constrained grid row with `min-h-0`. The tool list owns the main-pane
|
|
scroll area. The dialog and drawer must not scroll the document.
|
|
|
|
### Tool list and tool page
|
|
|
|
Each tool row shows its name and `~N tokens` when an estimate exists. It does
|
|
not show the full description. The selected row opens the tool page.
|
|
|
|
The tool page shows the name, estimate, full plain-text description, and input
|
|
schema. Render common object properties as rows with name, type, required
|
|
state, and description. Add a plain JSON view for nested schemas, references,
|
|
and composition keywords.
|
|
|
|
If the schema is absent because the tool has no arguments, show **No
|
|
arguments**. If storage limits removed it, show a distinct **Schema too large
|
|
to display** state.
|
|
|
|
Explain the estimate near the first token value: it uses `o200k_base`, and the
|
|
actual agent cost varies by model and provider. Do not repeat this explanation
|
|
on every row.
|
|
|
|
### Follow-up tests
|
|
|
|
- Backend tests cover structured and raw input schemas, schema limits, combined
|
|
limits, historical removal, estimator metadata, known tokenizer vectors, and
|
|
tokenizer errors.
|
|
- Component tests cover the rich tooltip, one close control, three-level
|
|
navigation, schema states, scroll restoration, focus restoration, and live
|
|
catalog removal.
|
|
- Desktop E2E proves internal tool-list scrolling and opens a tool page with
|
|
arguments and an estimate.
|
|
- Mobile E2E proves server-to-tools-to-tool navigation, both Back actions,
|
|
44px controls, safe-area clearance, and no document overflow.
|
|
- Public docs explain arguments, estimate limits, and third-party catalog
|
|
limits.
|
|
|
|
## Verification Results
|
|
|
|
All baseline and follow-up verification passed. Tasks 01 through 08 contain
|
|
the exact commands, RED evidence, final results, and inspected assets.
|
|
|
|
The backend focused suites, known `o200k_base` vectors, and release build pass.
|
|
The exact offline tokenizer adds about 3.0 MB to the compressed `kandev`
|
|
binary and 2.9 MB to the compressed `agentctl` binary.
|
|
|
|
The frontend focused suite passes 31 tests. Type checking, localization checks,
|
|
the localization ratchet, and focused lint pass. Fresh production E2E runs pass
|
|
on desktop Chromium and mobile Chrome. The inspected assets show the compact
|
|
tool list, desktop tool detail, and mobile tool detail.
|
|
|
|
The public documentation test suite passes 61 tests, and the validator accepts
|
|
all 41 published pages.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Completed baseline:
|
|
|
|
Wave 1:
|
|
|
|
- [x] [Task 01: Capture the Kandev tool catalog](task-01-capture-tool-catalog.md)
|
|
|
|
Wave 2:
|
|
|
|
- [x] [Task 02: Build the responsive explorer](task-02-build-responsive-explorer.md)
|
|
|
|
Wave 3:
|
|
|
|
- [x] [Task 03: Prove browser flows](task-03-prove-browser-flows.md)
|
|
- [x] [Task 04: Document the explorer](task-04-document-explorer.md)
|
|
|
|
Tasks 03 and 04 are parallel-safe because they own disjoint E2E and public-doc
|
|
files. The primary session executes all tasks in sequence unless the user asks
|
|
for subagents.
|
|
|
|
Follow-up wave 1:
|
|
|
|
- [x] [Task 05: Capture tool definitions and estimates](task-05-capture-tool-definitions.md)
|
|
|
|
Follow-up wave 2:
|
|
|
|
- [x] [Task 06: Refine explorer navigation and layout](task-06-refine-explorer-ux.md)
|
|
|
|
Follow-up wave 3:
|
|
|
|
- [x] [Task 07: Prove the revised browser flows](task-07-prove-revised-browser-flows.md)
|
|
- [x] [Task 08: Update explorer documentation](task-08-update-explorer-docs.md)
|
|
|
|
Tasks 07 and 08 are parallel-safe after Task 06. They own separate E2E and
|
|
public-doc files.
|
|
|
|
## Risks
|
|
|
|
- Plugin tool descriptions are provider-controlled text. The UI must render
|
|
them as text, not HTML or Markdown.
|
|
- A large tool catalog can increase session metadata. The current-only catalog
|
|
and explicit limits bound that growth.
|
|
- Some agents load tools lazily. The UI must show "not loaded" until Kandev
|
|
observes `tools/list`.
|
|
- Third-party tool catalogs remain unavailable without a new proxy or provider
|
|
contract.
|
|
- Token estimates differ from provider context and billing counts. The UI must
|
|
always identify them as estimates.
|
|
- The offline `o200k_base` vocabulary increases the backend binary. Task 05
|
|
records this change before the implementation continues.
|
|
- Input schemas can contain provider-controlled text. The UI must render schema
|
|
values as data and never as HTML.
|