475 lines
18 KiB
Markdown
475 lines
18 KiB
Markdown
# MCP Core Source Discovery Loop Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Prepare and execute the next development loop: turn the downloaded N12-pre evidence package into source decisions for the MCP core contact/group/message/file tools.
|
|
|
|
**Architecture:** The next loop is Stage B source discovery before Stage C implementation. It inventories copied iSphere / IMPlatformClient evidence, records capability-source decisions, then opens the first implementation slice only after the selected source is clear.
|
|
|
|
**Tech Stack:** Go 1.23.4, PowerShell, 7-Zip, Markdown decision records, existing Go MCP server, existing C# WinHelper.
|
|
|
|
## Global Constraints
|
|
|
|
- Repository root: `E:\coding\codex\isphere-ai-bridge`.
|
|
- Remote name: `gitea`; active branch: `main`; local starting commit for this plan: `e993ce1`.
|
|
- Code search rule from `AGENTS.md`: use `git ls-files`, `ag`, or `grep -R`; do not use `rg`.
|
|
- Evidence archive path: `E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\zyl-qqfile-20260709\archives\zyl.rar`.
|
|
- Evidence SHA256: `126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173`.
|
|
- Raw evidence stays under `runs/`; normal commits contain docs/source/code, not the raw archive.
|
|
- Product route: the six MCP core tools in `docs/mcp-core-tools-contract.md`.
|
|
- Stage order for this loop: source discovery first, then read-loop implementation, then write capability.
|
|
- Commit cadence: one small commit per accepted loop node.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Modify: `E:\coding\codex\isphere-ai-bridge\docs\current-status-card.md` — keep current loop pointer accurate.
|
|
- Create/modify: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\README.md` — live loop ledger and working rules for source discovery.
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\2026-07-09-n12-pre-zyl-index.md` — evidence index extracted from archive metadata and later extraction summaries.
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\capability-source-matrix.md` — decision table mapping each MCP core tool to primary/fallback source.
|
|
- Later implementation files after decisions are accepted:
|
|
- `E:\coding\codex\isphere-ai-bridge\internal\isphere\source.go`
|
|
- `E:\coding\codex\isphere-ai-bridge\internal\isphere\source_test.go`
|
|
- `E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools.go`
|
|
- `E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools_test.go`
|
|
|
|
---
|
|
|
|
### Task 1: Start the source-discovery loop ledger
|
|
|
|
**Files:**
|
|
- Modify: `E:\coding\codex\isphere-ai-bridge\docs\current-status-card.md`
|
|
- Create/modify: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\README.md`
|
|
|
|
**Interfaces:**
|
|
- Consumes: current Git state, `docs/mcp-core-tools-contract.md`, `docs/mcp-core-business-plan.md`.
|
|
- Produces: a single visible loop entry point for the next worker.
|
|
|
|
- [ ] **Step 1: Refresh repo state**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git fetch gitea
|
|
git status --short --branch
|
|
git log --oneline -3
|
|
```
|
|
|
|
Expected:
|
|
|
|
```text
|
|
## main...gitea/main [ahead 2]
|
|
e993ce1 docs: trim safety constraints from mcp roadmap
|
|
cfc7787 docs: realign iSphere bridge around core MCP capabilities
|
|
```
|
|
|
|
- [ ] **Step 2: Update `docs/current-status-card.md`**
|
|
|
|
Set the loop base line:
|
|
|
|
```markdown
|
|
Loop base: `e993ce1 docs: trim safety constraints from mcp roadmap`
|
|
Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-report-hardening'`
|
|
```
|
|
|
|
Add this current-loop block:
|
|
|
|
```markdown
|
|
## Current loop
|
|
|
|
Current loop: `Stage B1 - source discovery from N12-pre zyl package`.
|
|
|
|
Plan file: `docs/superpowers/plans/2026-07-09-mcp-core-source-discovery-loop.md`.
|
|
|
|
Loop output:
|
|
|
|
1. Evidence index for downloaded `zyl.rar` package.
|
|
2. Capability-source matrix for the four read tools:
|
|
- `isphere_search_contacts`
|
|
- `isphere_search_groups`
|
|
- `isphere_receive_messages`
|
|
- `isphere_receive_files`
|
|
3. Selected first Stage C implementation slice.
|
|
```
|
|
|
|
- [ ] **Step 3: Create the loop ledger**
|
|
|
|
Create `docs/source-discovery/README.md` with this content:
|
|
|
|
```markdown
|
|
# Source Discovery Ledger
|
|
|
|
Date: 2026-07-09
|
|
Current loop: Stage B1 - N12-pre zyl evidence source discovery
|
|
|
|
## Objective
|
|
|
|
Find the best real capability source for the MCP core read tools before implementing Stage C.
|
|
|
|
## Inputs
|
|
|
|
- `runs/offline-evidence-intake/zyl-qqfile-20260709/archives/zyl.rar`
|
|
- `runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/archive-list.txt`
|
|
- `runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/sha256.txt`
|
|
- `docs/mcp-core-tools-contract.md`
|
|
- `docs/mcp-core-business-plan.md`
|
|
|
|
## Loop cadence
|
|
|
|
1. Inventory evidence.
|
|
2. Identify source candidates.
|
|
3. Map candidates to MCP tools.
|
|
4. Select primary/fallback source per tool.
|
|
5. Open one Stage C implementation slice.
|
|
6. Verify with `go test ./...`, `go build ./cmd/isphere-mcp`, and MCP verification script.
|
|
7. Commit exact paths.
|
|
|
|
## Current target order
|
|
|
|
1. `isphere_receive_messages`
|
|
2. `isphere_search_contacts`
|
|
3. `isphere_search_groups`
|
|
4. `isphere_receive_files`
|
|
|
|
Reason: message source discovery is the current blocker; contacts/groups can be derived or selected after the message source shape is known.
|
|
|
|
## Current plan
|
|
|
|
See `docs/superpowers/plans/2026-07-09-mcp-core-source-discovery-loop.md`.
|
|
```
|
|
|
|
- [ ] **Step 4: Verify docs diff**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git diff --check
|
|
git diff -- docs/current-status-card.md docs/source-discovery/README.md
|
|
```
|
|
|
|
Expected: `git diff --check` exits 0 and the diff only touches the two listed docs.
|
|
|
|
- [ ] **Step 5: Commit Task 1**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git add -- docs/current-status-card.md docs/source-discovery/README.md
|
|
git diff --cached --check
|
|
git commit -m "docs: start mcp source discovery loop"
|
|
```
|
|
|
|
Expected: commit succeeds.
|
|
|
|
---
|
|
|
|
### Task 2: Build the N12-pre zyl evidence index
|
|
|
|
**Files:**
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\2026-07-09-n12-pre-zyl-index.md`
|
|
- Read local input: `E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\archive-list.txt`
|
|
|
|
**Interfaces:**
|
|
- Consumes: archive metadata, `archive-list.txt`, `sha256.txt`.
|
|
- Produces: a reviewable evidence index without committing raw evidence files.
|
|
|
|
- [ ] **Step 1: Confirm archive metadata and candidate paths**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
Get-Content -LiteralPath runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\sha256.txt
|
|
Select-String -LiteralPath runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\archive-list.txt -Pattern 'MsgLib\.db|Smark\.SendReceive|SaveToDB|PacketReader\.ProcessPacket|LoginInfo|System\.Data\.SQLite|importal\\[0-9a-f]{32}' -CaseSensitive:$false | Select-Object -First 200
|
|
```
|
|
|
|
Expected: sha256 matches `126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173`; candidate file paths are visible.
|
|
|
|
- [ ] **Step 2: Create the evidence index file**
|
|
|
|
Create `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md` with this concrete starting content, then extend it only with exact paths from `archive-list.txt`:
|
|
|
|
```markdown
|
|
# N12-pre zyl Evidence Index
|
|
|
|
Date: 2026-07-09
|
|
Evidence id: `zyl-qqfile-20260709`
|
|
Archive: `runs/offline-evidence-intake/zyl-qqfile-20260709/archives/zyl.rar`
|
|
SHA256: `126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173`
|
|
Archive type: RAR5
|
|
Archive listing summary: 3931 files, 439 folders
|
|
|
|
## Candidate source families
|
|
|
|
| Family | Evidence path examples | Why it matters | Initial action |
|
|
| --- | --- | --- | --- |
|
|
| SQLite runtime | `zyl\iSphere\System.Data.SQLite.dll`; `zyl\Impp\System.Data.SQLite.dll` | Confirms bundled SQLite usage around message libraries | record versions and inspect dependent DB files |
|
|
| iSphere message DB | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db`; `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\duyanming0731\MsgLib.db` | Strong candidate for `isphere_receive_messages`, contacts, groups, and attachment references | extract selected DB copies and inspect schema |
|
|
| IMPP message DB | `zyl\Impp\Account\90005981\MsgLib.db`; `zyl\Impp\Account\27091282\MsgLib.db` | Older or parallel candidate source for message history | compare schema with iSphere DB |
|
|
| Local communication logs | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\Smark.SendReceive\2026-07-07_1.log`; `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\SaveToDB\2026-07-07_1.log`; `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\PacketReader.ProcessPacket\2026-07-07_1.log` | Candidate execution trace for message receive/save behavior | inspect log structure and timestamp alignment |
|
|
| Login/info logs | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\LoginInfo\2026-07-07_1.log` | Candidate account/session context for source mapping | inspect field names and account identifiers |
|
|
| Received/document cache | `zyl\importal\256914c029af44bd96665abd69ddd500\*.xlsx`; `zyl\importal\4a33b65a33c14149b440724bfc3d912e\g.docx`; `zyl\importal\4fa0846abdbb4331a956cb056be9566a\*.pdf` | Candidate file receive/download cache for `isphere_receive_files` | map hashed directories to DB/log references |
|
|
|
|
## First extraction target list
|
|
|
|
| Priority | Archive path | Destination under runs | Reason |
|
|
| --- | --- | --- | --- |
|
|
| 1 | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/msgdb-isphere-90005981/` | latest visible iSphere message DB candidate |
|
|
| 2 | `zyl\Impp\Account\90005981\MsgLib.db` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/msgdb-impp-90005981/` | compare older or parallel IMPP DB candidate |
|
|
| 3 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\Smark.SendReceive\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-smark-90005981-20260707/` | message send/receive trace candidate |
|
|
| 4 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\SaveToDB\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-savetodb-90005981-20260707/` | DB write trace candidate |
|
|
| 5 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\LoginInfo\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-logininfo-90005981-20260707/` | account/session context candidate |
|
|
|
|
## Decision after index
|
|
|
|
Proceed to `docs/source-discovery/capability-source-matrix.md` after the first extraction target list has confirmed message DB and log candidates.
|
|
```
|
|
|
|
- [ ] **Step 3: Verify index contains concrete candidates**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
Select-String -LiteralPath docs\source-discovery\2026-07-09-n12-pre-zyl-index.md -Pattern '待补|占位'
|
|
```
|
|
|
|
Expected: no output.
|
|
|
|
- [ ] **Step 4: Commit Task 2**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git add -- docs/source-discovery/2026-07-09-n12-pre-zyl-index.md
|
|
git diff --cached --check
|
|
git commit -m "docs: index n12-pre zyl evidence sources"
|
|
```
|
|
|
|
Expected: commit succeeds.
|
|
|
|
---
|
|
|
|
### Task 3: Create the capability-source matrix
|
|
|
|
**Files:**
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\docs\source-discovery\capability-source-matrix.md`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `docs/mcp-core-tools-contract.md`, `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md`.
|
|
- Produces: source decisions that Stage C implementation can consume.
|
|
|
|
- [ ] **Step 1: Create the matrix**
|
|
|
|
Create `docs/source-discovery/capability-source-matrix.md` with this content:
|
|
|
|
```markdown
|
|
# Capability Source Matrix
|
|
|
|
Date: 2026-07-09
|
|
Stage: B source discovery
|
|
|
|
## Source priority
|
|
|
|
1. Existing bridge / API / local service.
|
|
2. Local data, log, cache, or database source.
|
|
3. UIA helper source through C# WinHelper.
|
|
4. Network/protocol source.
|
|
5. Mock source for tests only.
|
|
|
|
## Matrix
|
|
|
|
| MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| `isphere_receive_messages` | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db` | `zyl\Impp\Account\90005981\MsgLib.db` plus `Smark.SendReceive` logs | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#first-extraction-target-list` | selected after schema confirms message table | first |
|
|
| `isphere_search_contacts` | message DB contact/conversation tables after schema inspection | UIA helper source through current WinHelper if DB lacks display names | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | second |
|
|
| `isphere_search_groups` | message DB group/conversation tables after schema inspection | UIA helper source through current WinHelper if DB lacks group display names | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | third |
|
|
| `isphere_receive_files` | importal hashed document cache mapped through message DB attachment references | `Smark.SendReceive` and `SaveToDB` logs for file-reference traces | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | fourth |
|
|
|
|
## Stage C entry rule
|
|
|
|
Open implementation only after the selected row links to a concrete file or directory in the evidence index and the schema/log inspection notes state which fields map to the MCP output contract.
|
|
```
|
|
|
|
- [ ] **Step 2: Verify the matrix contains concrete candidates**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
Select-String -LiteralPath docs\source-discovery\capability-source-matrix.md -Pattern '待补|占位'
|
|
```
|
|
|
|
Expected: no output.
|
|
|
|
- [ ] **Step 3: Commit Task 3**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git add -- docs/source-discovery/capability-source-matrix.md
|
|
git diff --cached --check
|
|
git commit -m "docs: select mcp capability sources"
|
|
```
|
|
|
|
Expected: commit succeeds.
|
|
|
|
---
|
|
|
|
### Task 4: Open the first Stage C implementation slice
|
|
|
|
**Files:**
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\internal\isphere\source.go`
|
|
- Create: `E:\coding\codex\isphere-ai-bridge\internal\isphere\source_test.go`
|
|
- Modify: the current tool registration file found with `git ls-files internal | Select-String -Pattern 'tool|mcp|registry|server'`.
|
|
- Create/modify: `E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools_test.go`
|
|
|
|
**Interfaces:**
|
|
- Consumes: selected source row for `isphere_receive_messages`.
|
|
- Produces: first business MCP tool skeleton with normalized JSON and audit object.
|
|
|
|
- [ ] **Step 1: Locate current tool registration**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git ls-files internal | Select-String -Pattern 'tool|mcp|registry|server'
|
|
```
|
|
|
|
Expected: the file that registers `win_helper_version`, `win_helper_self_check`, `win_helper_scan_windows`, and `win_helper_dump_uia` is visible.
|
|
|
|
- [ ] **Step 2: Write failing test for source abstraction**
|
|
|
|
Create `internal/isphere/source_test.go` with this test:
|
|
|
|
```go
|
|
package isphere
|
|
|
|
import (
|
|
"context"
|
|
"testing"
|
|
)
|
|
|
|
func TestMockMessageSourceReturnsNormalizedMessages(t *testing.T) {
|
|
src := MockMessageSource{
|
|
Messages: []Message{
|
|
{
|
|
ID: "msg-1",
|
|
ConversationID: "conv-1",
|
|
SenderName: "测试用户",
|
|
Text: "hello",
|
|
},
|
|
},
|
|
}
|
|
|
|
got, err := src.ReceiveMessages(context.Background(), ReceiveMessagesQuery{ConversationID: "conv-1", Limit: 10})
|
|
if err != nil {
|
|
t.Fatalf("ReceiveMessages returned error: %v", err)
|
|
}
|
|
if len(got.Messages) != 1 {
|
|
t.Fatalf("message count = %d, want 1", len(got.Messages))
|
|
}
|
|
if got.Messages[0].ID != "msg-1" || got.Messages[0].ConversationID != "conv-1" {
|
|
t.Fatalf("unexpected message: %+v", got.Messages[0])
|
|
}
|
|
}
|
|
```
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
go test ./internal/isphere -run TestMockMessageSourceReturnsNormalizedMessages -v
|
|
```
|
|
|
|
Expected: FAIL because package/types do not exist yet.
|
|
|
|
- [ ] **Step 3: Implement minimal source abstraction**
|
|
|
|
Create `internal/isphere/source.go`:
|
|
|
|
```go
|
|
package isphere
|
|
|
|
import "context"
|
|
|
|
type Message struct {
|
|
ID string `json:"message_id"`
|
|
ConversationID string `json:"conversation_id"`
|
|
SenderName string `json:"sender_name"`
|
|
Text string `json:"text"`
|
|
}
|
|
|
|
type ReceiveMessagesQuery struct {
|
|
ConversationID string
|
|
Limit int
|
|
}
|
|
|
|
type ReceiveMessagesResult struct {
|
|
Messages []Message `json:"messages"`
|
|
}
|
|
|
|
type MessageSource interface {
|
|
ReceiveMessages(ctx context.Context, query ReceiveMessagesQuery) (ReceiveMessagesResult, error)
|
|
}
|
|
|
|
type MockMessageSource struct {
|
|
Messages []Message
|
|
}
|
|
|
|
func (s MockMessageSource) ReceiveMessages(ctx context.Context, query ReceiveMessagesQuery) (ReceiveMessagesResult, error) {
|
|
if query.Limit <= 0 || query.Limit > len(s.Messages) {
|
|
query.Limit = len(s.Messages)
|
|
}
|
|
out := make([]Message, 0, query.Limit)
|
|
for _, msg := range s.Messages {
|
|
if query.ConversationID != "" && msg.ConversationID != query.ConversationID {
|
|
continue
|
|
}
|
|
out = append(out, msg)
|
|
if len(out) == query.Limit {
|
|
break
|
|
}
|
|
}
|
|
return ReceiveMessagesResult{Messages: out}, nil
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Verify source abstraction**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
go test ./internal/isphere -run TestMockMessageSourceReturnsNormalizedMessages -v
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 5: Commit Task 4 source abstraction**
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
git add -- internal/isphere/source.go internal/isphere/source_test.go
|
|
git diff --cached --check
|
|
go test ./...
|
|
go build ./cmd/isphere-mcp
|
|
git commit -m "feat: add isphere message source abstraction"
|
|
```
|
|
|
|
Expected: all commands exit 0 and commit succeeds.
|
|
|
|
---
|
|
|
|
## Self-Review
|
|
|
|
- Spec coverage: this plan covers the next loop requested by the user: source discovery, evidence organization, capability-source selection, and first Stage C entry.
|
|
- Placeholder scan: the plan contains concrete paths and explicit verification commands for future generated docs.
|
|
- Type consistency: `MessageSource`, `ReceiveMessagesQuery`, `ReceiveMessagesResult`, and `MockMessageSource` are defined before use.
|
|
|
|
## Execution Handoff
|
|
|
|
Plan saved for the next loop. Recommended execution mode: one node at a time.
|
|
|
|
1. Start with Task 1 and Task 2 only.
|
|
2. Stop after the evidence index is concrete.
|
|
3. Ask the business manager to accept the selected first source.
|
|
4. Open Task 3 and Task 4 only after acceptance.
|