# 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 environment cannot log in

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

If login is only possible in another test sandbox, follow `docs/offline-evidence-intake-plan.md` and use the recommended **Full sandbox artifact bundle** route. The user does not need to generate JSON. Ask them to copy the logged-in test sandbox's install directory, user-data directories, ProgramData directories, shortcuts, `%TEMP%\importal` / `localcache` candidates, and simple copy notes into `runs\offline-evidence-intake\<evidence-id>\`.

The minimal `manifest.json` / `scan_windows-redacted.json` / `dump_uia-main-redacted.json` route is optional and only for advanced operators. In either route, the package is `N12-pre` context only. It can support offline inventory and reverse analysis, but it does not replace live current-environment `win_helper_scan_windows` and `win_helper_dump_uia` evidence.

After receiving a full bundle, first do read-only inventory. Do not directly run unknown copied binaries, do not modify original copied files, do not use copied credential-like material to log in, and do not design automatic login, send message, send file, receive file, injection, hook, memory reading, 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.