insight-blueprint

A Python MCP server for hypothesis-driven data analysis. Manage analysis designs, data catalogs, and review workflows through Claude Code or any MCP-compatible client.

Installation

Recommended: Claude Code Plugin

# Option 1: From the official marketplace
claude plugin install etoyama/insight-blueprint

# Option 2: Via custom marketplace (permanent install)
/plugin marketplace add etoyama/insight-blueprint
/plugin install insight-blueprint@insight-blueprint-marketplace

# Option 3: From a local clone (session only)
git clone https://github.com/etoyama/insight-blueprint.git
claude --plugin-dir ./insight-blueprint

All options provide 8 analysis skills and auto-configure the MCP server. A WebUI dashboard opens automatically at http://127.0.0.1:3000.

Tip: Option 3 loads the plugin for the current session only. Add a shell alias for convenience:

alias claude-ib='claude --plugin-dir /path/to/insight-blueprint'

Alternative: Direct Execution

# Start the server without plugin (zero-install)
uvx insight-blueprint --project /path/to/my-analysis

# Or install permanently
uv tool install insight-blueprint
insight-blueprint --project /path/to/my-analysis

Updating

When a new version is published, run the following from within Claude Code to pull the latest plugin (auto-update is off by default for third-party marketplaces):

/plugin marketplace update insight-blueprint-marketplace
/plugin update insight-blueprint@insight-blueprint-marketplace

See CHANGELOG.md for release notes.

Optional: Python Package

For data-lineage tracking with tracked_pipe in your notebooks/scripts:

uv add insight-blueprint

This is optional but recommended for analysis pipeline transparency. MCP tools work without it.

Features

MCP Tools

insight-blueprint exposes 18 tools via the Model Context Protocol, allowing AI assistants to manage your analysis workflow:

WebUI Dashboard

A browser-based dashboard (http://127.0.0.1:3000) with two tabs:

• Designs -- Browse analysis designs, view details (overview + history), and track status transitions

• Catalog -- Search domain knowledge, browse data sources, and check cautions

Bundled Skills

The plugin provides 10 analysis skills that are automatically available after installation:

• /rq-problematization -- Generate impactful research questions by problematizing the assumptions in prior research (upstream of framing)

• /analysis-framing -- Explore available data and existing analyses to frame a hypothesis direction

• /analysis-design -- Guided workflow for creating hypothesis documents

• /analysis-journal -- Record reasoning steps during analysis (observations, evidence, decisions, questions)

• /analysis-reflection -- Structured reflection to draw conclusions or branch hypotheses

• /analysis-revision -- Guided revision workflow for addressing review comments

• /catalog-register -- Step-by-step data source registration

• /data-lineage -- Track data transformations and export lineage diagrams (Mermaid)

• /batch-analysis -- Overnight batch execution of queued designs (headless notebooks, self-review, journal recording)

• /premortem -- Pre-flight risk evaluation of queued designs with approval token issuance (gates /batch-analysis)

Skills support both English and Japanese trigger phrases.

Analysis Workflow

Skills chain together to support the full hypothesis-driven analysis lifecycle:

/rq-problematization (problematize assumptions → research questions)  ← optional upstream
    ↓ (RQ Brief)
/analysis-framing (explore data, frame direction)
    ↓
/analysis-design (create hypothesis)
    ↓ (interactive)          ↓ (batch)
/analysis-journal        /batch-analysis (overnight headless)
    ↓                        ↓
    ↓
/analysis-reflection (reflect → conclude or branch)      ← morning review
    ↓ ↗ back to /analysis-framing (new direction needed)
    ↕ WebUI review → /analysis-revision (address review comments)
/catalog-register (register findings as domain knowledge)

Each design has an analysis_intent field (exploratory, confirmatory, or mixed) to distinguish whether you're testing a specific hypothesis or exploring data for patterns. The Insight Journal (.insight/designs/{id}_journal.yaml) tracks your reasoning process with 8 event types mapped to the Narrative Scaffolding framework (Huang+ IUI 2026).

Overnight Operation

Batch analysis runs overnight via a two-step workflow: risk evaluation followed by headless execution.

Workflow

/premortem --queued --yes --mode review
    ↓ (exit 0: token issued)
    ↓ (exit 2: HIGH detected, human triage needed)
/batch-analysis --approved-by TOKEN
    ↓
Morning review: summary.md + /analysis-reflection per design

Automation Modes

Set the mode in .insight/config.yaml under batch.automation (default: review).

Phased Rollout of --approved-by

The --approved-by TOKEN argument is introduced in two phases:

• Phase A (batch.approved_by_required: false): Omitting the flag prints a warning and runs in legacy mode. Existing workflows are not broken.

• Phase B (batch.approved_by_required: true): Omitting the flag causes exit 1. All batch runs must go through /premortem first.

Transition from Phase A to Phase B by setting approved_by_required: true in .insight/config.yaml when your team is ready.

CLI Options

insight-blueprint --project /path/to/project   # Specify project directory
insight-blueprint --no-browser                  # Suppress browser auto-open
insight-blueprint --version                     # Show version
insight-blueprint                               # Use current directory

Team Server Mode

Multiple Claude Code instances can share a single insight-blueprint server via MCP SSE (Server-Sent Events).

Server mode (WebUI + MCP SSE)

insight-blueprint --project /path/to/project --mode server --port 4000

Each Claude Code instance connects by adding to .claude/settings.json:

{
  "mcpServers": {
    "insight-blueprint": {
      "type": "sse",
      "url": "http://<host>:4000/mcp/sse"
    }
  }
}

Headless mode (MCP SSE only, no WebUI)

insight-blueprint --project /path/to/project --mode headless --port 4000

Options

WARNING: No authentication. Phase 1 does not include authentication. Run the server on a trusted network only, or bind to localhost with --host 127.0.0.1.

Migration Guide (from v0.3.x)

If you previously used insight-blueprint without the plugin system, clean up the old skill copies:

# Remove old skill copies (now provided by the plugin)
rm -rf .claude/skills/analysis-design .claude/skills/analysis-framing \
       .claude/skills/analysis-journal .claude/skills/analysis-reflection \
       .claude/skills/analysis-revision .claude/skills/catalog-register \
       .claude/skills/data-lineage

# Remove old rule copies (now integrated into skill definitions)
rm -rf .claude/rules/analysis-workflow.md .claude/rules/catalog-workflow.md \
       .claude/rules/insight-yaml.md .claude/rules/extension-policy.md

The plugin's skills take precedence, so old copies won't cause errors but should be removed to avoid confusion.

Development

Requires Python 3.11+, uv, and Node.js (for frontend build).

git clone https://github.com/etoyama/insight-blueprint.git
cd insight-blueprint
uv sync --all-extras

# Build frontend assets (required for WebUI)
poe build-frontend

# Run lint + typecheck + test
poe all

See CONTRIBUTING.md for setup instructions, code style, and how to submit pull requests.

Tech Stack

Support

If you find this project useful, consider buying me a coffee.

License

MIT