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 read-only WinHelper operations through Go MCP. This phase does not automate iSphere login and does not perform message or file actions.

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 four tools are exposed.
• win_helper_version returns ISphereWinHelper.
• No real iSphere login is required.
• No message/file/search action tool is present.

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

7. Allowed tools

Only these four tools are allowed in the first phase:

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

Allowed parameters:

• win_helper_version: no business parameters.
• win_helper_self_check: no business parameters.
• win_helper_scan_windows: include_all_visible only.
• win_helper_dump_uia: hwnd, max_depth, include_text, max_children only.

8. Explicit non-goals and safety boundaries

The current phase has these boundaries:

• no login automation
• no send message
• no send file
• no receive/download file
• no process injection
• no hook
• no memory reading
• no search contacts
• no open conversation
• no automatic login
• no credential, token, cookie, or private-key extraction
• no endpoint-security bypass or evasion
• no Python MCP fallback

Future send/file operations, if ever approved, must be behind explicit human approval and audit records. They are not implemented in this phase.

9. Real-login UIA capture procedure

This is a later real-login capture gate. Do not run it unless the operator has explicit approval for the real logged-in UIA capture step.

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-approved 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 approved evidence under:

   runs\real-loggedin-lab\uia-dumps\
   

8. Review and redact any sensitive content before sharing reports.

During this procedure, the operator must not click, type, send, upload, download, modify client state, or capture passwords/tokens.

10. If this outer-network environment cannot log in

Do not run or mark the original current-environment real-login UIA capture gate as passed.

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. It still allows only the four first-phase read-only tools:

win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia

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.

Neither offline evidence nor N12R authorizes automatic login, search contacts, open conversation, send message, send file, receive file, injection, hook, memory reading, credential extraction, or endpoint-security bypass behavior.

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