docs: verify five-tool mcp surface
This commit is contained in:
zhaoyilun
@@ -2,7 +2,7 @@
|
||||
|
||||
This runbook is for the first Go MCP phase of `isphere-ai-bridge`. It lets an operator build and verify the Windows helper and the Go MCP server without reading the source code.
|
||||
|
||||
Current scope: expose four WinHelper observation operations through Go MCP. Business contact/group/message/file tools are defined in the core MCP contract and implemented in later stages.
|
||||
Current scope: expose four WinHelper observation operations plus the first log-backed business read tool, `isphere_receive_messages`, through Go MCP. The receive tool is registered with an empty default source until a safe evidence loader is wired.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
@@ -90,10 +90,11 @@ The verification confirms:
|
||||
- C# helper can be built.
|
||||
- Go MCP binary can be built.
|
||||
- MCP initialize/list/call flow works through the SDK harness.
|
||||
- Exactly four tools are exposed.
|
||||
- Exactly five tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`.
|
||||
- `win_helper_version` returns `ISphereWinHelper`.
|
||||
- Verification uses synthetic/local helper checks.
|
||||
- Message/file/search business tools are covered by the core MCP contract, not this runbook phase.
|
||||
- `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
|
||||
- Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
|
||||
- Contact/group/file/search/send business tools remain later-stage work.
|
||||
|
||||
## 6. Configure MCP client command
|
||||
|
||||
@@ -132,14 +133,15 @@ E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
|
||||
|
||||
## 7. Allowed tools
|
||||
|
||||
Only these four tools are allowed in the first phase:
|
||||
These five tools are currently allowed:
|
||||
|
||||
| Tool | Helper op | Purpose |
|
||||
| Tool | Source/op | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `win_helper_version` | `version` | Read helper version and protocol metadata. |
|
||||
| `win_helper_self_check` | `self_check` | Read desktop/UIA availability status. |
|
||||
| `win_helper_scan_windows` | `scan_windows` | Read visible window metadata or likely iSphere candidates. |
|
||||
| `win_helper_dump_uia` | `dump_uia` | Read a UI Automation tree for a specified window handle. |
|
||||
| `win_helper_version` | helper `version` | Read helper version and protocol metadata. |
|
||||
| `win_helper_self_check` | helper `self_check` | Read desktop/UIA availability status. |
|
||||
| `win_helper_scan_windows` | helper `scan_windows` | Read visible window metadata or likely iSphere candidates. |
|
||||
| `win_helper_dump_uia` | helper `dump_uia` | Read a UI Automation tree for a specified window handle. |
|
||||
| `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source. The default server source is empty until a loader is wired. |
|
||||
|
||||
Allowed parameters:
|
||||
|
||||
@@ -147,15 +149,19 @@ Allowed parameters:
|
||||
- `win_helper_self_check`: zero business parameters.
|
||||
- `win_helper_scan_windows`: `include_all_visible` only.
|
||||
- `win_helper_dump_uia`: `hwnd`, `max_depth`, `include_text`, `max_children` only.
|
||||
- `isphere_receive_messages`: `limit` only.
|
||||
|
||||
## 8. Current tool surface and next-stage route
|
||||
|
||||
The current runbook verifies four WinHelper observation tools:
|
||||
The current runbook verifies five tools:
|
||||
|
||||
- `win_helper_version`
|
||||
- `win_helper_self_check`
|
||||
- `win_helper_scan_windows`
|
||||
- `win_helper_dump_uia`
|
||||
- `isphere_receive_messages`
|
||||
|
||||
`isphere_receive_messages` currently has parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The next implementation slice should wire a safe configurable loader or fixture path before claiming production message ingestion.
|
||||
|
||||
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send/file capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
|
||||
|
||||
@@ -207,7 +213,7 @@ iSphere is internal-network only. If the current repository environment is outsi
|
||||
1. **N12-pre offline evidence** for copied files and static analysis. Follow `docs/offline-evidence-intake-plan.md` and place packages under `runs\offline-evidence-intake\<evidence-id>\`.
|
||||
2. **N12R internal-sandbox live capture** for real logged-in UIA evidence. Follow `docs/internal-sandbox-live-capture-plan.md` and `docs/internal-sandbox-operator-runbook.md`; place returned packages under `runs\internal-sandbox-live-capture\<capture-id>\`.
|
||||
|
||||
N12R is the active live-capture route when login is only possible in an internal-network test sandbox. It still allows only the four first-phase read-only tools:
|
||||
N12R is the active live-capture route when login is only possible in an internal-network test sandbox. The UIA capture procedure still uses only the four helper observation tools:
|
||||
|
||||
```text
|
||||
win_helper_version
|
||||
@@ -216,6 +222,8 @@ win_helper_scan_windows
|
||||
win_helper_dump_uia
|
||||
```
|
||||
|
||||
The MCP server also registers `isphere_receive_messages`, but its default source is empty and it should not be used as N12R UIA evidence collection.
|
||||
|
||||
After receiving an N12R package, validate it with `docs/n12r-return-package-validation-checklist.md` before using it as evidence for selector-design review. Prefer the scripted read-only validator:
|
||||
|
||||
```powershell
|
||||
|
||||
Reference in New Issue
Block a user