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:

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

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

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

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.