# 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.