terraphim/agent-tasks
16
0
Fork 0
Code Issues 85 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Generic MCP connector for session import (Phase 2 Task 2.5.3) #13

New Issue
Open
opened 2026-04-24 05:01:30 +02:00 by product-owner · 0 comments
product-owner commented 2026-04-24 05:01:30 +02:00
Copy Link

Problem Statement

Phase 2 Task 2.5.3 of the session-search spec is unchecked: there is no generic MCP connector. terraphim_sessions::connector/ ships AiderConnector, ClineConnector, and NativeClaudeConnector, but any new MCP-based coding tool (e.g. Zed, Goose, Continue, MCP-compatible IDE plugins) requires a bespoke connector. A generic McpConnector that speaks the MCP session-export contract would let users import any compliant tool's transcripts without waiting for per-tool code.

Current State

  • crates/terraphim_sessions/src/connector/mod.rs defines SessionConnector trait (async, returns Vec<Session>) and ConnectorRegistry at line ~108.
  • Existing connectors bundle parsing logic per tool (Markdown for Aider, JSON for Cline, JSONL for Claude Code).
  • MCP already standardises a resources/read + prompts/list surface consumable over stdio or SSE (terraphim_mcp_server is the other side of the same protocol).
  • grep McpConnector crates/terraphim_sessions returns zero hits.

Acceptance Criteria

  • New file crates/terraphim_sessions/src/connector/mcp.rs defines McpConnector { endpoint: McpEndpoint } where McpEndpoint = Stdio { command: String, args: Vec<String> } | Sse { url: Url }.
  • McpConnector implements SessionConnector::import(&self) -> Result<Vec<Session>> by calling resources/list then resources/read for each resource whose MIME type is application/x-terraphim-session+json or text/x-session-transcript.
  • Config lookup in ConnectorRegistry::detect_sources recognises an mcp: URL scheme and constructs the connector accordingly.
  • /sessions sources in the REPL lists any discovered MCP endpoints.
  • /sessions import --source mcp://<url> triggers the new connector.
  • Failures during MCP handshake emit a structured error with endpoint and phase (connect, list, read), not a generic anyhow chain.
  • Unit test using an in-process MCP mock server (reuse the harness from terraphim_mcp_server::tests) imports at least one session.
  • cargo test -p terraphim_sessions --lib connector::mcp passes.
  • cargo clippy -p terraphim_sessions -- -D warnings passes.

Proposed Approach

  1. Add mcp module alongside aider.rs, cline.rs, native.rs. Register in connector/mod.rs.
  2. Use the rmcp or mcp-rust-sdk crate already in the workspace (feature-gated under mcp-rust-sdk) for client-side calls; gate the connector behind feature = "mcp" to avoid pulling SDK into default builds.
  3. Define SessionResource { id, title, mime_type, updated_at } so import can decide which resources to fetch.
  4. Map MCP resource payloads onto the existing Session model via serde with a light schema-version check.
  5. Add integration test that spins up terraphim_mcp_server in-process and imports a seeded session.

Files affected:

  • crates/terraphim_sessions/src/connector/mcp.rs (new, ~250 LOC)
  • crates/terraphim_sessions/src/connector/mod.rs (~15 LOC registry)
  • crates/terraphim_sessions/Cargo.toml (add mcp feature, optional dep)
  • crates/terraphim_sessions/tests/mcp_connector_test.rs (new, ~100 LOC)

Dependencies

None. Can ship in parallel with #3 (Cline connector wiring) and #5 (Tantivy index).

Unblocks: third-party tool imports without per-tool code, and extensions to the session-search spec that cite MCP-only IDEs.

Verification

cargo test -p terraphim_sessions --features mcp --lib connector::mcp
cargo test -p terraphim_sessions --features mcp --test mcp_connector_test
cargo clippy -p terraphim_sessions --features mcp -- -D warnings
./target/debug/terraphim-agent sessions sources
./target/debug/terraphim-agent sessions import --source "mcp://stdio/path/to/server"

Scope

Single PR, estimated 350-450 LOC including tests and Cargo wiring. Completes Phase 2 Task 2.5.3.

Upstream: Implements docs/specifications/terraphim-agent-session-search-tasks.md Phase 2 Task 2.5.3 for terraphim/terraphim-ai.

## Problem Statement Phase 2 Task 2.5.3 of the session-search spec is unchecked: there is no generic MCP connector. `terraphim_sessions::connector/` ships `AiderConnector`, `ClineConnector`, and `NativeClaudeConnector`, but any new MCP-based coding tool (e.g. Zed, Goose, Continue, MCP-compatible IDE plugins) requires a bespoke connector. A generic `McpConnector` that speaks the MCP session-export contract would let users import any compliant tool's transcripts without waiting for per-tool code. ## Current State - `crates/terraphim_sessions/src/connector/mod.rs` defines `SessionConnector` trait (async, returns `Vec<Session>`) and `ConnectorRegistry` at line ~108. - Existing connectors bundle parsing logic per tool (Markdown for Aider, JSON for Cline, JSONL for Claude Code). - MCP already standardises a `resources/read` + `prompts/list` surface consumable over stdio or SSE (`terraphim_mcp_server` is the other side of the same protocol). - `grep McpConnector crates/terraphim_sessions` returns zero hits. ## Acceptance Criteria - [ ] New file `crates/terraphim_sessions/src/connector/mcp.rs` defines `McpConnector { endpoint: McpEndpoint }` where `McpEndpoint = Stdio { command: String, args: Vec<String> } | Sse { url: Url }`. - [ ] `McpConnector` implements `SessionConnector::import(&self) -> Result<Vec<Session>>` by calling `resources/list` then `resources/read` for each resource whose MIME type is `application/x-terraphim-session+json` or `text/x-session-transcript`. - [ ] Config lookup in `ConnectorRegistry::detect_sources` recognises an `mcp:` URL scheme and constructs the connector accordingly. - [ ] `/sessions sources` in the REPL lists any discovered MCP endpoints. - [ ] `/sessions import --source mcp://<url>` triggers the new connector. - [ ] Failures during MCP handshake emit a structured error with endpoint and phase (`connect`, `list`, `read`), not a generic `anyhow` chain. - [ ] Unit test using an in-process MCP mock server (reuse the harness from `terraphim_mcp_server::tests`) imports at least one session. - [ ] `cargo test -p terraphim_sessions --lib connector::mcp` passes. - [ ] `cargo clippy -p terraphim_sessions -- -D warnings` passes. ## Proposed Approach 1. Add `mcp` module alongside `aider.rs`, `cline.rs`, `native.rs`. Register in `connector/mod.rs`. 2. Use the `rmcp` or `mcp-rust-sdk` crate already in the workspace (feature-gated under `mcp-rust-sdk`) for client-side calls; gate the connector behind `feature = "mcp"` to avoid pulling SDK into default builds. 3. Define `SessionResource { id, title, mime_type, updated_at }` so `import` can decide which resources to fetch. 4. Map MCP resource payloads onto the existing `Session` model via `serde` with a light schema-version check. 5. Add integration test that spins up `terraphim_mcp_server` in-process and imports a seeded session. Files affected: - `crates/terraphim_sessions/src/connector/mcp.rs` (new, ~250 LOC) - `crates/terraphim_sessions/src/connector/mod.rs` (~15 LOC registry) - `crates/terraphim_sessions/Cargo.toml` (add `mcp` feature, optional dep) - `crates/terraphim_sessions/tests/mcp_connector_test.rs` (new, ~100 LOC) ## Dependencies None. Can ship in parallel with #3 (Cline connector wiring) and #5 (Tantivy index). Unblocks: third-party tool imports without per-tool code, and extensions to the session-search spec that cite MCP-only IDEs. ## Verification ```bash cargo test -p terraphim_sessions --features mcp --lib connector::mcp cargo test -p terraphim_sessions --features mcp --test mcp_connector_test cargo clippy -p terraphim_sessions --features mcp -- -D warnings ./target/debug/terraphim-agent sessions sources ./target/debug/terraphim-agent sessions import --source "mcp://stdio/path/to/server" ``` ## Scope Single PR, estimated 350-450 LOC including tests and Cargo wiring. Completes Phase 2 Task 2.5.3. Upstream: Implements `docs/specifications/terraphim-agent-session-search-tasks.md` Phase 2 Task 2.5.3 for terraphim/terraphim-ai.
root added the status/approved label 2026-05-11 00:05:27 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent-catalogue
Role-based subagent type tracking issue (architect, developer, etc.) — distinct from persona agents (agent:kimiko etc.)
 agent:kairo
Tasks owned by Kairo
 agent:kimiko
Tasks owned by Kimiko
 agent:shimaguru
Tasks owned by Shimaguru
 priority:critical
Must be done immediately
 priority:high
Should be done this cycle
 priority:low
Nice to have
 priority:medium
Normal priority
 status/approved
Approved for implementation
 status/in-progress
Agent is actively working on this issue
 type:bug
Defect fix
 type:feature
New functionality
 type:research
Investigation or spike
 type:task
General task
 workflow:blocked
Task is blocked by a dependency
 workflow:done
Task is complete
 workflow:in-progress
Task is actively being worked on
 workflow:ready
Task is ready for an agent to pick up
No Label status/approved
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
browser-qa compliance-watchdog documentation-generator drift-detector implementation-swarm kairo kimie05c34be198a20b9 merge-coordinator meta-coordinator product-development quality-coordinator root security-sentinel shimaguru spec-validator upstream-synchronizer
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: terraphim/agent-tasks#13
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?