Research: MCP component analysis and recommendation - Implement lightweight version with Builder API

docs/research/README.md

@@ -0,0 +1,120 @@
+# MCP Component Research - Quick Summary
+
+**Research Date:** October 2025 (Revised after feedback)  
+**Full Report:** [mcp-component-analysis.md](./mcp-component-analysis.md)
+
+## Question
+
+Should Chartifact implement a Model Context Protocol (MCP) component for creating and editing interactive documents?
+
+## Answer
+
+**YES - Implement a lightweight transactional builder with MCP wrapper (1-2 days effort).**
+
+## Revised Analysis
+
+Initial recommendation was "No" based on overestimated complexity (5-7 weeks). After feedback, revised to lightweight approach:
+
+### Key Insights
+
+1. **Time estimate was way off**: 1-2 days for simple builder + MCP wrapper, not 5-7 weeks
+2. **Multi-turn conversations benefit**: Token accumulation across many editing turns makes transactional operations valuable
+3. **LLMs miss schema details**: Structured operations help prevent common mistakes
+4. **Editor completion easier with builder**: Builder provides foundation for editor, not vice versa
+
+## Key Findings
+
+### 1. Multi-Turn Token Accumulation Matters
+- Single document: 741 lines (~5,000 tokens)
+- 20 editing turns: 100,000+ tokens (exhausts context)
+- Transactional operations: Send only changes, not full document each time
+
+### 2. Schema Clarity vs. Practice
+- Schema is clear in theory
+- LLMs can miss details in practice
+- Structured builder prevents violations
+- Sensible defaults help starting point
+
+### 3. Lightweight Implementation
+- **Effort:** 1-2 days, not 5-7 weeks
+- **Code:** 350-600 lines, not 2,500-4,000
+- **Maintenance:** Minimal - maps to schema
+
+### 4. Editor Foundation
+- Builder simplifies editor completion
+- Ready-made operations (add, delete, update)
+- Shared validation logic
+- Easier undo/redo implementation
+
+## Benefits vs. Costs
+
+### Benefits (Revised)
+
+| Benefit | Value | Reason |
+|---------|-------|--------|
+| Token efficiency | High | Multi-turn conversations stay in context |
+| Schema validation | High | Structured operations prevent mistakes |
+| Editor foundation | High | Builder simplifies editor completion |
+| Sensible defaults | High | Start with working document, not blank |
+| MCP tool access | Medium | Standardized protocol for external tools |
+
+### Costs (Revised)
+
+| Cost | Effort | Details |
+|------|--------|---------|
+| Transactional builder | 1 day | Core operations, validation |
+| MCP wrapper | 0.5 day | Thin shim over builder |
+| File integration | 0.5 day | Load/save operations |
+| **Total** | **1-2 days** | Focused development |
+
+**Verdict: Benefits outweigh costs** with lightweight approach.
+
+## Recommendation
+
+### Implement Lightweight Transactional Builder + MCP Wrapper
+
+**Why the change from original "No"?**
+
+1. **Complexity overestimated**: 1-2 days, not 5-7 weeks
+2. **Multi-turn conversations**: Token accumulation is real issue
+3. **LLMs miss schema**: Structured operations help in practice
+4. **Editor needs foundation**: Builder makes editor easier to complete
+
+### Implementation Plan
+
+**Day 1: Transactional Builder**
+- Create immutable document builder class
+- Core operations: create, addGroup, addElement, delete*
+- Type-safe API with validation
+- Sensible defaults included
+
+**Day 1-2: MCP Wrapper**
+- Thin shim exposing builder via MCP protocol
+- Tool definitions with JSON schemas
+- Simple state management
+
+**Day 2: File Integration**
+- Load/save .idoc.json files
+- Basic error handling
+
+**Next: Refactor Editor**
+- Use builder as foundation
+- Simpler implementation
+- Ready-made operations
+
+## Conclusion
+
+**Revised recommendation: YES, implement lightweight version.**
+
+Original analysis overestimated complexity and underestimated benefits:
+- **Complexity**: 1-2 days, not 5-7 weeks
+- **Multi-turn value**: Token efficiency matters
+- **Practical LLM behavior**: Structured operations help
+- **Editor synergy**: Builder provides foundation
+
+**Next step:** Implement simple transactional builder with MCP wrapper.
+
+---
+
+**Status:** Research revised based on feedback, ready for implementation  
+**See:** [Full updated analysis](./mcp-component-analysis.md)