isphere-ai-bridge/docs/go-mcp-runbook.md

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 the first log-backed business read tool, isphere_receive_messages, through Go MCP. The receive tool is registered with 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:

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 -NoProfile -ExecutionPolicy Bypass -File scripts\build-win-helper.ps1

Expected output includes "ok":true and writes:

runs\win-helper\ISphereWinHelper.exe

3. Verify C# helper

Run the helper verification script:

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:

go test ./...

Build the Go MCP binary:

go build ./cmd/isphere-mcp

This creates the platform default binary in the repository root, for example:

isphere-mcp.exe

If you want a fixed operator path, use an explicit output path instead:

go build -o runs\go-mcp\isphere-mcp.exe ./cmd/isphere-mcp

5. Verify Go MCP

Run the repeatable smoke verification:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1

Expected final output includes:

{"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 five tools are exposed: four WinHelper observation tools plus isphere_receive_messages.
• win_helper_version returns ISphereWinHelper.
• 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 optional message source

By default, isphere_receive_messages is registered but uses an empty source, so it returns:

{"messages":[]}

To point the server at a local encrypted PacketReader log-line file, set:

$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 clears it so the default smoke test remains deterministic.

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:

E:\coding\codex\isphere-ai-bridge\runs\go-mcp\isphere-mcp.exe

Recommended working directory:

E:\coding\codex\isphere-ai-bridge

Example client configuration shape:

{
  "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:

E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe

8. Allowed tools

These five 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.

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.

9. Current tool surface and next-stage route

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 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.

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.

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 -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:

   { "include_all_visible": true }
   

6. Use win_helper_dump_uia on the selected hwnd, for example:

   {
     "hwnd": "0x001A0B2C",
     "max_depth": 8,
     "include_text": true,
     "max_children": 80
   }
   

7. Save selected evidence under:

   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:

win_helper_version
win_helper_self_check
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:

$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.