277 lines
11 KiB
Markdown
277 lines
11 KiB
Markdown
# Go MCP Operator Runbook
|
|
|
|
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 plus four log-backed business read tools through Go MCP: `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files` list mode. These business read tools use an empty default source unless `ISPHERE_PACKET_LOG_FILE` points to an operator-local encrypted PacketReader log-line file.
|
|
|
|
## 1. Prerequisites
|
|
|
|
Run all commands from the repository root:
|
|
|
|
```powershell
|
|
cd E:\coding\codex\isphere-ai-bridge
|
|
```
|
|
|
|
Required local tools:
|
|
|
|
- Windows PowerShell.
|
|
- .NET Framework C# compiler used by `scripts\build-win-helper.ps1`.
|
|
- Go toolchain compatible with this module.
|
|
- A normal user desktop session; administrator rights are not required for the first phase.
|
|
|
|
Python is not required. Python MCP is not part of this path.
|
|
|
|
## 2. Build C# helper
|
|
|
|
The C# helper is the Windows/UI Automation execution layer. Build it with:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-win-helper.ps1
|
|
```
|
|
|
|
Expected output includes `"ok":true` and writes:
|
|
|
|
```text
|
|
runs\win-helper\ISphereWinHelper.exe
|
|
```
|
|
|
|
## 3. Verify C# helper
|
|
|
|
Run the helper verification script:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
|
|
```
|
|
|
|
Expected output includes `"ok":true`, helper version `0.1.0`, a window scan count, and a UIA availability value.
|
|
|
|
## 4. Build Go MCP
|
|
|
|
Run tests first:
|
|
|
|
```powershell
|
|
go test ./...
|
|
```
|
|
|
|
Build the Go MCP binary:
|
|
|
|
```powershell
|
|
go build ./cmd/isphere-mcp
|
|
```
|
|
|
|
This creates the platform default binary in the repository root, for example:
|
|
|
|
```text
|
|
isphere-mcp.exe
|
|
```
|
|
|
|
If you want a fixed operator path, use an explicit output path instead:
|
|
|
|
```powershell
|
|
go build -o runs\go-mcp\isphere-mcp.exe ./cmd/isphere-mcp
|
|
```
|
|
|
|
## 5. Verify Go MCP
|
|
|
|
Run the repeatable smoke verification:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
|
|
```
|
|
|
|
Expected final output includes:
|
|
|
|
```json
|
|
{"ok":true}
|
|
```
|
|
|
|
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 eight tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`.
|
|
- `win_helper_version` returns `ISphereWinHelper`.
|
|
- `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
|
|
- A synthetic configured-source smoke check proves `ISPHERE_PACKET_LOG_FILE` can drive `isphere_receive_messages` end-to-end with one redacted fixture message.
|
|
- `isphere_search_contacts` is callable and returns JID-derived contact candidates from the same configured synthetic message fixture.
|
|
- `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture.
|
|
- `isphere_receive_files` is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
|
|
- Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
|
|
- File download/cache mapping and send business tools remain later-stage work.
|
|
|
|
## 6. Configure optional message source
|
|
|
|
By default, `isphere_receive_messages` is registered but uses an empty source, so it returns:
|
|
|
|
```json
|
|
{"messages":[]}
|
|
```
|
|
|
|
To point the server at a local encrypted PacketReader log-line file, set:
|
|
|
|
```powershell
|
|
$env:ISPHERE_PACKET_LOG_FILE = "E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\<evidence-id>\packet-reader-lines.txt"
|
|
```
|
|
|
|
The file must contain one encrypted Base64 log line per line. Blank lines are ignored. Keep this file under ignored `runs/` paths or another operator-local location; do not commit raw logs or decrypted message content.
|
|
|
|
Then start the MCP server normally. The command entry point uses `ISPHERE_PACKET_LOG_FILE` if it is set. The repeatable verification script checks both paths: it clears the variable for the default empty-source smoke test, then creates a temporary synthetic encrypted fixture file and proves the configured-source path returns one redacted message.
|
|
|
|
## 7. Configure MCP client command
|
|
|
|
After building a stable binary, configure your MCP client to run the Go MCP executable as a stdio server.
|
|
|
|
Recommended command if using the fixed output path:
|
|
|
|
```text
|
|
E:\coding\codex\isphere-ai-bridge\runs\go-mcp\isphere-mcp.exe
|
|
```
|
|
|
|
Recommended working directory:
|
|
|
|
```text
|
|
E:\coding\codex\isphere-ai-bridge
|
|
```
|
|
|
|
Example client configuration shape:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"isphere-ai-bridge": {
|
|
"command": "E:\\coding\\codex\\isphere-ai-bridge\\runs\\go-mcp\\isphere-mcp.exe",
|
|
"cwd": "E:\\coding\\codex\\isphere-ai-bridge"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If you used `go build ./cmd/isphere-mcp` without `-o`, point the command to:
|
|
|
|
```text
|
|
E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
|
|
```
|
|
|
|
## 8. Allowed tools
|
|
|
|
These eight tools are currently allowed:
|
|
|
|
| Tool | Source/op | Purpose |
|
|
| --- | --- | --- |
|
|
| `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. |
|
|
| `isphere_search_contacts` | log-backed message JIDs | Search contact candidates extracted from sender/receiver bare JIDs in the configured message source. |
|
|
| `isphere_search_groups` | log-backed groupchat JIDs | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source. |
|
|
| `isphere_receive_files` | log-backed file-transfer messages | List file metadata candidates extracted from file-transfer message bodies. Download/cache mapping is not implemented yet. |
|
|
|
|
Allowed parameters:
|
|
|
|
- `win_helper_version`: zero business 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.
|
|
- `isphere_search_contacts`: `query`, `limit` only.
|
|
- `isphere_search_groups`: `query`, `limit` only.
|
|
- `isphere_receive_files`: `conversation_id`, `message_id`, `file_id`, `name_contains`, `mode`, `limit` only. C14 supports `mode` empty or `list`; download is deferred.
|
|
|
|
## 9. Current tool surface and next-stage route
|
|
|
|
The current runbook verifies eight tools:
|
|
|
|
- `win_helper_version`
|
|
- `win_helper_self_check`
|
|
- `win_helper_scan_windows`
|
|
- `win_helper_dump_uia`
|
|
- `isphere_receive_messages`
|
|
- `isphere_search_contacts`
|
|
- `isphere_search_groups`
|
|
- `isphere_receive_files`
|
|
|
|
The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via `ISPHERE_PACKET_LOG_FILE`; this is still not a production ingestion claim because raw evidence remains local and uncommitted. `isphere_receive_files` currently supports list mode only; download/cache mapping is deferred.
|
|
|
|
Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.
|
|
|
|
## 10. Real-login UIA capture procedure
|
|
|
|
This is a later real-login capture gate used to collect live UI structure for connector work.
|
|
|
|
Procedure:
|
|
|
|
1. Build and verify first:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
|
|
```
|
|
|
|
2. Manually open iSphere / IMPlatformClient.
|
|
3. Manually log in using the normal company login process.
|
|
4. Keep the main iSphere window visible.
|
|
5. Use `win_helper_scan_windows` to find the candidate window. Prefer read-only scan arguments such as:
|
|
|
|
```json
|
|
{ "include_all_visible": true }
|
|
```
|
|
|
|
6. Use `win_helper_dump_uia` on the selected `hwnd`, for example:
|
|
|
|
```json
|
|
{
|
|
"hwnd": "0x001A0B2C",
|
|
"max_depth": 8,
|
|
"include_text": true,
|
|
"max_children": 80
|
|
}
|
|
```
|
|
|
|
7. Save selected evidence under:
|
|
|
|
```text
|
|
runs\real-loggedin-lab\uia-dumps\
|
|
```
|
|
|
|
8. Review and redact any sensitive content before sharing reports.
|
|
|
|
## 11. If this outer-network environment cannot log in
|
|
|
|
iSphere is internal-network only. If the current repository environment is outside that network, use two separate routes:
|
|
|
|
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. The UIA capture procedure still uses only the four helper observation tools:
|
|
|
|
```text
|
|
win_helper_version
|
|
win_helper_self_check
|
|
win_helper_scan_windows
|
|
win_helper_dump_uia
|
|
```
|
|
|
|
The MCP server also registers the log-backed read tools (`isphere_receive_messages`, `isphere_search_contacts`, `isphere_search_groups`, and `isphere_receive_files`), but their default source is empty and they 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
|
|
$captureRoot = "runs\internal-sandbox-live-capture\<capture-id>"
|
|
$reportRoot = "runs\internal-sandbox-live-capture-reports"
|
|
New-Item -ItemType Directory -Force -Path $reportRoot | Out-Null
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-n12r-return-package.ps1 `
|
|
-PackageRoot $captureRoot `
|
|
-ReportPath (Join-Path $reportRoot "<capture-id>-validation.md")
|
|
```
|
|
|
|
Keep the validation report outside `$captureRoot`; the returned package is evidence input and should remain unchanged.
|
|
|
|
## 12. Troubleshooting
|
|
|
|
- If C# helper build fails, run `scripts\build-win-helper.ps1` directly and check for missing .NET Framework reference assemblies.
|
|
- If `win_helper_version` fails, rerun `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1` first.
|
|
- If Go MCP verification fails, rerun `go test ./...` and `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1`.
|
|
- If a client cannot start the MCP server, confirm the configured command points to the built `.exe` and the working directory is the repository root.
|