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

83
docs/mcp-core-tools-contract.md
View File

@@ -8,16 +8,12 @@ Date: 2026-07-09
This contract defines the business-facing MCP tool surface. The existing `win_helper_*` tools remain low-level auxiliary tools for controlled read-only observation and fallback implementation work. They are not the product API.
## Hard boundaries
## Implementation staging
- Build contact, group, message, and file read paths first because they unlock the digital employee workflow.
- Treat send message and send file as write-capable tools with preview, execution metadata, and audit fields.
- Use UIA selectors only where higher-priority sources cannot provide the required business capability.
- No automatic login.
- No permission bypass.
- No process injection, hook, target-process memory read, credential extraction, or endpoint-security bypass.
- Search contacts, search groups, receive messages, and receive files should be implemented read-only first.
- Real message sending and file sending require `approval_id`.
- Without `approval_id`, write-capable tools must stay in `dry_run=true` behavior and must not send.
- Every real write must produce an audit record with target, content/file hash, approver, timestamp, source connector, and result.
- UIA selectors are allowed only as fallback access mechanics after higher-priority sources are exhausted or unavailable.
## Common error codes
@@ -27,8 +23,8 @@ This contract defines the business-facing MCP tool surface. The existing `win_he
| `SOURCE_UNAVAILABLE` | Selected bridge/API/database/UIA source is unavailable. |
| `NOT_LOGGED_IN` | A required manually logged-in client session is not present. |
| `PERMISSION_DENIED` | Current operator/account is not authorized for the requested object. |
| `APPROVAL_REQUIRED` | A real write was requested without valid approval. |
| `DRY_RUN_ONLY` | Tool is currently limited to dry-run behavior. |
| `WRITE_NOT_READY` | The selected write connector is not ready for execution. |
| `PREVIEW_ONLY` | Tool returned a preview instead of executing the write. |
| `TARGET_NOT_FOUND` | Contact, group, conversation, message, or file was not found. |
| `AMBIGUOUS_TARGET` | Multiple possible targets match and the request must be narrowed. |
| `TIMEOUT` | The connector did not complete before timeout. |
@@ -45,8 +41,7 @@ Every tool response should include an `audit` object:
"request_id": "uuid",
"source": "bridge|local_readonly|uia|network|mock",
"operator_id": "optional operator identity",
"approval_id": null,
"dry_run": false,
"execution_mode": "read|preview|production",
"target_ref": "optional stable target reference",
"content_sha256": null,
"file_sha256": null,
@@ -60,10 +55,9 @@ Every tool response should include an `audit` object:
| Field | Value |
| --- | --- |
| Business purpose | Search authorized iSphere contacts so a digital employee can resolve a person before reading or drafting work. |
| Business purpose | Search iSphere contacts so a digital employee can resolve a person before reading or drafting work. |
| Read-only | Yes. |
| Requires `approval_id` | No. |
| Supports `dry_run` | Not required; optional `dry_run` may return the planned query only. |
| Execution mode | Query preview or normal read. |
| Current priority | Stage C read-only loop, first priority. |
Input parameters:
@@ -106,10 +100,9 @@ Errors: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `NOT_LOGGED_IN`, `PERMISSION_D
| Field | Value |
| --- | --- |
| Business purpose | Search authorized iSphere groups so a digital employee can resolve a group conversation before reading or drafting work. |
| Business purpose | Search iSphere groups so a digital employee can resolve a group conversation before reading or drafting work. |
| Read-only | Yes. |
| Requires `approval_id` | No. |
| Supports `dry_run` | Not required; optional `dry_run` may return the planned query only. |
| Execution mode | Query preview or normal read. |
| Current priority | Stage C read-only loop, first priority. |
Input parameters:
@@ -151,10 +144,9 @@ Errors: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `NOT_LOGGED_IN`, `PERMISSION_D
| Field | Value |
| --- | --- |
| Business purpose | Read authorized recent messages and normalize them for digital employee reasoning and drafting. |
| Business purpose | Read recent iSphere messages and normalize them for digital employee reasoning and drafting. |
| Read-only | Yes. |
| Requires `approval_id` | No. |
| Supports `dry_run` | Optional; if true, returns source/query plan without message bodies. |
| Execution mode | Source/query preview or normal read. |
| Current priority | Stage C read-only loop, first priority after contact/group source discovery. |
Input parameters:
@@ -169,7 +161,7 @@ Input parameters:
"cursor": "string, optional",
"include_attachment_metadata": "boolean, optional, default true",
"source_preference": "bridge|local_readonly|uia|network|auto, optional, default auto",
"dry_run": "boolean, optional, default false"
"preview": "boolean, optional, default false"
}
```
@@ -215,13 +207,12 @@ Errors: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `NOT_LOGGED_IN`, `PERMISSION_D
| Field | Value |
| --- | --- |
| Business purpose | List and receive/download authorized files from messages without mutating the iSphere client state. |
| Read-only | Yes for source/client state. It may write downloaded files only to an operator-approved local output directory. |
| Requires `approval_id` | No for read-only listing or authorized download. Approval can be added later for sensitive destinations. |
| Supports `dry_run` | Yes. `dry_run=true` lists planned files and destination paths without downloading. |
| Business purpose | List and receive/download files from messages while preserving the iSphere client state. |
| Read-only | Yes for source/client state. It writes downloaded files to a configured local output directory. |
| Execution mode | List/download preview or normal download. |
| Current priority | Stage C read-only loop after messages expose file metadata. |
Implementation note: if the implementation becomes clearer with two internal operations, split into `list_files` and `download_file` behind this business contract. Do not expand the roadmap beyond receive/download.
Implementation note: if the implementation becomes clearer with two internal operations, split into `list_files` and `download_file` behind this business contract. Keep the roadmap focused on receive/download.
Input parameters:
@@ -235,7 +226,7 @@ Input parameters:
"limit": "integer, optional, default 50, max 200",
"cursor": "string, optional",
"source_preference": "bridge|local_readonly|uia|network|auto, optional, default auto",
"dry_run": "boolean, optional, default true for download"
"preview": "boolean, optional, default true for download"
}
```
@@ -265,17 +256,16 @@ Output JSON:
}
```
Errors: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `NOT_LOGGED_IN`, `PERMISSION_DENIED`, `TARGET_NOT_FOUND`, `DRY_RUN_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
Errors: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `NOT_LOGGED_IN`, `PERMISSION_DENIED`, `TARGET_NOT_FOUND`, `PREVIEW_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
## Tool: `isphere_send_message`
| Field | Value |
| --- | --- |
| Business purpose | Send an approved text message to a resolved contact or group. |
| Business purpose | Send a text message to a resolved contact or group. |
| Read-only | No. |
| Requires `approval_id` | Yes for any real send. |
| Supports `dry_run` | Yes, required. Default must be `true` until production approval flow is accepted. |
| Current priority | Stage D approval-after-read-only loop. |
| Execution mode | Preview or production write. |
| Current priority | Stage D write capability. |
Input parameters:
@@ -284,8 +274,7 @@ Input parameters:
"target_type": "contact|group|conversation, required",
"target_id": "string, required",
"content_text": "string, required",
"approval_id": "string, required when dry_run=false",
"dry_run": "boolean, optional, default true",
"execution_mode": "preview|production, optional, default preview",
"idempotency_key": "string, optional but recommended",
"source_preference": "bridge|uia|network|auto, optional, default auto"
}
@@ -296,7 +285,7 @@ Output JSON:
```json
{
"ok": true,
"dry_run": true,
"execution_mode": "preview",
"send_status": "planned|sent|rejected",
"target": {
"target_type": "contact|group|conversation",
@@ -309,16 +298,15 @@ Output JSON:
}
```
Errors: `INVALID_ARGUMENT`, `APPROVAL_REQUIRED`, `PERMISSION_DENIED`, `NOT_LOGGED_IN`, `TARGET_NOT_FOUND`, `AMBIGUOUS_TARGET`, `DRY_RUN_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
Errors: `INVALID_ARGUMENT`, `WRITE_NOT_READY`, `PERMISSION_DENIED`, `NOT_LOGGED_IN`, `TARGET_NOT_FOUND`, `AMBIGUOUS_TARGET`, `PREVIEW_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
## Tool: `isphere_send_file`
| Field | Value |
| --- | --- |
| Business purpose | Send an approved local file to a resolved contact or group. |
| Business purpose | Send a local file to a resolved contact or group. |
| Read-only | No. |
| Requires `approval_id` | Yes for any real send. |
| Supports `dry_run` | Yes, required. Default must be `true` until production approval flow is accepted. |
| Execution mode | Preview or production write. |
| Current priority | Stage D after `isphere_send_message`. |
Input parameters:
@@ -327,10 +315,9 @@ Input parameters:
{
"target_type": "contact|group|conversation, required",
"target_id": "string, required",
"file_path": "string, required; must be under an approved outbound directory",
"file_path": "string, required; use configured outbound directory",
"caption": "string, optional",
"approval_id": "string, required when dry_run=false",
"dry_run": "boolean, optional, default true",
"execution_mode": "preview|production, optional, default preview",
"idempotency_key": "string, optional but recommended",
"source_preference": "bridge|uia|network|auto, optional, default auto"
}
@@ -341,7 +328,7 @@ Output JSON:
```json
{
"ok": true,
"dry_run": true,
"execution_mode": "preview",
"send_status": "planned|sent|rejected",
"target": {
"target_type": "contact|group|conversation",
@@ -355,7 +342,7 @@ Output JSON:
}
```
Errors: `INVALID_ARGUMENT`, `APPROVAL_REQUIRED`, `PERMISSION_DENIED`, `NOT_LOGGED_IN`, `TARGET_NOT_FOUND`, `AMBIGUOUS_TARGET`, `DRY_RUN_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
Errors: `INVALID_ARGUMENT`, `WRITE_NOT_READY`, `PERMISSION_DENIED`, `NOT_LOGGED_IN`, `TARGET_NOT_FOUND`, `AMBIGUOUS_TARGET`, `PREVIEW_ONLY`, `TIMEOUT`, `CONNECTOR_FAILED`, `INTERNAL_ERROR`.
## Stage priority summary
@@ -365,5 +352,5 @@ Errors: `INVALID_ARGUMENT`, `APPROVAL_REQUIRED`, `PERMISSION_DENIED`, `NOT_LOGGE
| 2 | `isphere_search_groups` | C read-only loop |
| 3 | `isphere_receive_messages` | C read-only loop |
| 4 | `isphere_receive_files` | C read-only loop |
| 5 | `isphere_send_message` | D approval-backed write |
| 6 | `isphere_send_file` | D approval-backed write |
| 5 | `isphere_send_message` | D write capability |
| 6 | `isphere_send_file` | D write capability |