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 WinHelper observation operations plus four business read tools through Go MCP: isphere_receive_messages, isphere_search_contacts, isphere_search_groups, and isphere_receive_files list mode. These business read tools use an empty default message source unless ISPHERE_PACKET_LOG_FILE points to an operator-local encrypted PacketReader log-line file or ISPHERE_PACKET_LOG_DIR points to an operator-local directory of encrypted PacketReader .log/.txt files. Contact/group display names can also be optionally enriched from an operator-local copied MsgLib.db through the bounded read-only MsgLibReadSidecar.

1. Prerequisites

Run all commands from the repository root:

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 -NoProfile -ExecutionPolicy Bypass -File scripts\build-win-helper.ps1

Expected output includes "ok":true and writes:

runs\win-helper\ISphereWinHelper.exe

3. Verify C# helper

Run the helper verification script:

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:

go test ./...

Build the Go MCP binary:

go build ./cmd/isphere-mcp

This creates the platform default binary in the repository root, for example:

isphere-mcp.exe

If you want a fixed operator path, use an explicit output path instead:

go build -o runs\go-mcp\isphere-mcp.exe ./cmd/isphere-mcp

5. Verify Go MCP

Run the repeatable smoke verification:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1

Expected final output includes:

{"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 eight tools are exposed: four WinHelper observation tools plus isphere_receive_messages, isphere_search_contacts, isphere_search_groups, and isphere_receive_files.
• win_helper_version returns ISphereWinHelper.
• isphere_receive_messages is callable and returns an empty messages array from the default empty source.
• isphere_receive_messages returns the contract-facing ok, conversation, messages, next_cursor, and audit envelope, while preserving legacy message aliases such as id, text, and timestamp.
• A synthetic configured-source smoke check proves ISPHERE_PACKET_LOG_FILE can drive isphere_receive_messages end-to-end with one redacted fixture message.
• A synthetic configured-directory smoke check proves ISPHERE_PACKET_LOG_DIR can drive isphere_receive_messages, contact search, group search, and file-list extraction from a temporary directory fixture.
• isphere_search_contacts is callable and returns JID-derived contact candidates from the same configured synthetic message fixture.
• isphere_search_groups is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture.
• isphere_receive_files is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
• Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
• The deterministic verification path clears MsgLib env variables, so it proves the default no-MsgLib behavior remains stable.
• File download/cache mapping and send business tools remain later-stage work.

6. Configure optional message source

By default, isphere_receive_messages is registered but uses an empty source, so it returns:

{"messages":[]}

To point the server at a local encrypted PacketReader log-line file, set:

$env:ISPHERE_PACKET_LOG_FILE = "E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\<evidence-id>\packet-reader-lines.txt"

The file must contain one encrypted Base64 log line per line. Blank lines are ignored. Keep this file under ignored runs/ paths or another operator-local location; do not commit raw logs or decrypted message content.

To point the server at a directory containing multiple local encrypted PacketReader files, set:

$env:ISPHERE_PACKET_LOG_DIR = "E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\<evidence-id>\raw\temp\PacketReader"

The directory loader recursively reads .log and .txt files, sorts paths deterministically, and ignores blank lines. Set only one source variable at a time: if both ISPHERE_PACKET_LOG_FILE and ISPHERE_PACKET_LOG_DIR are set, server startup fails fast as an ambiguous configuration.

Then start the MCP server normally. The command entry point uses ISPHERE_PACKET_LOG_FILE when the file variable is set, otherwise ISPHERE_PACKET_LOG_DIR when the directory variable is set. The repeatable verification script checks three paths: default empty source, a temporary synthetic encrypted fixture file, and a temporary synthetic encrypted fixture directory.

7. Configure optional MsgLib display-name enrichment

This is optional. It enriches contact/group display metadata; it does not turn MsgLib.db into the primary message source. isphere_receive_messages still needs a PacketReader source to return messages, and MsgLib only fills safe display fields such as sender_name and conversation.display_name.

Build the bounded x86 sidecar first:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-msglib-sidecar.ps1

Then configure all three MsgLib variables before starting the MCP server:

$env:ISPHERE_MSGLIB_SIDECAR_EXE = "E:\coding\codex\isphere-ai-bridge\runs\msglib-sidecar\MsgLibReadSidecar.exe"
$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"

Optional password override:

$env:ISPHERE_MSGLIB_PASSWORD = "123"

Rules:

• Set all of ISPHERE_MSGLIB_SIDECAR_EXE, ISPHERE_MSGLIB_SQLITE_DLL, and ISPHERE_MSGLIB_DB, or set none of them. Partial MsgLib config fails server startup.
• Keep copied DB/provider files under ignored runs/ paths or another operator-local location. Do not commit them.
• MsgLibReadSidecar is read-only and bounded to schema/display metadata operations. It does not send messages, download files, mutate DB rows, log in, hook processes, or return raw rows.
• Standard scripts\verify-go-mcp.ps1 intentionally clears MsgLib variables to keep the default smoke deterministic.

Verify the optional provider path:

$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-sidecar.ps1

Expected provider evidence contains provider_checked=true, a display_source_count, and sanitized display_entity_summaries with counts/source table names only.

Verify MCP-level optional enrichment, including receive-message display fields:

$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-mcp-enrichment.ps1

Expected MCP evidence is sanitized and should include:

{
  "ok": true,
  "receive_display_smoke": true,
  "receive_sender_name_populated": true,
  "receive_conversation_display_populated": true,
  "printed_entity_values": false,
  "message_bodies_returned": false,
  "file_paths_returned": false,
  "raw_rows_returned": false
}

The optional MCP smoke internally uses copied-DB display metadata to build a synthetic encrypted PacketReader fixture, but the printed output must stay limited to counts, booleans, and msglib:<source_table> refs. It must not print entity values, JIDs, message bodies, local DB paths, attachment paths, or raw rows.

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

E:\coding\codex\isphere-ai-bridge\runs\go-mcp\isphere-mcp.exe

Recommended working directory:

E:\coding\codex\isphere-ai-bridge

Example client configuration shape:

{
  "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:

E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe

9. Allowed tools

These eight 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 with a contract-shaped response envelope. The default server source is empty unless ISPHERE_PACKET_LOG_FILE or ISPHERE_PACKET_LOG_DIR is configured.
isphere_search_contacts	log-backed message JIDs	Search contact candidates extracted from sender/receiver bare JIDs in the configured message source.
isphere_search_groups	log-backed groupchat JIDs	Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source.
isphere_receive_files	log-backed file-transfer messages	List file metadata candidates extracted from file-transfer message bodies. Download/cache mapping is not implemented yet.

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: conversation_id, query, since, include_attachment_metadata, source_preference, preview, cursor, limit only. since must be RFC3339/RFC3339Nano when supplied; source_preference currently supports empty/auto/local_readonly; cursor must be empty until pagination is implemented.
• isphere_search_contacts: query, cursor, source_preference, include_inactive, limit only. source_preference currently supports empty/auto/local_readonly; cursor must be empty until pagination is implemented.
• isphere_search_groups: query, cursor, source_preference, include_archived, limit only. source_preference currently supports empty/auto/local_readonly; cursor must be empty until pagination is implemented.
• isphere_receive_files: conversation_id, message_id, file_id, name_contains, mode, output_dir, cursor, source_preference, preview, limit only. C22 supports mode empty or list; source_preference currently supports empty/auto/local_readonly; cursor and output_dir must be empty in current list-only mode; download is deferred.

10. Current tool surface and next-stage route

The current runbook verifies eight tools:

• win_helper_version
• win_helper_self_check
• win_helper_scan_windows
• win_helper_dump_uia
• isphere_receive_messages
• isphere_search_contacts
• isphere_search_groups
• isphere_receive_files

The current log-backed business read tools have parser/source/tool registration and an empty default server source. Raw N12-pre evidence remains under ignored runs/ paths and is not committed. The current command entry point can read an operator-local encrypted PacketReader log-line file via ISPHERE_PACKET_LOG_FILE or a directory of .log/.txt files via ISPHERE_PACKET_LOG_DIR; this is still not a production ingestion claim because raw evidence remains local and uncommitted. isphere_receive_messages now exposes contract-facing fields for digital-employee consumption while preserving older aliases for compatibility, supports conversation_id, keyword query, and RFC3339 since filtering, and validates the remaining safe contract args without pretending unsupported connectors/pagination exist. Contact and group search also accept the safe local-readonly contract args and can optionally enrich display metadata from MsgLibReadSidecar; receive-message sender_name and conversation.display_name can use that same optional metadata when MsgLib env is configured. isphere_receive_files supports list mode with safe contract arg validation; download/cache mapping remains deferred.

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

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

   { "include_all_visible": true }
   

6. Use win_helper_dump_uia on the selected hwnd, for example:

   {
     "hwnd": "0x001A0B2C",
     "max_depth": 8,
     "include_text": true,
     "max_children": 80
   }
   

7. Save selected evidence under:

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

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

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

win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia

The MCP server also registers the log-backed read tools (isphere_receive_messages, isphere_search_contacts, isphere_search_groups, and isphere_receive_files), but their default source is empty and they 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:

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

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