KR Boolean Field Mapping Journey - MCP Bug Analysis

kr-boolean-mapping-journey.md

KR Boolean Field Mapping Journey

This diagram shows the confusing field mapping journey for boolean Key Results and how the MCP issue was resolved.

graph TD
    A[Database Schema] --> B[Repository Layer]
    B --> C[Model Layer]
    C --> D[MCP API Response]

    subgraph "Database Layer"
        A1["`**Database Table: key_results**
        - id: string
        - type: 'boolean' | 'numeric'
        - current_value: number
        - **is_done: boolean** ← The actual field
        - status: string ← Wrong field in mapper`"]
    end

    subgraph "Repository & Mapping"
        B1["`**keyResultRepository.getAllByObjective()**
        Returns raw DB rows with:
        - current_value
        - is_done
        - status`"]

        B2["`**db-mappers.ts (BEFORE FIX)**
        ❌ isDone: dbKR.status === 'completed'
        ✅ current: dbKR.current_value`"]

        B3["`**db-mappers.ts (AFTER FIX)**
        ✅ isDone: dbKR.is_done || false
        ✅ current: dbKR.current_value`"]
    end

    subgraph "Model Layer"
        C1["`**KR Interface**
        - id: string
        - type: 'boolean' | 'numeric'
        - **current?: number**
        - **isDone?: boolean**`"]
    end

    subgraph "MCP API Problem"
        D1["`**MCP Route (BEFORE FIX)**
        Returns raw repository data:
        {
          current_value: '1.00', ← DB field name
          is_done: undefined,     ← Missing mapping
          status: 'some_value'    ← Wrong field
        }`"]

        D2["`**MCP Route (AFTER FIX)**
        Returns properly mapped data:
        {
          current: 1.00,      ← Model field name
          isDone: true,       ← Properly mapped
          type: 'boolean'
        }`"]
    end

    subgraph "The Confusion"
        E1["`**What LLM Saw:**
        current_value: '1.00' ← String, not boolean
        Missing isDone field

        **What LLM Expected:**
        isDone: true ← Boolean completion status
        current: 1.00 ← Numeric value`"]
    end

    A1 --> B1
    B1 --> B2
    B2 --> C1
    C1 --> D1
    D1 --> E1

    B1 --> B3
    B3 --> C1
    C1 --> D2

    classDef problem fill:#ffcccc,stroke:#ff0000
    classDef solution fill:#ccffcc,stroke:#00aa00
    classDef database fill:#cce5ff,stroke:#0066cc
    classDef model fill:#fff2cc,stroke:#d6b656

    class B2,D1,E1 problem
    class B3,D2 solution
    class A1,B1 database
    class C1 model

Loading

The Issue Breakdown

1. Database Reality

• Field name: is_done (boolean)
• Field name: current_value (number)

2. Model Expectation

• Field name: isDone (boolean)
• Field name: current (number)

3. Mapping Problems (Before Fix)

• ❌ Mapper checked wrong field: dbKR.status instead of dbKR.is_done
• ❌ MCP returned raw DB field names: current_value instead of current
• ❌ Missing isDone field in MCP responses

4. What the LLM Saw

{
  "id": "kr-3",
  "type": "boolean",
  "current_value": "1.00",  // ← String DB field, not mapped
  // ← isDone field missing entirely
}

5. What the LLM Expected

{
  "id": "kr-3",
  "type": "boolean",
  "current": 1.00,     // ← Proper numeric field
  "isDone": true       // ← Boolean completion status
}

The Fix

1. Fixed DB Type Definition: Added missing is_done?: boolean field
2. Fixed Mapper Logic: Changed from dbKR.status === 'completed' to dbKR.is_done || false
3. Fixed MCP Responses: Return consistent model field names (current, isDone) instead of raw DB fields