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, four business read tools, and one preview-only send-message tool through Go MCP. Read tools are isphere_receive_messages, isphere_search_contacts, isphere_search_groups, and isphere_receive_files list mode. The send tool is isphere_send_message preview/dry-run only; production send is blocked. 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; receive messages can use copied DB rows only when the caller explicitly passes source_preference="msglib_readonly".

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.4.0, a window scan count, send preflight smoke fields, 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 nine tools are exposed: four WinHelper observation tools plus isphere_receive_messages, isphere_search_contacts, isphere_search_groups, isphere_receive_files, and preview-only isphere_send_message.
• 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; exact ID/display/account matches rank before prefix/substring matches and case-insensitive duplicates are collapsed.
• isphere_search_groups is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture; exact ID/display-name matches rank before prefix/substring matches and case-insensitive duplicates are collapsed.
• isphere_receive_files is callable in list mode and returns one file metadata candidate from the configured synthetic file-transfer fixture.
• isphere_send_message is callable in preview mode and returns send_status="planned" without raw content in the response; execution_mode="production" returns send_status="blocked" and production_send_enabled=false.
• 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, send-file, and production send 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 and explicit DB receive

This is optional. It enriches contact/group display metadata and can also serve isphere_receive_messages from copied MsgLib.db rows when the caller explicitly chooses source_preference="msglib_readonly". It does not turn MsgLib.db into the default message source: empty or auto source preference still uses the PacketReader/log-backed source.

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/message-list operations. It does not send messages, download files, mutate DB rows, log in, hook processes, or return raw rows.
• source_preference="msglib_readonly" is required to read messages from copied MsgLib.db; auto and empty source preference remain PacketReader/log-backed.
• 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 and explicit DB receive:

$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,
  "db_receive_smoke": true,
  "db_receive_message_count": 5,
  "db_receive_sources": ["msglib:tblPersonMsg"],
  "receive_display_smoke": true,
  "receive_sender_name_populated": true,
  "receive_conversation_display_populated": true,
  "printed_entity_values": false,
  "message_body_values_printed": 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 and explicitly calls isphere_receive_messages with source_preference="msglib_readonly". The printed output must stay limited to counts, booleans, and msglib:<source_table> refs. It must not print entity values, JIDs, message body values, 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 nine 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 plus optional MsgLib display enrichment	Search contact candidates extracted from sender/receiver bare JIDs in the configured message source, with deterministic exact-match-first ranking, case-insensitive de-duplication, and preserved source/raw_ref.
isphere_search_groups	log-backed groupchat JIDs plus optional MsgLib display enrichment	Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source, with deterministic exact-match-first ranking, case-insensitive de-duplication, and preserved source/raw_ref.
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.
isphere_send_message	B-route preview/dry-run contract	Plan a text-message send with target/content hash/idempotency/audit metadata. Production send is blocked.

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.
• isphere_send_message: target_type, target_id, content_text, content_sha256, idempotency_key, execution_mode only. R6b supports execution_mode empty/preview/dry_run as planned preview. execution_mode="production" returns blocked status until sandbox-send evidence passes. The response and audit store content_sha256 and idempotency_key_sha256, not raw message body or raw idempotency key.

10. Current tool surface and next-stage route

The current runbook verifies nine 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
• isphere_send_message

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, rank exact matches before prefix/substring matches, collapse case-insensitive duplicates across log-derived candidates and optional MsgLibReadSidecar display metadata, and preserve source/raw_ref; 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. isphere_send_message supports preview/dry-run metadata and redacted audit only; production send remains blocked until dynamic observation, idempotency protection, and one approved sandbox send prove success/ack behavior.

Core business tools for contacts, groups, messages, and files are defined in docs/mcp-core-tools-contract.md. Send-message preview metadata and audit records are now in place; production send still waits for the later online sandbox-send gate.

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. R6c online sandbox send evidence package

The local development machine cannot log in to iSphere. Do not attempt to prove production send locally.

To prepare the online/internal sandbox evidence package:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\package-send-sandbox-gate.ps1

Verify the package locally:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-send-sandbox-gate-package.ps1

Expected output includes:

{
  "ok": true,
  "local_login_required": false,
  "online_sandbox_required": true,
  "production_send_enabled": false
}

Generated package:

runs\send-sandbox-gate-package.zip

Send that zip to the online/internal sandbox operator. The operator must follow OPERATOR-STEPS.md inside the package:

1. fill SANDBOX-SEND-INPUTS.json;
2. run run-before-recorder.bat;
3. manually send exactly one sandbox message in the official client;
4. fill success_ack_or_sent_record;
5. run run-after-recorder.bat;
6. run make-return-zip.ps1;
7. return the generated zip.

Production isphere_send_message remains blocked until the returned package is analyzed.

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