{
  "markdown": "# insight-blueprint\n\n[![PyPI](https://img.shields.io/pypi/v/insight-blueprint)](https://pypi.org/project/insight-blueprint/)\n[![CI](https://github.com/etoyama/insight-blueprint/actions/workflows/ci.yml/badge.svg)](https://github.com/etoyama/insight-blueprint/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/etoyama)\n\nA Python MCP server for hypothesis-driven data analysis. Manage analysis designs, data catalogs, and review workflows through Claude Code or any MCP-compatible client.\n\n## Installation\n\n### Recommended: Claude Code Plugin\n\n```bash\n# Option 1: From the official marketplace\nclaude plugin install etoyama/insight-blueprint\n\n# Option 2: Via custom marketplace (permanent install)\n/plugin marketplace add etoyama/insight-blueprint\n/plugin install insight-blueprint@insight-blueprint-marketplace\n\n# Option 3: From a local clone (session only)\ngit clone https://github.com/etoyama/insight-blueprint.git\nclaude --plugin-dir ./insight-blueprint\n```\n\nAll options provide 8 analysis skills and auto-configure the MCP server. A WebUI dashboard opens automatically at http://127.0.0.1:3000.\n\n> **Tip:** Option 3 loads the plugin for the current session only. Add a shell alias for convenience:\n> ```bash\n> alias claude-ib='claude --plugin-dir /path/to/insight-blueprint'\n> ```\n\n### Alternative: Direct Execution\n\n```bash\n# Start the server without plugin (zero-install)\nuvx insight-blueprint --project /path/to/my-analysis\n\n# Or install permanently\nuv tool install insight-blueprint\ninsight-blueprint --project /path/to/my-analysis\n```\n\n### Updating\n\nWhen 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):\n\n```bash\n/plugin marketplace update insight-blueprint-marketplace\n/plugin update insight-blueprint@insight-blueprint-marketplace\n```\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes.\n\n### Optional: Python Package\n\nFor data-lineage tracking with `tracked_pipe` in your notebooks/scripts:\n\n```bash\nuv add insight-blueprint\n```\n\nThis is optional but recommended for analysis pipeline transparency. MCP tools work without it.\n\n## Features\n\n### MCP Tools\n\ninsight-blueprint exposes 18 tools via the [Model Context Protocol](https://modelcontextprotocol.io/), allowing AI assistants to manage your analysis workflow:\n\n| Category | Tools |\n|----------|-------|\n| **Analysis Design** | `create_analysis_design`, `update_analysis_design`, `get_analysis_design`, `list_analysis_designs` |\n| **Data Catalog** | `add_catalog_entry`, `update_catalog_entry`, `get_table_schema`, `search_catalog` |\n| **Domain Knowledge** | `get_domain_knowledge`, `extract_domain_knowledge`, `save_extracted_knowledge`, `suggest_knowledge_for_design`, `suggest_cautions` |\n| **Review Workflow** | `transition_design_status`, `save_review_comment`, `save_review_batch`, `get_review_comments` |\n| **Project** | `get_project_context` |\n\n### WebUI Dashboard\n\nA browser-based dashboard (http://127.0.0.1:3000) with two tabs:\n\n- **Designs** -- Browse analysis designs, view details (overview + history), and track status transitions\n- **Catalog** -- Search domain knowledge, browse data sources, and check cautions\n\n### Bundled Skills\n\nThe plugin provides 10 analysis skills that are automatically available after installation:\n\n- `/rq-problematization` -- Generate impactful research questions by problematizing the assumptions in prior research (upstream of framing)\n- `/analysis-framing` -- Explore available data and existing analyses to frame a hypothesis direction\n- `/analysis-design` -- Guided workflow for creating hypothesis documents\n- `/analysis-journal` -- Record reasoning steps during analysis (observations, evidence, decisions, questions)\n- `/analysis-reflection` -- Structured reflection to draw conclusions or branch hypotheses\n- `/analysis-revision` -- Guided revision workflow for addressing review comments\n- `/catalog-register` -- Step-by-step data source registration\n- `/data-lineage` -- Track data transformations and export lineage diagrams (Mermaid)\n- `/batch-analysis` -- Overnight batch execution of queued designs (headless notebooks, self-review, journal recording)\n- `/premortem` -- Pre-flight risk evaluation of queued designs with approval token issuance (gates `/batch-analysis`)\n\nSkills support both English and Japanese trigger phrases.\n\n### Analysis Workflow\n\nSkills chain together to support the full hypothesis-driven analysis lifecycle:\n\n```\n/rq-problematization (problematize assumptions → research questions)  ← optional upstream\n    ↓ (RQ Brief)\n/analysis-framing (explore data, frame direction)\n    ↓\n/analysis-design (create hypothesis)\n    ↓ (interactive)          ↓ (batch)\n/analysis-journal        /batch-analysis (overnight headless)\n    ↓                        ↓\n    ↓\n/analysis-reflection (reflect → conclude or branch)      ← morning review\n    ↓ ↗ back to /analysis-framing (new direction needed)\n    ↕ WebUI review → /analysis-revision (address review comments)\n/catalog-register (register findings as domain knowledge)\n```\n\nEach 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).\n\n## Overnight Operation\n\nBatch analysis runs overnight via a two-step workflow: risk evaluation\nfollowed by headless execution.\n\n### Workflow\n\n```\n/premortem --queued --yes --mode review\n    ↓ (exit 0: token issued)\n    ↓ (exit 2: HIGH detected, human triage needed)\n/batch-analysis --approved-by TOKEN\n    ↓\nMorning review: summary.md + /analysis-reflection per design\n```\n\n### Automation Modes\n\n| Mode | HIGH Risk Handling | Human Interaction |\n|------|-------------------|-------------------|\n| `manual` | Interactive prompt for every design | Required |\n| `review` | Blocks on HIGH (exit 2), auto-approves LOW/MEDIUM | Only when HIGH detected |\n| `auto` | Includes HIGH in approved set with warning | None |\n\nSet the mode in `.insight/config.yaml` under `batch.automation` (default: `review`).\n\n### Phased Rollout of `--approved-by`\n\nThe `--approved-by TOKEN` argument is introduced in two phases:\n\n- **Phase A** (`batch.approved_by_required: false`): Omitting the flag prints a\n  warning and runs in legacy mode. Existing workflows are not broken.\n- **Phase B** (`batch.approved_by_required: true`): Omitting the flag causes\n  exit 1. All batch runs must go through `/premortem` first.\n\nTransition from Phase A to Phase B by setting `approved_by_required: true` in\n`.insight/config.yaml` when your team is ready.\n\n## CLI Options\n\n```bash\ninsight-blueprint --project /path/to/project   # Specify project directory\ninsight-blueprint --no-browser                  # Suppress browser auto-open\ninsight-blueprint --version                     # Show version\ninsight-blueprint                               # Use current directory\n```\n\n## Team Server Mode\n\nMultiple Claude Code instances can share a single insight-blueprint server via MCP SSE (Server-Sent Events).\n\n### Server mode (WebUI + MCP SSE)\n\n```bash\ninsight-blueprint --project /path/to/project --mode server --port 4000\n```\n\nEach Claude Code instance connects by adding to `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"insight-blueprint\": {\n      \"type\": \"sse\",\n      \"url\": \"http://<host>:4000/mcp/sse\"\n    }\n  }\n}\n```\n\n### Headless mode (MCP SSE only, no WebUI)\n\n```bash\ninsight-blueprint --project /path/to/project --mode headless --port 4000\n```\n\n### Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--mode full` | (default) | stdio MCP + WebUI on localhost:3000. Standard single-user mode |\n| `--mode server` | - | HTTP MCP SSE + WebUI on the same port. For team/multi-client use |\n| `--mode headless` | - | HTTP MCP SSE only (no WebUI). Lightweight deployment |\n| `--host` | `0.0.0.0` | Bind address (server/headless mode only) |\n| `--port` | `4000` | Listen port (server/headless mode only) |\n| `--no-browser` | `false` | Suppress browser auto-open in full mode |\n\n> **WARNING: No authentication.** Phase 1 does not include authentication.\n> Run the server on a trusted network only, or bind to localhost with `--host 127.0.0.1`.\n\n## Migration Guide (from v0.3.x)\n\nIf you previously used insight-blueprint without the plugin system, clean up the old skill copies:\n\n```bash\n# Remove old skill copies (now provided by the plugin)\nrm -rf .claude/skills/analysis-design .claude/skills/analysis-framing \\\n       .claude/skills/analysis-journal .claude/skills/analysis-reflection \\\n       .claude/skills/analysis-revision .claude/skills/catalog-register \\\n       .claude/skills/data-lineage\n\n# Remove old rule copies (now integrated into skill definitions)\nrm -rf .claude/rules/analysis-workflow.md .claude/rules/catalog-workflow.md \\\n       .claude/rules/insight-yaml.md .claude/rules/extension-policy.md\n```\n\nThe plugin's skills take precedence, so old copies won't cause errors but should be removed to avoid confusion.\n\n## Development\n\nRequires **Python 3.11+**, **uv**, and **Node.js** (for frontend build).\n\n```bash\ngit clone https://github.com/etoyama/insight-blueprint.git\ncd insight-blueprint\nuv sync --all-extras\n\n# Build frontend assets (required for WebUI)\npoe build-frontend\n\n# Run lint + typecheck + test\npoe all\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, code style, and how to submit pull requests.\n\n### Tech Stack\n\n| Tool | Purpose |\n|------|---------|\n| **uv** | Package management |\n| **ruff** | Linting and formatting |\n| **ty** | Type checking |\n| **pytest** | Testing |\n| **FastMCP** | MCP server framework |\n| **FastAPI** | WebUI backend |\n\n## Support\n\nIf you find this project useful, consider buying me a coffee.\n\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/etoyama)\n\n## License\n\nMIT\n",
  "bytes": 10365,
  "sha": "989862a2fd97059f04db0a4175e31503b7d0569602c78713d1ad9e3131e5568e",
  "repo_slug": "etoyama/insight-blueprint",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_etoyama_insight_blueprint_insight_bluepr_36ec791a/readme"
}