docs: add go mcp runbook
This commit is contained in:
zhaoyilun
219
docs/go-mcp-runbook.md
Normal file
219
docs/go-mcp-runbook.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user