diff --git a/docs/go-mcp-runbook.md b/docs/go-mcp-runbook.md new file mode 100644 index 0000000..db3470b --- /dev/null +++ b/docs/go-mcp-runbook.md @@ -0,0 +1,219 @@ +# 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: + +```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 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: + +```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 +``` + +## 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 + 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: + + ```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 approved evidence under: + + ```text + 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.