feat: register isphere receive messages tool
This commit is contained in:
zhaoyilun
@@ -1,7 +1,7 @@
|
||||
# Capability Source Matrix
|
||||
|
||||
Date: 2026-07-09
|
||||
Stage: B source discovery
|
||||
Stage: C log-backed receive implementation
|
||||
Evidence index: `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md`
|
||||
Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
|
||||
|
||||
@@ -17,7 +17,7 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
|
||||
|
||||
| MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` stanzas | decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces; wrapped `MsgLib.db` after DB wrapper is solved | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | selected for Stage C log-backed parser | first |
|
||||
| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` stanzas via `internal/isphere.EncryptedPacketLogSource` | decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces; wrapped `MsgLib.db` after DB wrapper is solved | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | C3 registered and unit-verified; default server source is empty until operator verification/loader wiring | fixture-backed operator verification and docs |
|
||||
| `isphere_search_contacts` | decrypted packet/send-receive JIDs and later roster stanzas from `Smark.SendReceive` | `MsgLib.db` contact/conversation tables after DB wrapper is solved; UIA helper source if display names are missing | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#log-decryption-result` | candidate pending parser coverage | second |
|
||||
| `isphere_search_groups` | decrypted XMPP group/message stanzas if groupchat/group JIDs appear | `MsgLib.db` group/conversation tables after DB wrapper is solved; UIA helper source if group display names are missing | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | candidate pending group stanza evidence | third |
|
||||
| `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas plus `zyl\importal\<hash>` cache mapping | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | candidate pending cache-reference mapping | fourth |
|
||||
|
||||
@@ -655,7 +655,7 @@ Implemented and verified in this loop:
|
||||
- Tool source: `isphere.EncryptedPacketLogSource.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: input.Limit})`.
|
||||
- Tool output shape: a map/object with `messages`, where each message carries `id`, `conversation_id`, `conversation_type`, `sender_id`, `receiver_id`, `text`, `timestamp`, `subject`, `receipt_id`, and `read`.
|
||||
|
||||
- [ ] **Step 1: Write failing tool registration tests**
|
||||
- [x] **Step 1: Write failing tool registration tests**
|
||||
|
||||
Add or update tests so they fail before implementation:
|
||||
|
||||
@@ -666,19 +666,19 @@ go test ./internal/mcpserver -run TestNewServerRegistersN8WinHelperToolsWithoutC
|
||||
|
||||
Expected initial failures: `isphere_receive_messages` is not registered and the server/tool lists still expose only the four helper tools.
|
||||
|
||||
- [ ] **Step 2: Implement `internal/tools/isphere_read.go`**
|
||||
- [x] **Step 2: Implement `internal/tools/isphere_read.go`**
|
||||
|
||||
Register `isphere_receive_messages` with `mcp.AddTool`, convert the C2 `isphere.Message` slice into the explicit JSON/map output shape, and keep the only public input parameter as `limit`. Use a source interface so tests can inject a synthetic C2 source without raw evidence files.
|
||||
|
||||
- [ ] **Step 3: Register business read tool in `mcpserver.NewServer`**
|
||||
- [x] **Step 3: Register business read tool in `mcpserver.NewServer`**
|
||||
|
||||
Register the helper tools plus `isphere_receive_messages`. If no live log-line loader exists yet, wire an empty `isphere.EncryptedPacketLogSource{}` as the default so registration is testable without committing raw logs.
|
||||
|
||||
- [ ] **Step 4: Update existing helper-tool guard tests**
|
||||
- [x] **Step 4: Update existing helper-tool guard tests**
|
||||
|
||||
Rename or adjust the old “exactly four” helper test so it still blocks forbidden write/sending tool names but explicitly allows `isphere_receive_messages`. Update `internal/mcpserver/server_test.go` to expect five tools: four helper tools plus `isphere_receive_messages`.
|
||||
|
||||
- [ ] **Step 5: Run full verification**
|
||||
- [x] **Step 5: Run full verification**
|
||||
|
||||
Run:
|
||||
|
||||
@@ -690,22 +690,75 @@ go build ./cmd/isphere-mcp
|
||||
|
||||
Expected: all exit 0.
|
||||
|
||||
- [ ] **Step 6: Commit Loop C3 and rewrite Loop C4**
|
||||
- [x] **Step 6: Commit Loop C3 and rewrite Loop C4**
|
||||
|
||||
Commit exact C3 paths only. Rewrite Loop C4 around the actual MCP tool output shape and the fact that default server wiring has no raw evidence loader yet.
|
||||
|
||||
---
|
||||
|
||||
## Loop C3 Result
|
||||
|
||||
Implemented and verified in this loop:
|
||||
|
||||
- `internal/tools.RegisterISphereReadTools(server, source)` registers `isphere_receive_messages` with a single public input parameter: `limit`.
|
||||
- `internal/tools.ToolNameReceiveMessages` is `isphere_receive_messages`.
|
||||
- The tool calls the C2 source interface with `isphere.ReceiveMessagesQuery{Limit: input.Limit}` and returns structured content shaped as `messages: [{ id, conversation_id, conversation_type, sender_id, receiver_id, text, timestamp, subject, receipt_id, read }]`.
|
||||
- `internal/mcpserver.NewServer()` now registers four WinHelper observation tools plus `isphere_receive_messages`; default source wiring uses an empty `isphere.EncryptedPacketLogSource{}` so no raw evidence is committed or loaded by default.
|
||||
- Guard tests still keep helper tools scoped to helper observation operations while allowing `receive` as a legitimate read capability name for the new business tool.
|
||||
- Verification completed for C3 with `git diff --check`, `go test ./...`, and `go build ./cmd/isphere-mcp`; the generated root `isphere-mcp.exe` build artifact was removed.
|
||||
- Loop C4 was rewritten around the actual five-tool surface and empty default source behavior.
|
||||
|
||||
---
|
||||
|
||||
## Loop C4: Operator verification and docs
|
||||
|
||||
**Current draft goal:** Add a verification command or fixture-backed smoke test for `isphere_receive_messages` and update user-facing docs.
|
||||
**Goal:** Update the repeatable operator verification and user-facing docs for the five-tool surface after C3 registers `isphere_receive_messages`.
|
||||
|
||||
**Planned files:**
|
||||
- Modify: `scripts/verify-go-mcp.ps1`
|
||||
- Modify: `docs/go-mcp-runbook.md`
|
||||
- Modify: `docs/current-status-card.md`
|
||||
- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`
|
||||
|
||||
**Rewrite rule before implementation:** Only write this loop after C3 confirms the actual MCP response shape.
|
||||
**Interfaces from Loop C3:**
|
||||
- Server tool list: four WinHelper observation tools plus `isphere_receive_messages`.
|
||||
- Default `isphere_receive_messages` source: `isphere.EncryptedPacketLogSource{}` with no configured lines, so the operator smoke call should return `messages: []` until a real evidence loader is wired.
|
||||
- Verification script should still call `win_helper_version`, and should additionally call `isphere_receive_messages` with a small `limit` and assert the returned `messages` field is an array.
|
||||
|
||||
- [ ] **Step 1: Capture current verification red state**
|
||||
|
||||
Run before editing the script:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1
|
||||
```
|
||||
|
||||
Expected: FAIL because the existing harness still expects exactly four tools and treats `receive` as a forbidden term.
|
||||
|
||||
- [ ] **Step 2: Update `scripts/verify-go-mcp.ps1`**
|
||||
|
||||
Change expected tools to five, remove `receive` from the forbidden write/scope terms, and add an SDK call to `isphere_receive_messages` with `{ "limit": 5 }`. Assert `messages` exists and is an array; for the default empty source, assert the smoke result has zero messages.
|
||||
|
||||
- [ ] **Step 3: Update operator docs**
|
||||
|
||||
Update `docs/go-mcp-runbook.md` and `docs/current-status-card.md` so they describe the current five-tool surface, the empty default read source, and the fact that raw N12-pre evidence still stays under ignored `runs/` paths.
|
||||
|
||||
- [ ] **Step 4: Run full verification**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git diff --check
|
||||
go test ./...
|
||||
go build ./cmd/isphere-mcp
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1
|
||||
```
|
||||
|
||||
Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build.
|
||||
|
||||
- [ ] **Step 5: Commit Loop C4 and rewrite next loop**
|
||||
|
||||
Commit exact C4 paths only. Rewrite the next loop around the remaining gap: a safe configurable source loader or fixture path for `isphere_receive_messages`, without committing raw evidence.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user