admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89d7f65b45c84406717cb3560cdaa82a92ad5500
isphere-ai-bridge/docs/go-mcp-minimal-plan.md
zhaoyilun e993ce15fb docs: trim safety constraints from mcp roadmap
2026-07-09 22:02:26 +08:00

24 KiB
Raw Blame History

Go MCP Minimal Plan Nodes

Process rule: This is the single active plan for the next phase. The final MCP direction is Go. Old Python MCP, Python tests, offline-lab/native-lab Python layers are archival context outside the active path.

Goal: Build a minimal Go MCP server that exposes the existing C# ISphereWinHelper.exe observation operations as MCP tools.

Architecture: Go is the MCP/service layer. C# is the Windows/UI Automation execution layer. Go calls C# through one-shot stdin/stdout JSON using isphere.helper.v1.

Tech Stack: Go, MCP stdio, C# .NET Framework WinHelper, PowerShell verification scripts.

1. Node Tree

N0  Baseline cleanup and direction lock
  -> N1  C# WinHelper baseline verification
  -> N2  Go module skeleton
  -> N3  Go helper protocol contract
  -> N4  Go helper process client
  -> N5  Helper client live verification
  -> N6  MCP library decision
  -> N7  Go MCP server skeleton
  -> N8  Four read-only MCP tool handlers
  -> N9  MCP stdio smoke verification
  -> N10 Operator runbook and process scripts
  -> N11 Commit/review checkpoint
  -> N12-pre Offline evidence intake
  -> N12R Internal-sandbox live UIA capture route
  -> N12R-review Selector design review gate

Blocked/non-active:
  -> N12-current Current-environment real logged-in UIA capture gate

Reality update 2026-07-08: iSphere is internal-network only. The current repository environment is an outer-network coordination/analysis environment. Therefore N12-current stays secondary unless network placement changes. Live login and live UIA capture must happen in an internal-network test sandbox through N12R.

Node order: start each node after the previous node's acceptance conditions are met.

2. Node Details and Acceptance Conditions

N0: Baseline cleanup and direction lock

Purpose: Align the project on the Go MCP route.

Preconditions:

  • Current branch is codex/isphere-win-helper-first-phase unless explicitly changed by the user.
  • Python MCP temporary layer has been removed.

Actions:

  • Confirm tracked files only include current docs/prompts/C# helper/scripts/evidence placeholders.
  • Confirm the tracked tree is aligned with the current Go/C# route.
  • Confirm docs/go-csharp-helper-boundary.md remains the source boundary document.

Expected outputs:

  • Clean project direction: C# helper now, Go MCP next.
  • Single active fallback path: Go MCP plus C# helper.

Acceptance conditions:

git status --short

Pass if:

  • Working tree only contains expected files for the active edit.
  • git ls-files includes native/ISphereWinHelper/*.
  • git ls-files does not include src/isphere_ai_bridge/*.
  • git ls-files does not include tests/test_*.py.

Stop conditions:

  • Python MCP files reappear.
  • C# helper files are missing.
  • Worktree has unrelated dirty files.

Next node: N1.

N1: C# WinHelper baseline verification

Purpose: Prove the existing C# helper still works before writing Go code.

Preconditions:

  • N0 accepted.
  • scripts/build-win-helper.ps1 exists.
  • scripts/verify-win-helper.ps1 exists.

Actions:

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1

Expected outputs:

  • runs/win-helper/ISphereWinHelper.exe is built locally.
  • version, self_check, scan_windows, and dump_uia all run through JSON.

Acceptance conditions:

Pass if output contains:

{"ok":true}

And confirms:

  • helper path points to runs\win-helper\ISphereWinHelper.exe.
  • version is 0.1.0.
  • scan_window_count is a number.
  • uia_available is true or a valid boolean field.
  • Temporary WinForms dump_uia succeeds.

Stop conditions:

  • Build fails.
  • Helper stdout is not JSON.
  • dump_uia cannot capture the temporary WinForms window.
  • Helper requires admin rights.

Next node: N2.

N2: Go module skeleton

Purpose: Create the smallest Go project shell.

Preconditions:

  • N1 accepted.
  • Go toolchain is available on this machine.

Actions:

Create:

go.mod

Initial module name:

isphere-ai-bridge

Create only the Go module at this node; server code starts in the later server node.

Expected outputs:

  • A Go module exists.
  • Dependencies stay limited to standard Go tooling needs.

Acceptance conditions:

Run:

go version
go list ./...

Pass if:

  • go version exits 0.
  • go list ./... exits 0 or reports only the root module with no packages before packages are created.
  • Generated files stay in the Go route.

Stop conditions:

  • Go is not installed.
  • Module name conflicts with repository layout.
  • Toolchain tries to create unrelated files outside the repo.

Commit boundary: optional; can be combined with N3.

Next node: N3.

N3: Go helper protocol contract

Purpose: Model isphere.helper.v1 in Go before process execution.

Preconditions:

  • N2 accepted.
  • docs/go-csharp-helper-boundary.md is available.

Actions:

Create:

internal/helperclient/contract.go
internal/helperclient/client_test.go

Define minimal structs:

HelperRequest
HelperResponse
HelperError

Required fields:

protocol
request_id
op
timeout_ms
args
ok
data
error
warnings

Expected outputs:

  • JSON marshaling generates isphere.helper.v1 requests.
  • JSON unmarshaling accepts C# helper success and error responses.

Acceptance conditions:

Run:

go test ./internal/helperclient -run Contract -v

Pass if tests prove:

  • version request marshals with protocol="isphere.helper.v1".
  • success response unmarshals with ok=true and data.helper_name="ISphereWinHelper".
  • error response unmarshals with ok=false and error.code="WINDOW_NOT_FOUND".
  • unknown data fields are preserved as JSON maps or raw JSON.

Stop conditions:

  • Contract field names differ from C# helper output.
  • Tests require a real helper process; N3 must be pure JSON only.

Commit boundary:

git add go.mod internal/helperclient/contract.go internal/helperclient/client_test.go
git commit -m "feat: add go helper contract"

Next node: N4.

N4: Go helper process client

Purpose: Let Go call ISphereWinHelper.exe --json with one request and one response.

Preconditions:

  • N3 accepted.
  • C# helper verification from N1 passes.

Actions:

Create:

internal/helperclient/client.go

Implement:

Client
Client.Call(ctx, op, args)

Client responsibilities:

  • Resolve helper exe path.
  • Start helper with --json.
  • Write request JSON to stdin.
  • Read stdout.
  • Capture stderr.
  • Enforce context timeout.
  • Return structured Go error for missing helper, timeout, bad JSON, non-zero exit.

Expected outputs:

  • Go can call C# helper without MCP.
  • Process execution logic lives only in internal/helperclient.

Acceptance conditions:

Run:

go test ./internal/helperclient -run Client -v

Pass if tests prove:

  • Missing helper path returns a structured error.
  • Bad helper output returns a structured error using a test stub.
  • Timeout returns a structured error using a test stub.
  • Real version call returns ok=true when helper is built.

Stop conditions:

  • Client leaks helper processes after timeout.
  • Client requires admin rights.
  • Client writes logs/files by default.
  • Client duplicates C# UIA logic.

Commit boundary:

git add internal/helperclient/client.go internal/helperclient/client_test.go
git commit -m "feat: add win helper process client"

Next node: N5.

N5: Helper client live verification

Purpose: Verify Go-to-C# works against the real helper on this machine.

Preconditions:

  • N4 accepted.
  • scripts/verify-win-helper.ps1 passes.

Actions:

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
go test ./internal/helperclient -v

Expected outputs:

  • C# helper works alone.
  • Go helper client works against C# helper.

Acceptance conditions:

Pass if:

  • PowerShell verification exits 0.
  • Go tests exit 0.
  • Test output includes a real version call.
  • Tests cover helper version/self-check/scan/dump paths only.

Stop conditions:

  • Tests only pass with mocked helper and never call the real C# helper.
  • C# helper passes alone but Go client cannot call it.

Commit boundary: separate commit only when tests/scripts changed.

Next node: N6.

N6: MCP library decision

Purpose: Choose the Go MCP server library before writing server code.

Preconditions:

  • N5 accepted.
  • Network/package access is available or a local dependency strategy is chosen.

Actions:

Evaluate one current Go MCP library or official SDK option.

Record the decision inside the implementation commit or a short docs section.

Decision must answer:

package/module name
stdio support yes/no
tool registration style
JSON schema support
maintenance risk
why this is enough for four tools

Expected outputs:

  • One MCP server package is selected.
  • One MCP framework remains in the codebase.

Acceptance conditions:

Pass if:

go list -m all

shows exactly one MCP-related Go dependency, or no external MCP dependency if a minimal stdio implementation is deliberately chosen.

Also pass if:

  • The decision does not add HTTP server dependencies.
  • The decision does not require Python or Node runtime.
  • The decision supports stdio.

Stop conditions:

  • MCP package cannot build on Windows.
  • Package requires a background daemon.
  • Package forces HTTP-only transport.
  • Multiple MCP packages are added without a reason.

Commit boundary: can be combined with N7.

Next node: N7.

N7: Go MCP server skeleton

Purpose: Create a Go binary that can start as an MCP stdio server.

Preconditions:

  • N6 accepted.

Actions:

Create:

cmd/isphere-mcp/main.go

Optional only if it keeps main.go small:

internal/mcpserver/server.go

Register the tool definitions needed for the current test surface; if the library supports an empty server test, keep tool registration for N8.

Expected outputs:

  • go build ./cmd/isphere-mcp creates a binary.
  • Server starts in stdio mode.

Acceptance conditions:

Run:

go test ./...
go build ./cmd/isphere-mcp

Pass if:

  • Build exits 0.
  • Server construction uses the Go runtime only.
  • Simple server construction tests stay on the server construction path.

Stop conditions:

  • Server starts an HTTP listener.
  • Server invokes C# helper during initialization.
  • Build requires unrelated services.

Commit boundary: can be combined with N8.

Next node: N8.

N8: Four read-only MCP tool handlers

Purpose: Expose the first four read-only WinHelper operations through Go MCP.

Preconditions:

  • N7 accepted.
  • internal/helperclient accepted.

Actions:

Create:

internal/tools/winhelper.go
internal/tools/winhelper_test.go

Register exactly these tools:

win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia

Tool behavior:

win_helper_version       -> helper op version
win_helper_self_check    -> helper op self_check
win_helper_scan_windows  -> helper op scan_windows
win_helper_dump_uia      -> helper op dump_uia

Expected outputs:

  • Four tool definitions exist.
  • Tool handlers call internal/helperclient.
  • Handlers delegate UI work through internal/helperclient.

Acceptance conditions:

Run:

go test ./internal/tools -v
go test ./...

Pass if tests prove:

  • Exactly four WinHelper tools are registered for this phase.
  • Tool names match the list above.
  • Tool schemas include only needed parameters:
    • include_all_visible for scan.
    • hwnd, max_depth, include_text, max_children for dump.
  • This phase contains only WinHelper observation tools.

Stop conditions:

  • A fifth real action tool is added.
  • A handler clicks, types, sends, uploads, downloads, or edits files.
  • Tool code calls helper outside internal/helperclient.

Commit boundary:

git add cmd/isphere-mcp internal/mcpserver internal/tools go.mod go.sum
git commit -m "feat: add minimal go mcp server"

Next node: N9.

N9: MCP stdio smoke verification

Purpose: Verify the Go MCP binary can run over stdio and expose the four tools.

Preconditions:

  • N8 accepted.

Actions:

Create if useful:

scripts/verify-go-mcp.ps1

The script should:

  • Build C# helper.
  • Build Go MCP binary.
  • Start Go MCP over stdio or use the MCP library test harness.
  • List tools.
  • Confirm the four expected tools exist.
  • Call at least win_helper_version.

Expected outputs:

  • A repeatable local verification command.

Acceptance conditions:

Run:

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

Pass if output includes:

{"ok":true}

And confirms:

  • Four tool names are present.
  • win_helper_version returns ISphereWinHelper.
  • Verification uses synthetic/local helper checks.
  • Message/file/search business actions are handled by the core MCP contract route.

Stop conditions:

  • Verification needs manual interaction.
  • Verification needs Python.
  • Tool listing cannot be automated.

Commit boundary:

git add scripts/verify-go-mcp.ps1
git commit -m "test: add go mcp verification script"

Next node: N10.

N10: Operator runbook and process scripts

Purpose: Make the current tool usable by a human operator without reading code.

Preconditions:

  • N9 accepted.

Actions:

Create:

docs/go-mcp-runbook.md

Update only if needed:

README.md

Runbook must include:

  • Build C# helper.
  • Verify C# helper.
  • Build Go MCP.
  • Verify Go MCP.
  • Configure MCP client command.
  • Allowed tools.
  • Explicit non-goals.
  • Real-login UIA capture procedure.

Expected outputs:

  • A user can run the first phase without asking for hidden context.

Acceptance conditions:

Pass if runbook includes exact commands for:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
go test ./...
go build ./cmd/isphere-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1

And describes the current tool surface:

win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia

Stop conditions:

  • Runbook drifts back to the Python MCP route.
  • Runbook states that send/file business tools are already implemented by the WinHelper observation phase.
  • Runbook omits the route to docs/mcp-core-tools-contract.md for business send/file tools.

Commit boundary:

git add docs/go-mcp-runbook.md README.md
git commit -m "docs: add go mcp runbook"

Next node: N11.

N11: Commit and review checkpoint

Purpose: Freeze the first Go MCP phase before real iSphere data is introduced.

Preconditions:

  • N10 accepted.

Actions:

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
go test ./...
go build ./cmd/isphere-mcp
git status --short

Expected outputs:

  • All local verification passes.
  • Worktree is clean after commits.

Acceptance conditions:

Pass if:

  • git status --short has no output.
  • Latest commits are small and tied to N3/N4/N8/N9/N10.
  • Go/C# route files are the active implementation surface.
  • Business search/send/file tools remain in the core contract until implemented.

Stop conditions:

  • Any verification fails.
  • Unrelated generated files are staged.
  • Worktree contains ignored build outputs outside runs/.

Next node: N12-pre for offline evidence intake, followed by N12R for live capture in an internal-network test sandbox. N12-current remains blocked because the current outer-network environment cannot log in to internal iSphere.

N12-pre: Offline evidence intake

Purpose: Define and validate offline evidence copied from a separate logged-in test sandbox when the current repository environment cannot log in to iSphere.

Preconditions:

  • N11 accepted.
  • Current environment cannot manually log in to iSphere / IMPlatformClient.
  • Business manager approves offline evidence intake as a pre-gate only.

Actions:

  • Follow docs/offline-evidence-intake-plan.md.
  • Prefer mode A, Full sandbox artifact bundle. The user does not need to understand or generate JSON; they only copy folders from the logged-in test sandbox.
  • Recommended full-bundle shape:
runs/offline-evidence-intake/<evidence-id>/
  copy-notes.txt
  raw/
    install/
    user-profile/
    programdata/
    shortcuts/
    temp-importal-localcache/
    other-candidates/
  metadata/
  notes/
  • Common candidate source paths include install directories, %APPDATA%, %LOCALAPPDATA%, %PROGRAMDATA%, Documents, Desktop/Start Menu shortcuts, and %TEMP%\importal or localcache folders.
  • Pay attention to historical iSphere anchors such as importal\localcache, LoginLog, IMPP.Util.dll, IMPlatformClient, and iSphere.
  • Optional mode B, Minimal redacted UIA package, is only for advanced operators who already know how to produce JSON:
runs/offline-evidence-intake/<evidence-id>/
  manifest.json
  scan_windows-redacted.json
  dump_uia-main-redacted.json
  • For optional mode B, confirm the package states n12_status = offline_pre_only_not_n12_pass and uses only:
version
self_check
scan_windows
dump_uia

Expected outputs:

  • Full sandbox artifact bundle for read-only offline inventory, or optional minimal UIA JSON package for advanced users.
  • Package is labeled as offline/pre-gate evidence.
  • N12 pass status remains tied to the real live-capture gate.

Acceptance conditions:

Pass if:

  • In mode A, the copied bundle preserves directory structure and includes at least one useful raw/ source area plus copy-notes.txt when available.
  • In mode A, repository-side handling is inventory-focused: preserve original copied files and inspect copies/metadata first.
  • In mode B, required JSON files exist and parse as JSON, and the manifest records offline pre-evidence status.
  • For both modes, the route stays focused on evidence intake and source discovery for the core MCP tools.

Stop conditions:

  • Any step requires the user to understand JSON before they can provide the recommended full bundle.
  • Binary execution is deferred to a separately prepared runtime task.
  • Original copied files lose their preserved evidence state.
  • Package scope expands beyond evidence intake and source discovery.
  • Any reader treats the offline package as a replacement for true N12.

Next node: N12R internal-sandbox live capture route if live UI evidence is needed. N12-current remains blocked in the outer-network environment.

N12R: Internal-sandbox live capture route

Purpose: Capture live iSphere UIA evidence from a separate internal-network test sandbox where iSphere can be manually opened and logged in.

Preconditions:

  • N11 accepted.
  • Optional N12-pre offline evidence, if used, has been validated only as pre-gate context and not as live capture evidence.
  • An internal-network test sandbox can manually open and log in to iSphere / IMPlatformClient using the normal company login process.
  • The internal sandbox has this repository or a trusted copy of the built helper/MCP artifacts.
  • The operator follows docs/internal-sandbox-operator-runbook.md.

Actions:

  • In the internal sandbox, run only the first-phase read-only operations:
win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia

or the equivalent helper ops:

version
self_check
scan_windows
dump_uia
  • Save the returned package under:
runs/internal-sandbox-live-capture/<capture-id>/
  • Follow the package contract in docs/internal-sandbox-live-capture-plan.md.

Expected outputs:

  • metadata/source-notes.txt stating internal-network test sandbox, manual login, main window visible, and forbidden actions not performed.
  • helper/version.json.
  • helper/self-check.json.
  • windows/scan-windows.json.
  • windows/selected-window.json.
  • uia/dump-uia-main.json.
  • uia/dump-uia-main-redacted.json.
  • notes/operator-notes.txt.

Acceptance conditions:

Pass if:

  • The package satisfies docs/n12r-return-package-validation-checklist.md.
  • scan-windows.json includes an iSphere / IMPlatformClient candidate window.
  • dump-uia-main.json contains a UI Automation root tree for the selected window.
  • The capture notes state the user manually logged in and record the exact capture scope.
  • The redacted dump exists before broad sharing.

Stop conditions:

  • Internal sandbox cannot manually log in.
  • No candidate window appears.
  • UIA tree is empty or inaccessible.
  • Package contains secrets or message contents that require redaction before review.
  • Any step expands beyond scan/dump evidence capture into business actions or low-level client manipulation.

Next node: N12R-review selector design review gate after N12R evidence is accepted and a separate selector design plan exists.

N12-current: Current-environment real logged-in UIA capture gate (blocked)

This is the original N12 definition. It is retained as a blocked/non-active gate for historical clarity. It is not the active route while the repository environment is outside the internal network.

Blocked reason: iSphere is internal-network only, and the current repository environment cannot manually log in.

Original purpose: Capture real iSphere UIA evidence from a manually logged-in iSphere window in the same environment where this repository is running.

Original preconditions, if network placement changes later:

  • N11 accepted.
  • Optional N12-pre offline evidence, if used, has been validated only as pre-gate context and not as N12 pass evidence.
  • The repository environment can manually open and log in to iSphere / IMPlatformClient using the normal company login process.
  • iSphere main window is visible in that same environment.

Original tool actions:

Use only these Go MCP tools:

win_helper_scan_windows
win_helper_dump_uia

Save output under:

runs/real-loggedin-lab/uia-dumps/

Current decision: Active route uses N12R internal-sandbox live capture instead of waiting on this gate.

Next node: Future selector design follows accepted N12R evidence, or a passed N12-current gate, plus a separate selector design plan.

3. Global Acceptance Rules

Every node must satisfy these rules:

  1. Go MCP remains the active implementation path.
  2. Core contact/group/message/file tools follow docs/mcp-core-tools-contract.md.
  3. UIA/helper work stays behind internal/helperclient and supports source discovery or fallback connector work.
  4. Stage exact paths.
  5. Every code node uses tests first.
  6. Every completion claim needs a fresh verification command.
  7. Every failed gate produces a short report before continuing.

4. Current Next Node

Current guidance after N0-N15 remote updates is:

当前下一步：MCP 核心工具合同冻结 + 只读消息源 discovery + N12-pre 证据包整理。

Immediate next action:

Use `docs/mcp-core-tools-contract.md` and `docs/mcp-core-business-plan.md` as the active business route. Prioritize `isphere_search_contacts`, `isphere_search_groups`, `isphere_receive_messages`, and `isphere_receive_files`, then move `isphere_send_message` and `isphere_send_file` into Stage D after source discovery and connector verification.

N12-pre offline evidence remains pre-gate context. Existing UIA selector/report work is auxiliary evidence and fallback support only; the project core is MCP communication capability for contacts, groups, messages, and files.

Reference in New Issue View Git Blame Copy Permalink