220 lines
6.0 KiB
Markdown
220 lines
6.0 KiB
Markdown
# 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.
|