EX MCP Server

# Consolidation Plan (Augment) Status: Draft — Ready to execute in phases Objectives - Remove duplicate code paths, prevent drift, and simplify navigation - Canonicalize domains: src/ for application code, tools/ for MCP tools, root for entrypoints Principles - Non-destructive first: import shims and deprecation banners before any deletions - Observable safety: tests + smoke checks between each phase - Rollback-friendly: each phase is independently revertible Phase A — Providers canonicalization - Canonical: src/providers - Actions 1) Add deprecation banner to top-level providers/*.py indicating src/providers is canonical 2) Implement re-export shims in providers/__init__.py so `from providers.X import Y` resolves to `src.providers.X` 3) Ensure server.py and tools already import from src.providers (they do); scan tests/scripts for `^from providers\.` and fix to src.providers where feasible 4) Freeze top-level providers/* to read-only (no new features), update docs/providers README to point to src/providers - Validation - Run focused tests: tests/test_openrouter_*.py, tests/test_xai_models.py, tests/test_thinking_routing.py - Manual smoke: tools.listmodels and a short chat via Kimi and GLM Status notes (Phase A) - Picked up: Deprecation banners in top-level providers/* (per migration_checklist_phaseA.md [x]) - Picked up: providers/__init__.py shim re-exports to src/providers/* (per migration_checklist_phaseA.md [x]) - Picked up: providers/README updated (per migration_checklist_phaseA.md [x]) - Pending: Repo-wide grep/replace of legacy imports `from providers.` → `from src.providers.` (unchecked) - Pending: Smoke validations (listmodels; quick GLM/Kimi chat) (unchecked) - Pending: Confirm only src/providers registry is used at runtime via logs (unchecked) - Pending: Plan final deletion window after green CI (unchecked) Status notes (Phase B) - Picked up: Ownership defined (RouterService authoritative; agentic router provides hints) — documented in plan - Picked up: Alias/deprecation direction for routing/task_router.py  documented - Pending: Implemented accept_agentic_hint(TaskType, caps) API in RouterService (needs code validation) - Pending: Logging of final decision and hint application; enable ROUTER_DIAGNOSTICS_ENABLED and capture logs - Pending: Decision table tests for TaskTypes (web, vision, long_context, code) Phase B — Routing unification - Canonical: src/router/service.py for service-level routing; src/core/agentic/task_router.py for agentic heuristics - Actions 1) Move routing/task_router.py into src/core/agentic as task_router_legacy.py or merge into existing IntelligentTaskRouter 2) Add routing/__init__.py shim re-exporting IntelligentTaskRouter from src.core.agentic 3) Grep tests/scripts for `from routing.task_router` and switch to `from src.core.agentic.task_router` - Validation - Run tests covering routing heuristics and thinking config: tests/test_thinking_routing.py, tests/test_model_thinking_config.py - Manual check: RouterService preflight logs models and auto selection paths Phase C — Tools cleanup - Canonical: tools/ directory - Actions 1) Confirm no source modules exist in src/tools/ (currently empty); remove src/tools package after import audit 2) Keep tools/ as the sole source of MCP tool implementations; ensure server lean registry is the single constructor - Validation - Run list_tools and verify expected catalog Status notes (Phase C) - Picked up: src/tools/ confirmed ghost and removed in audit pass (removal_candidates.md notes) - Picked up: tools/ as canonical and lean registry active (server logs reference) - Pending: Repo grep to ensure no imports reference src.tools - Pending: Write docs/tools index links into augment_reports index for discoverability - Pending: Re-run list_tools smoke and capture output in logs - Run list_tools, basic chat/analyze/debug tool calls locally; ensure no import errors Phase D — Documentation and guardrails - Actions 1) Update docs/architecture and docs/augment_reports to reflect canonical choices 2) Add a CONTRIBUTING.md section: “Use src/providers and src/router only; do not add top-level provider files” 3) Add CI lint to fail on new imports of `providers.` or `routing.` outside src/* - Validation - Ensure blocker CI workflow `.github/workflows/no-legacy-imports.yml` is green - Confirm docs and CONTRIBUTING.md merged in main Status notes (Phase D) - Picked up: Blocker CI documented and script present (no_legacy_imports_blocker.md) - Pending: Update docs/architecture and augment_reports to reflect canonical choices - Pending: Add CONTRIBUTING.md guardrails section - Pending: Verify CI job exists and passes in this branch --- Phase E — Missed items and verifications (from audits) - Legacy imports updates still pending (providers.* src.providers.*, routing.* src.router.*) across tests/scripts/docs - Smoke validations pending: listmodels, quick GLM/Kimi chat; capture outputs in docs/augment_reports/audit/logs/ - Router diagnostics: enable ROUTER_DIAGNOSTICS_ENABLED=true and capture route_decision/route_diagnostics logs for web/vision/long_context/code - ThinkDeep reliability: verify non-empty first block with EX_ENSURE_NONEMPTY_FIRST=true and EXAI_WS_EXPERT_MICROSTEP=true; capture one Kimi and one GLM run - Analyze reliability: confirm analysis_partial or non-empty first block; capture logs and outputs - DEFAULT_MODEL stability: avoid 'auto' where upstream tools reject it (see call_errors); prefer glm-4.5-flash unless routing requires auto - Docs consistency: update examples to use src.providers.* and src/router/* imports - Removal window planning: schedule Phase-F shim deletions after one week green CI; prepare PR References considered: - previous_audit/call_errors.md (empty_response patterns; payload guard fix; auto model alias failures) - previous_audit/decision_tree_architecture.md and duplicate_domains_map.md (canonicalization targets and next actions) Detailed task breakdown - Implement shims (A.2/B.2) - providers/__init__.py: `from src.providers import *` and module-level __all__ to mirror src - routing/__init__.py: `from src.core.agentic.task_router import IntelligentTaskRouter, TaskType` - Search-and-replace (A.3/B.3) - Replace `from providers.` → `from src.providers.` in tests/ and scripts/ - Replace `from routing.task_router` → `from src.core.agentic.task_router` - Deprecation banners (A.1) - Add top-of-file comment: “DEPRECATED: Canonical implementation moved to src/providers/...; this file is frozen and will be removed in Phase F” Deletions (final clean-up — Phase F) - After 1–2 weeks of green CI and no legacy imports detected: - Delete providers/* duplicate files (keep package as shim if any external users rely on it) - Delete routing/task_router.py (if merged) and routing package (if unused) - Confirm src/tools/ removed Risk and rollback - Each phase is shim-first; revert by removing shim and changes in a single commit if issues arise - Keep CHANGELOG entries and link to duplicate_domains_map.md for traceability Execution notes - Work on a feature branch off main, open a PR with: rationale, file list, validation logs, and rollback plan - Prefer small PRs per phase - Do not change runtime behavior (models/routes) — this is structural only