COAIA Visualizer MCP Server

Model Context Protocol (MCP) server for accessing COAIA Visualizer chart services from AI agents.

Overview

This MCP server enables AI agents (like Claude Desktop) to interact with running COAIA Visualizer instances through a secure API. Agents can list, read, create, update, and delete structural tension charts.

Installation

Prerequisites

1. Node.js 18+ installed
2. COAIA Visualizer running (from parent directory)
3. API token from visualizer startup

Setup

cd mcp
npm install
npm run build

Configuration

Environment Variables

Create a .env file in the mcp directory:

# Required: API token (shown when coaia-visualizer starts)
COAIAN_API_TOKEN=your_token_here

# Optional: API URL (defaults to http://localhost:3000)
COAIAV_API_URL=http://localhost:3000

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "coaia-visualizer": {
      "command": "node",
      "args": [
        "/path/to/coaia-visualizer-feat-4/mcp/dist/index.js"
      ],
      "env": {
        "COAIAN_API_TOKEN": "your_token_here",
        "COAIAV_API_URL": "http://localhost:3000"
      }
    }
  }
}

Available Tools

list_charts

List all structural tension charts with optional filtering.

Parameters:

• level (optional): Filter by chart level (0, 1, 2, etc.)
• rootOnly (optional): If true, return only root charts

Example:

{
  "level": 0,
  "rootOnly": true
}

get_chart

Get detailed information about a specific chart.

Parameters:

• chartId (required): The chart ID (e.g., "chart_1")

Example:

{
  "chartId": "chart_1"
}

create_chart

Create a new structural tension chart.

Parameters:

• desiredOutcome (required): What you want to CREATE
• currentReality (required): Honest assessment of current state
• dueDate (optional): ISO date string
• parentChartId (optional): Parent chart ID for sub-charts

Example:

{
  "desiredOutcome": "Build a working API",
  "currentReality": "No API exists yet",
  "dueDate": "2026-01-20"
}

update_chart

Update a chart's desired outcome, current reality, or due date.

Parameters:

• chartId (required): Chart ID to update
• updateDesiredOutcome (optional): New desired outcome text
• addCurrentRealityObservation (optional): Add observation
• updateDueDate (optional): New due date or null

Example:

{
  "chartId": "chart_1",
  "addCurrentRealityObservation": "Completed API authentication"
}

add_action_step

Add a new action step to a chart.

Parameters:

• chartId (required): Chart ID
• description (required): Action description
• dueDate (optional): ISO date string

Example:

{
  "chartId": "chart_1",
  "description": "Write API documentation",
  "dueDate": "2026-01-15"
}

update_action_step

Update an existing action step.

Parameters:

• chartId (required): Chart ID
• actionName (required): Action entity name (e.g., "chart_1_action_1")
• description (required): New description

toggle_action_completion

Toggle completion status of an action.

Parameters:

• chartId (required): Chart ID
• actionName (required): Action entity name

delete_action_step

Delete an action step.

Parameters:

• chartId (required): Chart ID
• actionName (required): Action entity name

delete_chart

Delete a chart and all its sub-charts.

Parameters:

• chartId (required): Chart ID to delete

search_charts

Search charts by text or filters.

Parameters:

• q (optional): Search term
• level (optional): Filter by level
• completed (optional): Filter by completion status
• hasActions (optional): Filter charts with actions

Example:

{
  "q": "API",
  "hasActions": true
}

get_chart_progress

Calculate progress percentage for a chart.

Parameters:

• chartId (required): Chart ID

Usage Examples

Starting the Server

1. Start COAIA Visualizer:

cd /path/to/coaia-visualizer-feat-4
coaia-visualizer --memory-path ./memory.jsonl

2. Note the API token shown in output
3. Configure Claude Desktop with the token
4. Restart Claude Desktop

Agent Interactions

Once configured, you can ask Claude:

• "List all my structural tension charts"
• "Show me chart_1 in detail"
• "Create a new chart for building an API"
• "Add an action step to chart_1"
• "What's the progress on chart_2?"
• "Search for charts related to documentation"

Development

Building

npm run build

Watch Mode

npm run dev

Testing

npm test

Troubleshooting

"Unauthorized" Error

• Verify COAIAN_API_TOKEN matches the token from visualizer startup
• Check that token is properly set in environment/config

"Connection Refused"

• Ensure COAIA Visualizer is running
• Verify COAIAV_API_URL is correct
• Check firewall/network settings

"Chart not found"

• Verify chart ID exists using list_charts
• Check memory file has data

Security

• API token is required for all requests
• Token is auto-generated if not set (dev only)
• Local-only by default (no CORS)
• All operations create backups before modification

License

MIT