Skip to content

README.md

Latest commit

 

History

History
272 lines (195 loc) · 10.2 KB

README.md

File metadata and controls

272 lines (195 loc) · 10.2 KB
Raw

insight-blueprint

PyPI CI License: MIT Python 3.11+ Buy Me A Coffee

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:

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 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

Mode HIGH Risk Handling Human Interaction
manual Interactive prompt for every design Required
review Blocks on HIGH (exit 2), auto-approves LOW/MEDIUM Only when HIGH detected
auto Includes HIGH in approved set with warning None

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

Option Default Description
--mode full (default) stdio MCP + WebUI on localhost:3000. Standard single-user mode
--mode server - HTTP MCP SSE + WebUI on the same port. For team/multi-client use
--mode headless - HTTP MCP SSE only (no WebUI). Lightweight deployment
--host 0.0.0.0 Bind address (server/headless mode only)
--port 4000 Listen port (server/headless mode only)
--no-browser false Suppress browser auto-open in full mode

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

Tool Purpose
uv Package management
ruff Linting and formatting
ty Type checking
pytest Testing
FastMCP MCP server framework
FastAPI WebUI backend

Support

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

Buy Me A Coffee

License

MIT