docs: realign iSphere bridge around core MCP capabilities

docs/mcp-core-business-plan.md

@@ -0,0 +1,145 @@
+# MCP Core Business Plan
+
+Date: 2026-07-09
+
+## Business correction
+
+项目核心不是继续做 UIA selector/report，而是通过 MCP 暴露 iSphere 的联系人、群组、消息、文件能力。
+
+后续研发主线切换为 MCP 核心通信能力：搜索联系人、搜索群组、收发消息、收发文件。现有 UIA/selector/report 只作为底层辅助和证据，不再作为主线继续扩展。
+
+## Core business capabilities
+
+The product roadmap is limited to six business capabilities:
+
+1. Search contacts.
+2. Search groups.
+3. Receive/read messages.
+4. Send messages.
+5. Receive/download files.
+6. Send files.
+
+Everything else is infrastructure or fallback support. Selector catalog/report validation may support UI automation if needed, but it is not the main product deliverable.
+
+## Capability source priority
+
+Use this priority order when searching for real implementations:
+
+1. Existing bridge / API / local service.
+2. Local database / log / cache read-only access.
+3. UI automation.
+4. Network/API analysis.
+5. Reverse engineering, only for explanation and validation, not as the default route.
+
+Implications:
+
+- Prefer an existing bridge/API/local service before reading local storage or using UIA.
+- Prefer read-only database/log/cache access before UI automation when it can answer the business question.
+- UIA selector work is a fallback access mechanic, not the primary roadmap.
+- Do not continue investing in selector report hardening unless a concrete business tool is blocked by selector quality.
+- Reverse engineering is last resort and should explain formats or validate assumptions; it should not become the default delivery path.
+
+## Stage A: Freeze MCP core tools contract
+
+Goal: lock the business-facing MCP tool surface before adding more helper or selector work.
+
+Deliverables:
+
+- `docs/mcp-core-tools-contract.md` exists and defines:
+  - `isphere_search_contacts`
+  - `isphere_search_groups`
+  - `isphere_receive_messages`
+  - `isphere_send_message`
+  - `isphere_receive_files`
+  - `isphere_send_file`
+- Write-capable tools require `approval_id` for real execution.
+- Write-capable tools support `dry_run=true` and default to dry-run until approved.
+- Read-only tools do not mutate the iSphere client state.
+
+Acceptance:
+
+- Contract names, input parameters, output JSON, error codes, audit fields, read-only/write status, approval behavior, and implementation priority are explicit.
+- No new selector/report node is introduced as the next primary step.
+
+## Stage B: Find real capability sources
+
+Goal: identify the best source for each read-only capability.
+
+Tasks:
+
+1. Inventory existing bridge/API/local service artifacts and current Go/C# boundaries.
+2. Re-check whether existing bridge endpoints or local services can provide contacts, groups, messages, or files.
+3. Re-check local database/log/cache artifacts only in read-only mode.
+4. Use UIA only if higher-priority sources cannot satisfy the read-only tool.
+5. Document source decisions per tool before implementation.
+
+Acceptance:
+
+- Each read-only tool has a selected primary source and a fallback source.
+- The decision is evidence-backed and does not rely on stale prior notes without current verification.
+- No automatic login, hook, injection, memory read, or endpoint-security bypass is introduced.
+
+## Stage C: Read-only loop
+
+Goal: deliver useful MCP read capability before any real write capability.
+
+Implementation order:
+
+1. `isphere_search_contacts`
+2. `isphere_search_groups`
+3. `isphere_receive_messages`
+4. `isphere_receive_files`
+
+Acceptance:
+
+- Each tool can return normalized JSON through MCP.
+- Each tool records audit metadata.
+- File receiving/download writes only to an approved local output directory and never mutates source client state.
+- Tests and verification do not send messages, upload files, click destructive controls, or alter production data.
+
+## Stage D: Approval-after-read-only write capability
+
+Goal: add write behavior only after the read-only loop is proven.
+
+Implementation order:
+
+1. `isphere_send_message` with `dry_run=true` preview first.
+2. Approval store and audit validation.
+3. `isphere_send_message` real send only with valid `approval_id`.
+4. `isphere_send_file` with `dry_run=true` preview first.
+5. `isphere_send_file` real send only with valid `approval_id`.
+
+Acceptance:
+
+- No valid `approval_id`, no real send.
+- Every real send records target, content/file hash, approver, time, connector, and result.
+- Idempotency prevents accidental duplicate sends.
+- Operator can review dry-run output before approval.
+
+## Stage E: Pre-production safety, audit, and deployment acceptance
+
+Goal: make the MCP service safe and operable before broader use.
+
+Checks:
+
+- Tool allowlist and source allowlist are explicit.
+- Audit records are durable and redacted where needed.
+- Approval records are traceable.
+- Deployment docs include exact commands, rollback, logs, and known limits.
+- Security boundaries are still enforced: no automatic login, no bypass, no injection, no hook, no target-process memory read.
+
+Acceptance:
+
+- Full test suite passes.
+- Operator runbook covers normal operation and failure modes.
+- A business user can understand which of the six capabilities are supported and which remain staged.
+
+## Immediate next action
+
+Current next step is:
+
+```text
+MCP core tools contract freeze + read-only message source discovery + N12-pre evidence package organization.
+```
+
+Do not start N16/N17 selector/report hardening as the mainline. If UIA is needed later, use the existing N13/N14/N15 results as auxiliary evidence only.