# 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 WinHelper observation operations plus the first log-backed business read tool, `isphere_receive_messages`, through Go MCP. The receive tool is registered with an empty default source until a safe evidence loader is wired.

## 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 five tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`.
- `win_helper_version` returns `ISphereWinHelper`.
- `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
- Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
- Contact/group/file/search/send business tools remain later-stage work.

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

These five tools are currently allowed:

| Tool | Source/op | Purpose |
| --- | --- | --- |
| `win_helper_version` | helper `version` | Read helper version and protocol metadata. |
| `win_helper_self_check` | helper `self_check` | Read desktop/UIA availability status. |
| `win_helper_scan_windows` | helper `scan_windows` | Read visible window metadata or likely iSphere candidates. |
| `win_helper_dump_uia` | helper `dump_uia` | Read a UI Automation tree for a specified window handle. |
| `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source. The default server source is empty until a loader is wired. |

Allowed parameters:

- `win_helper_version`: zero business parameters.
- `win_helper_self_check`: zero business parameters.
- `win_helper_scan_windows`: `include_all_visible` only.
- `win_helper_dump_uia`: `hwnd`, `max_depth`, `include_text`, `max_children` only.
- `isphere_receive_messages`: `limit` only.

## 8. Current tool surface and next-stage route

The current runbook verifies five tools:

- `win_helper_version`
- `win_helper_self_check`
- `win_helper_scan_windows`
- `win_helper_dump_uia`
- `isphere_receive_messages`

`isphere_receive_messages` currently has parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored `runs/` paths and is not committed. The next implementation slice should wire a safe configurable loader or fixture path before claiming production message ingestion.

Core business tools for contacts, groups, messages, and files are defined in `docs/mcp-core-tools-contract.md`. Send/file capabilities enter the roadmap through that contract after source discovery, connector selection, preview metadata, execution metadata, and audit records are in place.

## 9. Real-login UIA capture procedure

This is a later real-login capture gate used to collect live UI structure for connector work.

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 login 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 selected evidence under:

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

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

## 10. If this outer-network environment cannot log in

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. The UIA capture procedure still uses only the four helper observation tools:

```text
win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia
```

The MCP server also registers `isphere_receive_messages`, but its default source is empty and it should not be used as N12R UIA evidence collection.

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.

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