# Track state for mcp_architecture_refactor_20260606
# Updated by Tier 2 Tech Lead as tasks complete

[meta]
track_id = "mcp_architecture_refactor_20260606"
name = "MCP Architecture Refactor (Sub-MCP Extraction)"
status = "active"
current_phase = 0
last_updated = "2026-06-06"

[blocked_by]
data_oriented_error_handling_20260606 = "merged"
data_structure_strengthening_20260606 = "merged"

[blocks]
mcp_dsl_20260606 = "planned in spec §12.1; the future DSL track"

[phases]
phase_1 = { status = "pending", checkpointsha = "", name = "Foundation: security module + SubMCP Protocol + controller skeleton" }
phase_2 = { status = "pending", checkpointsha = "", name = "Move old code to mcp_client_legacy.py; mcp_client.py becomes the shim" }
phase_3 = { status = "pending", checkpointsha = "", name = "Extract File I/O sub-MCP" }
phase_4 = { status = "pending", checkpointsha = "", name = "Extract Python sub-MCP" }
phase_5 = { status = "pending", checkpointsha = "", name = "Extract C, C++, Web, Analysis sub-MCPs" }
phase_6 = { status = "pending", checkpointsha = "", name = "Extract External sub-MCP" }
phase_7 = { status = "pending", checkpointsha = "", name = "Update dispatch + Result integration + docs + archive" }

[tasks]
# Phase 1: Foundation
t1_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_client_security.py (8+ tests: _is_allowed positive/negative, _resolve_and_check, configure, Result[Path] return)" }
t1_2 = { status = "pending", commit_sha = "", description = "Green: create src/mcp_client_security.py with _is_allowed, _resolve_and_check, configure (all return Result[Path], use Metadata, NilPath)" }
t1_3 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_client.py (controller skeleton: SubMCP Protocol, MCPController class with register/dispatch/get_tool_schemas; no sub-MCPs yet)" }
t1_4 = { status = "pending", commit_sha = "", description = "Green: add SubMCP Protocol + MCPController class skeleton to src/mcp_client.py (alongside the existing 45 functions; the controller is alongside, not replacing)" }
t1_5 = { status = "pending", commit_sha = "", description = "Verify the 4 existing test files still pass (no regression: mcp_client.py is unchanged at this point)" }
t1_6 = { status = "pending", commit_sha = "", description = "Phase 1 checkpoint commit + git note" }
# Phase 2: Move to legacy
t2_1 = { status = "pending", commit_sha = "", description = "Use git mv to move src/mcp_client.py to src/mcp_client_legacy.py" }
t2_2 = { status = "pending", commit_sha = "", description = "Create a new src/mcp_client.py that re-exports all 45+ old symbols from mcp_client_legacy" }
t2_3 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_client_legacy.py (verify all 45+ old symbols are still importable from src.mcp_client)" }
t2_4 = { status = "pending", commit_sha = "", description = "Run all 4 existing test files; confirm no regressions (they import from src.mcp_client which is now the shim)" }
t2_5 = { status = "pending", commit_sha = "", description = "Run src/app_controller.py:61 usage; confirm mcp_client.py_get_symbol_info is accessible via the shim" }
t2_6 = { status = "pending", commit_sha = "", description = "Phase 2 checkpoint commit + git note" }
# Phase 3: Extract File I/O
t3_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_file_io.py (9+ tests: one per FileIOMCP tool, plus security integration)" }
t3_2 = { status = "pending", commit_sha = "", description = "Green: create src/mcp_file_io.py with FileIOMCP class (read_file, list_directory, search_files, get_file_summary, get_file_slice, set_file_slice, edit_file, get_tree, get_git_diff)" }
t3_3 = { status = "pending", commit_sha = "", description = "Register FileIOMCP in the controller (add 2 lines to src/mcp_client.py: import + register call)" }
t3_4 = { status = "pending", commit_sha = "", description = "Verify: existing tests pass; the dispatch function in mcp_client_legacy.py still works (FileIOMCP is registered alongside, not replacing)" }
t3_5 = { status = "pending", commit_sha = "", description = "Phase 3 checkpoint commit + git note" }
# Phase 4: Extract Python
t4_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_python.py (14+ tests: one per py_* tool)" }
t4_2 = { status = "pending", commit_sha = "", description = "Green: create src/mcp_python.py with PythonMCP class" }
t4_3 = { status = "pending", commit_sha = "", description = "Register PythonMCP in the controller" }
t4_4 = { status = "pending", commit_sha = "", description = "Verify: existing tests pass; especially test_mcp_ts_integration.py for any py_* related integration" }
t4_5 = { status = "pending", commit_sha = "", description = "Phase 4 checkpoint commit + git note" }
# Phase 5: Extract C, C++, Web, Analysis
t5_1 = { status = "pending", commit_sha = "", description = "Red + Green: src/mcp_c.py with CMCP class; register; 5+ tests" }
t5_2 = { status = "pending", commit_sha = "", description = "Red + Green: src/mcp_cpp.py with CppMCP class; register; 5+ tests" }
t5_3 = { status = "pending", commit_sha = "", description = "Red + Green: src/mcp_web.py with WebMCP class; URL validation; register; 4+ tests" }
t5_4 = { status = "pending", commit_sha = "", description = "Red + Green: src/mcp_analysis.py with AnalysisMCP class; register; 4+ tests" }
t5_5 = { status = "pending", commit_sha = "", description = "Phase 5 checkpoint commit + git note" }
# Phase 6: Extract External
t6_1 = { status = "pending", commit_sha = "", description = "Red: tests/test_mcp_external.py (4+ tests: register_server, async_dispatch, get_tool_schemas, unregister_server)" }
t6_2 = { status = "pending", commit_sha = "", description = "Green: create src/mcp_external.py with ExternalMCP class (the existing ExternalMCPManager refactored; class name preserved)" }
t6_3 = { status = "pending", commit_sha = "", description = "Wire the controller to delegate to ExternalMCP AFTER native sub-MCPs miss (in dispatch())" }
t6_4 = { status = "pending", commit_sha = "", description = "Verify: test_mcp_client_beads.py (existing) still passes (the Beads MCP is an external)" }
t6_5 = { status = "pending", commit_sha = "", description = "Phase 6 checkpoint commit + git note" }
# Phase 7: Update dispatch + Result integration + docs + archive
t7_1 = { status = "pending", commit_sha = "", description = "Update mcp_client_legacy.py's dispatch() to use the new controller's dispatch() (delegate to MCPController)" }
t7_2 = { status = "pending", commit_sha = "", description = "Verify the dispatch now returns Result[str, ErrorInfo]; the legacy shim unwraps .data so existing tests see strings" }
t7_3 = { status = "pending", commit_sha = "", description = "Update docs/guide_mcp_client.md (if exists) with the new architecture diagram + per-MCP reference" }
t7_4 = { status = "pending", commit_sha = "", description = "Manual smoke test: launch GUI; trigger one tool from each sub-MCP; verify it works" }
t7_5 = { status = "pending", commit_sha = "", description = "Final state.toml update; mark all phases completed; git mv to archive; update tracks.md" }
t7_6 = { status = "pending", commit_sha = "", description = "Phase 7 checkpoint commit + git note (TRACK COMPLETE)" }

[verification]
# Filled as phases complete
phase_1_foundation_complete = false
phase_2_legacy_shim_complete = false
phase_3_file_io_extracted = false
phase_4_python_extracted = false
phase_5_c_cpp_web_analysis_extracted = false
phase_6_external_extracted = false
phase_7_dispatch_updated_and_archived = false
full_test_suite_passes = false
no_new_optional_introduced = false
existing_test_files_pass_unchanged = false

[line_count_progression]
# Filled as phases complete; original mcp_client.py was 2205 lines
phase_1_start = 2205
phase_2_after_move = 2205 # same code, just in legacy file
phase_3_after_file_io = 2205 - 200 # approx 200 lines for FileIOMCP extracted
phase_4_after_python = 0 # approx 200 more lines extracted
phase_5_after_c_cpp_web_analysis = 0 # approx 400 more lines
phase_6_after_external = 0 # approx 200 more lines
phase_7_final_mcp_client_py = 200 # controller + shim re-exports

[sub_mcp_extraction_status]
file_io = { status = "pending", tools_extracted = 0, of_total = 9 }
python = { status = "pending", tools_extracted = 0, of_total = 14 }
c = { status = "pending", tools_extracted = 0, of_total = 5 }
cpp = { status = "pending", tools_extracted = 0, of_total = 5 }
web = { status = "pending", tools_extracted = 0, of_total = 2 }
analysis = { status = "pending", tools_extracted = 0, of_total = 2 }
external = { status = "pending", class_extracted = false }

[mcp_dsl_followup]
track_id = "mcp_dsl_20260606"
status = "planned_in_mcp_architecture_refactor_20260606"
goal = "Introduce a per-MCP compact dialect for tool calls (APL/K/Cosy-inspired), replacing or augmenting JSON. Estimated 5x token reduction per call."
note = "Per user feedback (2026-06-06): 'kinda want to compress the mcp to just have a single intention based DSL per mcp, kinda like command line but more flexible'. Out of scope for this track; this track lays the architectural groundwork (sub-MCPs are the natural unit to pair with a DSL emitter)."
