🏗️ MCP Refactoring Plan

Problem: 2,123-line monolithic server.ts with no modularity, no data tiering, no docs/data integration.

📊 Current vs Proposed Structure

Current (Anti-Pattern)

tools/mcp-development-ai/src/
└── server.ts (2,123 lines) ❌ MONOLITH

Proposed (Modular)

tools/mcp-development-ai/src/
├── server.ts                    (~100 lines - entry point only)
├── config/
│   └── constants.ts             (storage paths, limits)
├── types/
│   └── index.ts                 (all interfaces)
├── storage/
│   ├── memory-store.ts          (in-memory state)
│   ├── file-storage.ts          (local JSON files)
│   ├── mongodb-storage.ts       (cloud sync)
│   └── docs-data-integration.ts (READ from docs/data!)
├── agents/
│   ├── agent-types.ts           (agent definitions)
│   ├── agent-router.ts          (auto-assign decisions)
│   └── agent-training.ts        (per-agent learning)
├── memory/
│   ├── tiered-memory.ts         (hot/warm/cold)
│   ├── summarizer.ts            (auto-summarize decisions)
│   └── compressor.ts            (context compression)
├── tools/
│   ├── preflight.ts             (intelligent context)
│   ├── log-decision.ts          (decision logging)
│   ├── find-similar.ts          (semantic search)
│   ├── report-outcome.ts        (feedback loop)
│   └── mine-patterns.ts         (pattern extraction)
├── session/
│   ├── session-detector.ts      (Cursor session detection)
│   └── session-sync.ts          (sync with docs/data)
└── utils/
    ├── token-estimator.ts       (token counting)
    └── text-utils.ts            (truncation, etc.)

🧠 Smart Data Architecture

Tier 1: VITAL (Always Loaded)

Location: docs/data/ (git-tracked, source of truth)

interface VitalData {
  // Session history - CRITICAL for context continuity
  sessions: SessionManifest[];  // From docs/data/sessions-history/
  
  // High-impact decisions (confidence > 0.9, outcome: success)
  criticalDecisions: CompressedDecision[];  // Max 20
  
  // Agent types - defines the learning structure
  agentTypes: AgentTypeConfig;  // From docs/data/agent-types.json
  
  // Core conventions (rules, not examples)
  conventions: ConventionRule[];  // Max 10
}

Tier 2: WORKING (Session-specific)

Location: In-memory + development-memory.json

interface WorkingData {
  // Current session decisions ONLY
  currentSession: {
    number: number;
    decisions: DecisionSummary[];  // Just summaries!
    startedAt: Date;
  };
  
  // Recently accessed decisions (LRU cache)
  recentAccess: DecisionSummary[];  // Max 10
}

Tier 3: ARCHIVAL (On-demand)

Location: MongoDB only (not loaded by default)

interface ArchivalData {
  // Full decision history (all fields)
  allDecisions: DevelopmentDecision[];
  
  // Vector embeddings for semantic search
  embeddings: DecisionEmbedding[];
  
  // Patterns mined over time
  patterns: LearnedPattern[];
}

🔗 docs/data Integration

Current Problem

docs/data/sessions-history/session-9.json  ← EXISTS
development-memory.json                      ← SEPARATE, DUPLICATE

Solution: docs/data as Source of Truth

// NEW: docs-data-integration.ts

export function loadSessionContext(): VitalData {
  const sessionsDir = 'docs/data/sessions-history';
  const agentTypesFile = 'docs/data/agent-types.json';
  
  return {
    sessions: readAllSessionManifests(sessionsDir),
    agentTypes: readAgentTypes(agentTypesFile),
    criticalDecisions: extractCriticalFromSessions(),
  };
}

// development-memory.json becomes WORKING memory only
// Archival stays in MongoDB

🤖 Agent-Specific Training

Current Problem

// All decisions lumped together
decisions: DevelopmentDecision[]

// Agent ID exists but NOT USED for training
decision.agentId = "cursor-angular-agent"  // Just a label!

Solution: Per-Agent Learning

// NEW: agent-training.ts

interface AgentKnowledge {
  agentId: string;
  specialization: string[];  // e.g., ["angular", "signals", "components"]
  
  // Per-agent success patterns
  successfulPatterns: Pattern[];
  
  // Per-agent failure patterns (anti-patterns)
  antiPatterns: Pattern[];
  
  // Confidence calibration per agent
  confidenceScore: number;  // Predicted vs actual success
}

// When routing a task:
function getRelevantContext(task: string): AgentContext {
  const agent = detectBestAgent(task);  // "cursor-angular-agent"
  
  return {
    // Only decisions from THIS agent type
    relevantDecisions: getAgentDecisions(agent.id),
    
    // Agent-specific patterns
    patterns: agent.successfulPatterns,
    
    // Agent-specific warnings
    warnings: agent.antiPatterns,
  };
}

📉 Data Reduction Strategy

Current: 919 lines in development-memory.json

{
  "decisions": [
    {
      "id": "dev_xxx",
      "question": "How to handle SCSS color.adjust() not working?",  // 50 chars
      "chosen": "Revert to darken() syntax",                         // 25 chars
      "reasoning": "...",                                             // 200 chars
      "options": ["...", "...", "..."],                              // 100 chars
      "context": { "files": ["..."], "task": "..." }                 // 100 chars
    }
    // x 38 decisions = ~18,000 chars = ~4,500 tokens
  ]
}

Proposed: Tiered Storage

// development-memory.json (WORKING - 200 lines max)
{
  "currentSession": 9,
  "workingDecisions": [
    { "id": "xxx", "summary": "Fixed SCSS: use darken()", "agentId": "cursor-angular" },
    // Max 10 summaries = ~50 tokens
  ]
}

// docs/data/sessions-history/session-9.json (VITAL - already git-tracked)
{
  "decisions": [
    { "id": "xxx", "summary": "...", "impact": "high" }  // High-impact only
  ]
}

// MongoDB (ARCHIVAL - on-demand)
// Full decisions with all fields
// Vector embeddings
// Pattern history

🚀 Implementation Plan

Phase 1: Modularize server.ts (Day 1)

1. Extract types to types/index.ts
2. Extract storage to storage/ modules
3. Extract tools to tools/ modules
4. Extract agents to agents/ modules
5. Reduce server.ts to entry point only

Phase 2: Implement Data Tiering (Day 2)

1. Create memory/tiered-memory.ts
2. Implement auto-summarization on log
3. Move full decisions to MongoDB only
4. Keep only summaries in local files

Phase 3: Integrate docs/data (Day 3)

1. Create storage/docs-data-integration.ts
2. Read sessions from docs/data/sessions-history/
3. Sync critical decisions to docs/data/
4. Make development-memory.json working-only

Phase 4: Agent-Specific Training (Day 4)

1. Create agents/agent-training.ts
2. Implement per-agent decision filtering
3. Track per-agent success/failure patterns
4. Add confidence calibration per agent

📊 Expected Improvements

🎯 Key Design Decisions

1. docs/data is source of truth - Git-tracked, auditable
2. development-memory.json is working memory - Just current session
3. MongoDB is archival - Full history, on-demand access
4. Summaries, not full decisions - 90% token reduction
5. Per-agent learning - Specialized knowledge per agent type
6. Modular code - Single responsibility, testable

Created: December 12, 2025 | Session 9.3