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
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:
| Category | Tools |
|---|---|
| Analysis Design | create_analysis_design, update_analysis_design, get_analysis_design, list_analysis_designs |
| Data Catalog | add_catalog_entry, update_catalog_entry, get_table_schema, search_catalog |
| Domain Knowledge | get_domain_knowledge, extract_domain_knowledge, save_extracted_knowledge, suggest_knowledge_for_design, suggest_cautions |
| Review Workflow | transition_design_status, save_review_comment, save_review_batch, get_review_comments |
| Project | get_project_context |
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 8 analysis skills that are automatically available after installation:
/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)
Skills support both English and Japanese trigger phrases.
Analysis Workflow
Skills chain together to support the full hypothesis-driven analysis lifecycle:
/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).