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