admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: trim safety constraints from mcp roadmap

Browse Source
This commit is contained in:
zhaoyilun
2026-07-09 22:02:26 +08:00
parent cfc7787cdd
commit e993ce15fb
8 changed files with 172 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/go-mcp-minimal-plan.md
View File

@@ -1,8 +1,8 @@
# Go MCP Minimal Plan Nodes
> **Process rule:** This is the single active plan for the next phase. The final MCP direction is Go. Python MCP, Python tests, offline-lab/native-lab Python layers are not part of the active path.
> **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` read-only operations as MCP tools.
**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`.
@@ -33,9 +33,9 @@ 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` is not the active route unless network placement changes. Live login and live UIA capture must happen in an internal-network test sandbox through `N12R`.
**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`.
Hard rule: **no node may start until the previous node's acceptance conditions are met.**
Node order: start each node after the previous node's acceptance conditions are met.
---
@@ -43,7 +43,7 @@ Hard rule: **no node may start until the previous node's acceptance conditions a
## N0: Baseline cleanup and direction lock
**Purpose:** Ensure the project is no longer split between Python MCP and Go MCP.
**Purpose:** Align the project on the Go MCP route.
**Preconditions:**
@@ -53,13 +53,13 @@ Hard rule: **no node may start until the previous node's acceptance conditions a
**Actions:**
- Confirm tracked files only include current docs/prompts/C# helper/scripts/evidence placeholders.
- Confirm no active `src/isphere_ai_bridge`, Python MCP package, or Python test suite is tracked.
- 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.
- No Python MCP fallback path.
- Single active fallback path: Go MCP plus C# helper.
**Acceptance conditions:**
@@ -69,7 +69,7 @@ git status --short
Pass if:
- No unexpected modified or untracked files exist except the active plan file while editing.
- 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`.
@@ -157,12 +157,12 @@ Initial module name:
isphere-ai-bridge
```
Do not create server code yet.
Create only the Go module at this node; server code starts in the later server node.
**Expected outputs:**
- A Go module exists.
- No dependencies are added unless required by standard Go tooling.
- Dependencies stay limited to standard Go tooling needs.
**Acceptance conditions:**
@@ -177,7 +177,7 @@ Pass if:
- `go version` exits 0.
- `go list ./...` exits 0 or reports only the root module with no packages before packages are created.
- No Python files are added.
- Generated files stay in the Go route.
**Stop conditions:**
@@ -369,14 +369,14 @@ Pass if:
- PowerShell verification exits 0.
- Go tests exit 0.
- Test output includes a real `version` call.
- No tests click/type/send/upload/download.
- 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:** no separate commit unless tests/scripts changed.
**Commit boundary:** separate commit only when tests/scripts changed.
**Next node:** N6.
@@ -395,7 +395,7 @@ Pass if:
Evaluate one current Go MCP library or official SDK option.
Record the decision inside the implementation commit or a short docs section. Do not create a large architecture document.
Record the decision inside the implementation commit or a short docs section.
Decision must answer:
@@ -411,7 +411,7 @@ why this is enough for four tools
**Expected outputs:**
- One MCP server package is selected.
- No competing MCP framework remains in the codebase.
- One MCP framework remains in the codebase.
**Acceptance conditions:**
@@ -464,7 +464,7 @@ Optional only if it keeps `main.go` small:
internal/mcpserver/server.go
```
Do not register real tools yet if the library supports a clean empty server test. If the library requires tools immediately, register only placeholder-free real tool definitions from N8.
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:**
@@ -483,8 +483,8 @@ go build ./cmd/isphere-mcp
Pass if:
- Build exits 0.
- No Python runtime is required.
- No C# helper is launched during simple server construction tests.
- Server construction uses the Go runtime only.
- Simple server construction tests stay on the server construction path.
**Stop conditions:**
@@ -538,7 +538,7 @@ win_helper_dump_uia -> helper op dump_uia
- Four tool definitions exist.
- Tool handlers call `internal/helperclient`.
- No handler performs UI logic directly.
- Handlers delegate UI work through `internal/helperclient`.
**Acceptance conditions:**
@@ -556,13 +556,13 @@ Pass if tests prove:
- Tool schemas include only needed parameters:
- `include_all_visible` for scan.
- `hwnd`, `max_depth`, `include_text`, `max_children` for dump.
- No send/search/file tools exist.
- 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 bypasses `internal/helperclient`.
- Tool code calls helper outside `internal/helperclient`.
**Commit boundary:**
@@ -622,8 +622,8 @@ And confirms:
- Four tool names are present.
- `win_helper_version` returns `ISphereWinHelper`.
- No real iSphere login is required.
- No message/file/search action is present.
- Verification uses synthetic/local helper checks.
- Message/file/search business actions are handled by the core MCP contract route.
**Stop conditions:**
@@ -690,23 +690,20 @@ go build ./cmd/isphere-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
```
And includes these boundaries:
And describes the current tool surface:
```text
no login automation
no send message
no send file
no receive/download file
no process injection
no hook
no memory reading
win_helper_version
win_helper_self_check
win_helper_scan_windows
win_helper_dump_uia
```
**Stop conditions:**
- Runbook says Python MCP is required.
- Runbook implies sending is implemented.
- Runbook omits approval boundaries for future sends.
- 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:**
@@ -750,8 +747,8 @@ Pass if:
- `git status --short` has no output.
- Latest commits are small and tied to N3/N4/N8/N9/N10.
- No Python MCP files exist.
- No search/send/file tools exist.
- Go/C# route files are the active implementation surface.
- Business search/send/file tools remain in the core contract until implemented.
**Stop conditions:**
@@ -816,24 +813,24 @@ dump_uia
**Expected outputs:**
- Full sandbox artifact bundle for read-only offline inventory, or optional minimal UIA JSON package for advanced users.
- No claim that the current environment has a logged-in iSphere window.
- No claim that N12 passed.
- 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 read-only inventory: do not directly run unknown binaries and do not modify original copied files.
- In mode B, required JSON files exist and parse as JSON, and the manifest records offline pre-evidence only, not N12 pass.
- For both modes, the route does not design or perform automatic login, send message, send file, receive file, injection, hook, memory reading, or endpoint-security bypass.
- 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.
- Any step directly runs unknown binaries from the copied bundle.
- Any step modifies original copied files.
- Package is used to design automatic login, sending, file transfer, injection, hook, memory reading, or endpoint-security bypass.
- 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.
@@ -848,7 +845,7 @@ Pass if:
- 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 approved process.
- 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`.
@@ -898,7 +895,7 @@ 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 no forbidden action was performed.
- The capture notes state the user manually logged in and record the exact capture scope.
- The redacted dump exists before broad sharing.
**Stop conditions:**
@@ -907,9 +904,9 @@ Pass if:
- No candidate window appears.
- UIA tree is empty or inaccessible.
- Package contains secrets or message contents that require redaction before review.
- Any step requires automatic login, clicking into conversations, sending, uploading, downloading, injection, hook, memory reading, or endpoint-security bypass.
- Any step expands beyond scan/dump evidence capture into business actions or low-level client manipulation.
**Next node:** N12R-review selector design review gate. Do not implement selectors until N12R evidence is accepted and a separate selector design plan is approved.
**Next node:** N12R-review selector design review gate after N12R evidence is accepted and a separate selector design plan exists.
---
@@ -925,10 +922,10 @@ This is the original N12 definition. It is retained as a blocked/non-active gate
- 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 approved process.
- 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 allowed actions:**
**Original tool actions:**
Use only these Go MCP tools:
@@ -943,9 +940,9 @@ Save output under:
runs/real-loggedin-lab/uia-dumps/
```
**Current decision:** Do not wait on this gate as the active route. Use N12R internal-sandbox live capture instead.
**Current decision:** Active route uses N12R internal-sandbox live capture instead of waiting on this gate.
**Next node:** Future selector design may be considered only after N12R evidence is accepted, or after N12-current becomes possible and passes. Do not implement selectors before a separate selector design plan is approved.
**Next node:** Future selector design follows accepted N12R evidence, or a passed N12-current gate, plus a separate selector design plan.
---
@@ -953,13 +950,13 @@ runs/real-loggedin-lab/uia-dumps/
Every node must satisfy these rules:
1. No Python MCP code.
2. No real send/search/file action before an explicitly approved post-N12R selector/action plan.
3. No process injection, hook, credential extraction, token extraction, or memory reading.
4. No broad `git add -A`; stage exact paths.
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 stops the plan and requires a short report before continuing.
7. Every failed gate produces a short report before continuing.
---
@@ -974,7 +971,7 @@ Current guidance after N0-N15 remote updates is:
Immediate next action:
```text
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` before any write-capable tool. Keep `isphere_send_message` and `isphere_send_file` behind `dry_run=true`, `approval_id`, and audit requirements.
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.
```
Do not treat N12-pre offline evidence as N12 pass. Do not start N16/N17 selector/report hardening as the mainline. 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.
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.