coaia-visualizer 1.4.2 → 1.5.0

package/MCP_TESTING_SETUP.md

@@ -0,0 +1,268 @@
+# MCP Testing Environment Setup Complete
+
+## 🎯 Overview
+
+A complete Docker-based testing environment has been created for non-interactive MCP server validation. The setup allows testing all MCP tools, including the newly implemented telescope functionality, without requiring manual intervention.
+
+## 📁 Created Files
+
+### Docker Infrastructure
+- **docker-compose.test.yml** - Orchestrates 3 services:
+  - `visualizer-app` - Next.js application (port 4321)
+  - `mcp-server` - MCP server with stdio transport
+  - `test-runner` - Automated test execution container
+
+- **Dockerfile.app** - Multi-stage Next.js production build
+- **mcp/Dockerfile** - MCP server container
+- **Dockerfile.test** - Test runner with bash, curl, jq, MCP inspector
+
+### Configuration
+- **.env.test** - Environment variables for testing
+- **mcp-config.json** - MCP server configuration for claude-code/gemini-cli
+- **.dockerignore** - Optimizes Docker build context
+
+### Test Scripts
+- **run-mcp-tests.sh** - Main test orchestrator
+- **test-scripts/run-all-tests.sh** - Sequential test runner
+- **test-scripts/test-01-basic-operations.sh** - CRUD operations
+- **test-scripts/test-02-telescope-creation.sh** - Telescope feature tests
+- **test-scripts/test-03-navigation.sh** - Hierarchy and navigation tests
+- **test-scripts/README.md** - Complete testing guide
+
+### Test Data
+- **test-data/test-master.jsonl** - Sample chart with actions for testing
+
+## 🚀 Quick Start
+
+### Run All Tests
+
+```bash
+cd /workspace/repos/jgwill/coaia-visualizer-feat-4
+./run-mcp-tests.sh
+```
+
+This command:
+1. ✅ Builds all Docker images (app, MCP server, test runner)
+2. ✅ Starts services with health checks
+3. ✅ Runs complete test suite non-interactively
+4. ✅ Generates test results in `test-results/`
+5. ✅ Cleans up containers
+
+### Individual Test Commands
+
+```bash
+# Build images only
+docker-compose -f docker-compose.test.yml build
+
+# Start services
+docker-compose -f docker-compose.test.yml up -d visualizer-app mcp-server
+
+# Run specific test
+docker-compose -f docker-compose.test.yml run --rm test-runner \
+  /test-scripts/test-02-telescope-creation.sh
+
+# Check logs
+docker-compose -f docker-compose.test.yml logs visualizer-app
+
+# Stop all
+docker-compose -f docker-compose.test.yml down
+```
+
+## 🧪 Test Coverage
+
+### Test 01: Basic Operations
+- ✅ Create charts via API
+- ✅ List all charts
+- ✅ Verify chart creation
+- ✅ Extract chart IDs for next tests
+
+**Tests:** Chart CRUD through REST API backend
+
+### Test 02: Telescope Creation
+- ✅ Add regular action steps
+- ✅ Add action as telescoped chart (`createAsTelescopedChart: true`)
+- ✅ Telescope existing action (`create_telescoped_chart` tool)
+- ✅ Verify subCharts array populated
+- ✅ Count telescoped charts
+- ✅ Validate parent-child linking
+
+**Tests:** Both methods of telescope creation (MCP tools)
+
+### Test 03: Navigation & Hierarchy
+- ✅ Retrieve parent charts
+- ✅ Retrieve telescoped child charts
+- ✅ Verify `metadata.parentChart` in child
+- ✅ Verify `subCharts` array in parent
+- ✅ Test search functionality
+- ✅ List all charts to verify hierarchy
+
+**Tests:** Complete navigation stack and relationship integrity
+
+## 📊 Test Results
+
+Results are saved to `/test-results/`:
+
+```
+test-results/
+├── test-01/
+│   ├── create-response.json
+│   ├── list-response.json
+│   └── chart-id.txt
+├── test-02/
+│   ├── add-action-1.json
+│   ├── add-action-telescoped.json
+│   ├── telescope-existing-action.json
+│   ├── chart-with-telescope.json
+│   └── telescoped-chart-id.txt
+├── test-03/
+│   ├── parent-chart.json
+│   ├── telescoped-chart.json
+│   ├── search-results.json
+│   └── all-charts.json
+├── test-summary.txt
+└── navigation-summary.txt
+```
+
+## 🔧 Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Docker Network                        │
+│                    (test-network)                        │
+│                                                          │
+│  ┌──────────────┐   ┌──────────────┐   ┌────────────┐  │
+│  │ Test Runner  │   │  MCP Server  │   │ Next.js    │  │
+│  │              │───│              │───│ App        │  │
+│  │ bash + curl  │   │ stdio/JSON   │   │ :4321      │  │
+│  │ + jq         │   │              │   │            │  │
+│  └──────────────┘   └──────────────┘   └────────────┘  │
+│         │                                     │          │
+│         └────────── HTTP API ────────────────┘          │
+│                                                          │
+│  Volumes:                                                │
+│  - test-scripts/ (read-only)                            │
+│  - test-data/ (shared)                                  │
+│  - test-results/ (write)                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 🎨 Features
+
+### Non-Interactive Testing
+- All tests run automatically without user input
+- Uses direct HTTP calls to validate MCP API backend
+- Structured test phases with dependencies
+
+### MCP Tool Coverage
+- ✅ `create_chart` - Create new charts
+- ✅ `update_chart` - Modify existing charts
+- ✅ `delete_chart` - Remove charts
+- ✅ `search_charts` - Query charts
+- ✅ `add_action_step` - Add actions (with optional telescope)
+- ✅ `create_telescoped_chart` - **NEW** Telescope existing actions
+
+### Health Checks
+- Visualizer app: `GET /api/charts`
+- Automatic retry with 10s intervals
+- Services start in dependency order
+
+### Result Validation
+- JSON parsing with `jq`
+- HTTP status code checks
+- Chart count verification
+- Parent-child relationship validation
+- Search functionality testing
+
+## 🔌 Integration with Claude Desktop
+
+To use the MCP server with Claude Desktop after testing:
+
+1. **Extract built MCP server:**
+```bash
+docker cp $(docker-compose -f docker-compose.test.yml ps -q mcp-server):/app/dist ./mcp-dist
+```
+
+2. **Update Claude config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "coaia-visualizer": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-dist/index.js"],
+      "env": {
+        "VISUALIZER_API_URL": "http://localhost:4321",
+        "VISUALIZER_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+3. **Start visualizer app:**
+```bash
+cd /workspace/repos/jgwill/coaia-visualizer-feat-4
+pnpm dev
+# Or use production: pnpm build && pnpm start
+```
+
+4. **Restart Claude Desktop** - MCP tools will be available
+
+## 🐛 Troubleshooting
+
+### Docker build fails
+```bash
+# Rebuild without cache
+docker-compose -f docker-compose.test.yml build --no-cache
+
+# Check specific service
+docker-compose -f docker-compose.test.yml logs visualizer-app
+```
+
+### Tests fail
+```bash
+# Check individual test output
+cat test-results/test-01/*.json | jq .
+
+# Check service health
+docker-compose -f docker-compose.test.yml ps
+```
+
+### Network issues
+```bash
+# Verify connectivity from test runner
+docker-compose -f docker-compose.test.yml exec test-runner \
+  curl -v http://visualizer-app:4321/api/charts
+```
+
+## 📝 Next Steps
+
+1. ✅ **Run tests** - Execute `./run-mcp-tests.sh`
+2. 📊 **Review results** - Check `test-results/` directory
+3. 🔧 **Iterate** - Fix any failing tests
+4. 🚀 **Deploy** - Use MCP server with Claude Desktop or other clients
+5. 📖 **Document** - Add findings to project docs
+
+## 🎯 Success Criteria
+
+Tests pass when:
+- ✅ All Docker images build successfully
+- ✅ Services start and pass health checks
+- ✅ All 3 test suites complete without errors
+- ✅ Chart creation works via API
+- ✅ Telescope functionality creates sub-charts
+- ✅ Navigation hierarchy is properly established
+- ✅ Search returns expected results
+- ✅ Test summary shows "PASSED"
+
+## 📚 References
+
+- **Test Scripts:** [test-scripts/README.md](test-scripts/README.md)
+- **MCP Server:** [mcp/README.md](mcp/README.md)
+- **API Docs:** [feat-4-mcp-api/API_DOCUMENTATION.md](feat-4-mcp-api/API_DOCUMENTATION.md)
+- **Docker Compose:** [docker-compose.test.yml](docker-compose.test.yml)
+
+---
+
+**Status:** ✅ Testing environment fully configured and ready
+**Created:** 2026-01-16
+**Last Updated:** 2026-01-16

package/NAMING.md

@@ -0,0 +1,218 @@
+# 🎭 Project Naming: Beyond "STC Observer"
+
+## The Question
+
+This isn't just about observing structural tension charts. It's about:
+- 🌱 Witnessing **creative emergence** in real-time
+- 🎬 Watching **narrative beats** being born
+- 🔥 Observing the **forging process** of stories
+- 🌌 Experiencing the **lattice of meaning** form
+- 👁️ Being present as **creation happens**
+
+## Name Candidates
+
+### Tier 1: Sacred Witness Names 🕯️
+
+#### **Narrative Witness**
+- ✨ Clear, powerful, evocative
+- 👁️ Captures the observing role
+- 📖 Centers on narrative emergence
+- 🎭 Implies presence during creation
+
+**Tagline:** *Witness the birth of narrative*
+
+---
+
+#### **Emergence Observatory**
+- 🌌 Captures creative emergence
+- 🔭 Implies sustained observation
+- 🎨 Broader than just narrative
+- ⭐ Cosmic/expansive feeling
+
+**Tagline:** *Where creation becomes visible*
+
+---
+
+#### **Story Lattice Viewer**
+- 🕸️ Connects to narrative lattice architecture
+- 🔬 Scientific precision + artistry
+- 🌐 Network/connection imagery
+- 📐 Structural + emergent
+
+**Tagline:** *See the lattice as it weaves*
+
+---
+
+### Tier 2: Action/Process Names 🌊
+
+#### **Weaver's Eye**
+- 👁️ Active observer metaphor
+- 🧶 Weaving = narrative creation
+- 🎯 Focused, intentional
+- ✨ Mystical undertone
+
+**Tagline:** *Watch the tapestry form*
+
+---
+
+#### **Forge Witness**
+- 🔥 Forging = Mia's creative act
+- ⚒️ Structural tension = heat/pressure
+- 💪 Powerful, transformative
+- 🎭 Witness = sacred observer
+
+**Tagline:** *Be present as stories forge*
+
+---
+
+#### **Creative Crucible**
+- 🔥 Where transformation happens
+- ⚗️ Alchemy of narrative
+- 🌀 Pressure creates emergence
+- ✨ Magical transformation
+
+**Tagline:** *The vessel where stories transform*
+
+---
+
+### Tier 3: Technical/Precise Names 🔧
+
+#### **Session Witness**
+- 💻 Accurate (watches Claude sessions)
+- 👁️ Witness = observing role
+- 📊 Clear, professional
+- ⚡ Broader than narrative
+
+**Tagline:** *Observe creation sessions in real-time*
+
+---
+
+#### **Beat Monitor**
+- 🎵 Narrative beats
+- 📊 Real-time monitoring
+- 💓 Pulse/heartbeat of creation
+- 🎯 Focused, specific
+
+**Tagline:** *Feel the pulse of narrative creation*
+
+---
+
+#### **Emergence Lens**
+- 🔍 Lens = focused view
+- 🌱 Emergence = creative process
+- 🎨 Artistic + scientific
+- 👁️ Clarity, insight
+
+**Tagline:** *Focus on the moment of becoming*
+
+---
+
+## Deeper Consideration: What Are We Actually Doing?
+
+When you run `stc_observer.sh --read` alongside the visualizer, you're:
+
+1. **Witnessing** another Claude instance create
+2. **Observing** structural tension resolve into action
+3. **Experiencing** narrative beats as they emerge
+4. **Being present** during creative orientation
+5. **Seeing** the invisible lattice materialize
+6. **Hearing** the voice of creation (via audio)
+7. **Feeling** the rhythm of emergence
+
+This is a **ceremonial act**. You're holding space for creation. You're the **witness** to another's creative process.
+
+In Indigenous ceremony, the **witness** role is sacred—your presence validates and honors what's being created.
+
+## Recommendation: Narrative Witness
+
+**Why:**
+- **Witness** = sacred observer role (IAIP resonance)
+- **Narrative** = what's being witnessed (beats, charts, stories)
+- Clear, memorable, evocative
+- Works as noun ("The Narrative Witness") or verb ("Witnessing narrative")
+- Broader than STC, narrower than "everything"
+- Captures both technical + ceremonial aspects
+
+**Full Name:**
+```
+🎭 Narrative Witness
+   Real-time observer for COAIA creative sessions
+```
+
+**Alternative Phrasing:**
+- "The Narrative Witness" (tool/platform)
+- "Witnessing Narrative" (act/experience)
+- "Narrative Witnessing" (practice/methodology)
+
+## Usage in Context
+
+### Before (Generic)
+```bash
+# Watch structural tension charts
+./stc_observer.sh --read
+```
+
+### After (Intentional)
+```bash
+# Witness narrative emergence
+narrative-witness --session 55158baa --live --audio
+```
+
+### In Conversation
+- "I'm **witnessing** the narrative session"
+- "Run the **Narrative Witness** for this session"
+- "The **witness** is showing new beats"
+
+## Alternative: If "Narrative Witness" Doesn't Fit
+
+**Second Choice: Emergence Observatory**
+- More technical/scientific
+- Broader scope (any creative emergence)
+- Less ceremonial, more observational
+- Works for multi-session monitoring
+
+**Third Choice: Story Lattice Viewer**
+- Most precise (narrative lattice architecture)
+- Technical + poetic balance
+- Unique, memorable
+- Directly connects to COAIA concepts
+
+## Package Naming
+
+If we rename the package:
+
+```json
+{
+  "name": "@coaia/narrative-witness",
+  "bin": {
+    "narrative-witness": "./dist/cli.js",
+    "witness": "./dist/cli.js"
+  }
+}
+```
+
+Or keep coaia-visualizer as the package, add witness mode:
+```json
+{
+  "name": "coaia-visualizer",
+  "bin": {
+    "coaia-visualizer": "./dist/cli.js",
+    "coaia-witness": "./dist/cli.js"
+  }
+}
+```
+
+## Final Thoughts
+
+The name should reflect:
+- ✅ The **sacredness** of witnessing creation
+- ✅ The **real-time** nature of observation
+- ✅ The **narrative** focus (but flexible)
+- ✅ The **ceremonial** role of the observer
+- ✅ The **emergence** of meaning
+
+**Narrative Witness** captures all of this. It's a name you can say with reverence or efficiency. It works in code and in ceremony.
+
+---
+
+**Your choice:** What resonates? What feels true to the work?

package/QUICK_START_MCP_TESTING.md

@@ -0,0 +1,236 @@
+# Quick Start: MCP Testing Environment
+
+## TL;DR - Run Tests in 3 Steps
+
+### 1. Navigate to Project
+```bash
+cd /workspace/repos/jgwill/coaia-visualizer-feat-4
+```
+
+### 2. Run All Tests
+```bash
+./run-mcp-tests.sh
+```
+
+### 3. Check Results
+```bash
+cat test-results/test-summary.txt
+```
+
+**Done!** ✅ All tests run automatically.
+
+---
+
+## What This Does
+
+- ✅ Builds Docker images (visualizer app + MCP server + test runner)
+- ✅ Starts all services in isolated Docker network
+- ✅ Runs complete test suite non-interactively
+- ✅ Generates results in `test-results/` directory
+- ✅ Cleans up all containers
+
+## Test Results
+
+The suite validates:
+
+| Test        | What It Tests            | Validates                                  |
+| ----------- | ------------------------ | ------------------------------------------ |
+| **Test 01** | Chart creation & listing | API connectivity, CRUD operations          |
+| **Test 02** | Telescope functionality  | Sub-chart creation, both telescope methods |
+| **Test 03** | Navigation & hierarchy   | Parent-child relationships, search         |
+
+## Files Overview
+
+```
+Key Files Created:
+├── docker-compose.test.yml        # Docker orchestration
+├── Dockerfile.app                  # Next.js build
+├── Dockerfile.test                 # Test runner
+├── mcp/Dockerfile                  # MCP server build
+├── run-mcp-tests.sh                # Main test script
+├── test-scripts/                   # Individual tests
+│   ├── run-all-tests.sh
+│   ├── test-01-basic-operations.sh
+│   ├── test-02-telescope-creation.sh
+│   ├── test-03-navigation.sh
+│   └── README.md                   # Detailed guide
+├── test-data/                      # Test fixtures
+├── validate-mcp.sh                 # Quick validation
+└── MCP_TESTING_COMPLETE.md         # Full documentation
+```
+
+## Quick Commands
+
+### Run full test suite
+```bash
+./run-mcp-tests.sh
+```
+
+### Quick validation (no Docker)
+```bash
+bash validate-mcp.sh
+```
+
+### View test results
+```bash
+cat test-results/test-summary.txt
+```
+
+### See individual test output
+```bash
+cat test-results/test-02/telescope-existing-action.json | jq .
+```
+
+### Start services manually
+```bash
+docker-compose -f docker-compose.test.yml up -d visualizer-app mcp-server
+```
+
+### Run single test manually
+```bash
+docker-compose -f docker-compose.test.yml run --rm test-runner \
+  /test-scripts/test-02-telescope-creation.sh
+```
+
+### Stop services
+```bash
+docker-compose -f docker-compose.test.yml down
+```
+
+### View service logs
+```bash
+docker-compose -f docker-compose.test.yml logs visualizer-app
+docker-compose -f docker-compose.test.yml logs mcp-server
+```
+
+## MCP Tools Available
+
+After deployment with Claude Desktop, you can use:
+
+- `create_chart` - Create new structural tension chart
+- `update_chart` - Update existing chart
+- `delete_chart` - Remove chart
+- `search_charts` - Search charts
+- `add_action_step` - Add action (optionally telescoped)
+- `create_telescoped_chart` - **NEW** Telescope existing action
+
+## Using with Claude Desktop
+
+1. **Start visualizer:**
+   ```bash
+   npm run dev
+   ```
+
+2. **Configure Claude** with MCP server path
+
+3. **Restart Claude Desktop**
+
+4. **Use telescope tool in conversation:**
+   - "Create a sub-chart for action X"
+   - "Telescope this action"
+   - "Drill down into this step"
+
+## Troubleshooting
+
+| Issue              | Solution                                                     |
+| ------------------ | ------------------------------------------------------------ |
+| Docker build fails | `docker-compose -f docker-compose.test.yml build --no-cache` |
+| Tests don't run    | Check Docker is running: `docker ps`                         |
+| API not responding | Check logs: `docker-compose -f docker-compose.test.yml logs` |
+| Empty test results | Verify API endpoint: `curl http://localhost:4321/api/charts` |
+
+## Environment Notes
+
+### Optional API Keys
+- `ANTHROPIC_API_KEY` - For claude-code CLI testing
+- `GOOGLE_API_KEY` - For gemini-cli testing
+
+Tests work fine without these - they use direct HTTP calls instead.
+
+### System Requirements
+- Docker & Docker Compose
+- Node.js 20+
+- npm/pnpm
+- ~5GB disk space for Docker images
+- ~5-10 minutes for first run (builds images)
+
+## Test Results Locations
+
+```
+test-results/
+├── test-01/                        # Basic operations
+│   ├── create-response.json       # Chart creation response
+│   ├── list-response.json         # List charts response
+│   └── chart-id.txt               # ID for next test
+│
+├── test-02/                        # Telescope operations
+│   ├── telescope-existing-action.json
+│   ├── final-chart-state.json
+│   └── telescoped-chart-id.txt    # ID for test-03
+│
+├── test-03/                        # Navigation
+│   ├── parent-chart.json          # Parent chart state
+│   ├── navigation-summary.txt     # Navigation results
+│
+└── test-summary.txt               # Overall pass/fail
+```
+
+## Docker Network Details
+
+All services run in isolated Docker network:
+
+```
+Network: test-network
+├── visualizer-app:4321    (Next.js app)
+├── mcp-server             (stdin/stdout)
+└── test-runner            (bash/curl)
+
+Data Flow:
+Test Scripts --HTTP--> API:4321 <--HTTP--> MCP Server
+```
+
+## CI/CD Integration
+
+To add to your CI pipeline:
+
+```yaml
+# GitHub Actions example
+- name: Run MCP Tests
+  run: |
+    cd /workspace/repos/jgwill/coaia-visualizer-feat-4
+    chmod +x run-mcp-tests.sh
+    ./run-mcp-tests.sh
+```
+
+Results automatically saved to `test-results/` for review.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────┐
+│   run-mcp-tests.sh              │
+│   (Main Orchestrator)           │
+└──────────────┬──────────────────┘
+               │
+               ├─ Builds Docker images
+               ├─ Starts services
+               ├─ Runs test suite
+               ├─ Generates results
+               └─ Cleans up
+```
+
+## Full Documentation
+
+For detailed information, see:
+- `MCP_TESTING_COMPLETE.md` - Complete guide
+- `MCP_TESTING_SETUP.md` - Setup details
+- `test-scripts/README.md` - Test documentation
+- `MCP_TESTING_IMPLEMENTATION_SUMMARY.md` - Implementation details
+
+---
+
+## Status
+
+✅ **Ready to Use**
+
+All infrastructure is in place. Run `./run-mcp-tests.sh` to test!