chain-insights 0.2.16

package/docs/investigation-workspaces.md

@@ -0,0 +1,151 @@
+# Investigation Workspaces
+
+An investigation workspace is a normal directory that contains Chain Insights
+case state, evidence, reports, graph payloads, imports, templates, and runtime
+schema notes. Agents and humans should be able to inspect it with a normal
+editor.
+
+## Initialize
+
+```bash
+mkdir -p ~/work/chain-insights-investigations
+cd ~/work/chain-insights-investigations
+cia init .
+```
+
+Do not run `cia init` inside an existing workspace unless replacing scaffolded
+files with `--force`. Without `--force`, init refuses to overwrite known
+workspace files before it creates directories or writes any files.
+
+## Layout
+
+```text
+.chain-insights/              Workspace metadata
+.chain-insights/schema/       Runtime graph schema captures
+.chain-insights/runtime/      Workspace-local runtime state and debug logs
+.chain-insights/runtime-skill/ Workspace-specific agent schema notes
+cases/                        Case exports and notes
+imports/                      External investigation inputs
+reports/                      Final or interim analyst reports
+reports/graphs/               Canonical graph JSON for visualization
+reports/tables/               Compact tabular extracts
+templates/                    Reusable case and report templates
+```
+
+No investigation output belongs under `~/.chain-insights`. That directory is
+for local Chain Insights config, wallet, and schema cache state.
+
+## Imports
+
+`imports/` is for user-provided or third-party inputs before they become case
+evidence.
+
+Examples:
+
+- Exchange support exports
+- CSV extracts
+- Screenshots
+- Raw notes
+- Partner reports
+
+Imported files are not automatically evidence. When an import supports a claim,
+summarize it into the case evidence manifest and reference the original path.
+
+## Templates
+
+`templates/` is for reusable workspace-local case, report, prompt, and evidence
+templates. Templates are optional helpers. They are not case state until copied
+into a case, evidence file, dossier, or report.
+
+Fresh workspaces include a `case-brief.md` starter template.
+
+## Cases
+
+Open and manage cases:
+
+```bash
+cia case open "Exchange deposit clustering" \
+  --tags aml,bittensor \
+  --description "Trace high-risk source funds into exchange entities"
+
+cia case list
+cia case activate <case-id>
+cia case suspend <case-id>
+cia case close <case-id>
+```
+
+Use `cia case show <case-id>` to show saved case context, evidence count,
+dossier summaries, and recent session notes.
+
+## Evidence
+
+Append evidence:
+
+```bash
+cia case evidence add <case-id> \
+  --source graph_query_batch \
+  --query-params "network=bittensor" \
+  --content "$(cat compact-result.json)"
+```
+
+Evidence Markdown is a provenance record, not a raw-data dump. Small JSON is
+pretty-printed inline with null fields removed. Large JSON is written under
+`reports/tables/` and the evidence file stores a summary plus a pointer.
+
+Verify evidence integrity:
+
+```bash
+cia case evidence verify <case-id>
+```
+
+Graph-backed tools can write `chain-insights.evidence_pointer.v1` entries that
+point to report files. The evidence file should keep the claim, source tool,
+original query parameters, compact facts, and workspace-local file pointers.
+
+## Dossiers
+
+Maintain an entity dossier:
+
+```bash
+cia case dossier update <case-id> 5... \
+  --type unknown \
+  --finding "Appears in the graph address sample; continue risk screening."
+```
+
+Dossiers are durable analyst notes about addresses or entities. Tools do not
+auto-populate dossiers unless they explicitly call the dossier workflow.
+
+## Sessions
+
+Start and end investigation sessions:
+
+```bash
+cia case session start <case-id>
+cia case session end <case-id> \
+  --findings "Initial topology query returned exchange deposit candidates." \
+  --next-steps "Run focused graph_query_batch probes."
+```
+
+Use sessions to record what changed during a work period and what the next
+agent should do. Session notes complement evidence; they do not replace it.
+
+## Reports And Visualization
+
+Generate an ad hoc visualization from JSON:
+
+```bash
+cia viz --data ./sample-transactions.json
+```
+
+Generate a visualization for a case:
+
+```bash
+cia viz <case-id>
+```
+
+Graph-backed tools store canonical graph JSON under `reports/graphs/`.
+Self-contained HTML graph reports and Markdown summaries live under `reports/`.
+Compact JSON and CSV outputs live under `reports/tables/`.
+
+The local graph report server starts automatically when a graph report URL is
+returned. Graph report URLs use `/graph-reports/<filename>.graph.json`.

package/docs/mcp-proxy.md

@@ -0,0 +1,180 @@
+# MCP Proxy
+
+The Chain Insights stdio proxy lets AI agents consume Chain Insights tools as
+an MCP server. It connects to the configured GraphRAG MCP endpoint and adds
+local wallet, case, evidence, and graph-report behavior.
+
+## Basic Configuration
+
+Use this MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "chain-insights": {
+      "command": "chain-insights-mcp-proxy"
+    }
+  }
+}
+```
+
+The proxy reads the same local Chain Insights config as the CLI.
+
+## Behavior
+
+The proxy:
+
+- Connects to `graphMcpEndpoint`.
+- Uses debug bearer auth, test access key auth, or x402 payment auth according
+  to local config.
+- Caches remote tool schemas per endpoint for 24 hours.
+- Exposes graph tools returned by the endpoint.
+- Adds local `balance`, `help`, and case workflow tools.
+- Starts the local graph report server when graph report URLs are returned.
+- Publishes instructions with required argument rules, workflow guidance, graph
+  report behavior, and schema hints.
+
+## Local Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `balance` | Show the local Base USDC payment wallet balance |
+| `help` | Show Chain Insights tool and workflow guidance |
+| `case_open` | Create a local investigation case |
+| `case_list` | List local investigation cases |
+| `case_resume` | Load case context, evidence count, dossiers, and latest session |
+| `case_add_evidence` | Append a report or note to the evidence manifest |
+| `case_verify_evidence` | Verify saved evidence integrity |
+| `case_update_dossier` | Add a durable finding to an address/entity dossier |
+| `case_start_session` | Start an investigation session |
+| `case_end_session` | End a session with findings and next steps |
+
+Remote graph tools are discovered from the configured GraphRAG MCP endpoint. The
+expected primitive graph tools are `graph_query` and `graph_query_batch`.
+
+## Auth Modes
+
+Local debug mode:
+
+```bash
+chain-insights debug on --token chain-insights-dev-debug --endpoint http://localhost:8012/mcp
+chain-insights mcp tools --refresh
+```
+
+Invited tester access key mode:
+
+```bash
+chain-insights access-key set ci_test_REDACTED --endpoint https://staging-mcp.chain-insights.ai/mcp
+chain-insights access-key status
+```
+
+Paid x402 mode:
+
+```bash
+chain-insights config set graphMcpEndpoint https://staging-mcp.chain-insights.ai/mcp
+chain-insights debug off
+chain-insights config set walletPrivateKey 0xYOUR_EVM_PRIVATE_KEY
+chain-insights wallet balance
+```
+
+If `graphMcpAuthToken` is set, Chain Insights sends both
+`X-MCP-Debug-Token` and `Authorization: Bearer <token>`. If it is empty,
+Chain Insights uses the encrypted wallet private key with x402 payment
+handling.
+
+## Agent Installers
+
+Install skills and MCP registration:
+
+```bash
+chain-insights --claude
+chain-insights --codex
+chain-insights --hermes
+```
+
+The Hermes installer writes Chain Insights skills under the Hermes skills
+directory and registers the stdio MCP proxy in the Hermes config.
+
+After installing, open an initialized investigation workspace in the agent and
+operate over the workspace files.
+
+## Claude Desktop
+
+Claude Desktop is supported for basic MCP calls. It is not the primary
+framework UI.
+
+Configure it:
+
+```bash
+chain-insights setup claude-desktop --dry-run
+chain-insights setup claude-desktop
+```
+
+Validate without opening Claude:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  --cli \
+  --config ~/.config/Claude/claude_desktop_config.json \
+  --server chain-insights \
+  --method tools/list
+```
+
+Claude Desktop does not hot-reload its MCP config. Fully quit and reopen it
+after setup.
+
+Useful MCP prompts:
+
+```text
+Use Chain Insights to show my payment wallet balance.
+```
+
+```text
+Use Chain Insights graph_query on network bittensor with:
+USE live_topology MATCH (n) WHERE n.address IS NOT NULL RETURN n.labels AS labels, n.address AS address LIMIT 10
+```
+
+```text
+Use Chain Insights graph_query_batch on network bittensor with these read-only Cypher queries:
+1. USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1
+2. USE live_topology MATCH (n) WHERE n.address IS NOT NULL RETURN n.labels AS labels, n.address AS address LIMIT 3
+```
+
+```text
+Use Chain Insights to open an investigation case named "Exchange deposit clustering" with tags aml,bittensor.
+```
+
+```text
+Use Chain Insights to save the last graph_query_batch result as evidence in case <case-id>.
+```
+
+## Inspector Validation
+
+Inspect a local Graph MCP endpoint directly:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  --cli http://localhost:8012/mcp \
+  --transport http \
+  --method tools/list \
+  --header "X-MCP-Debug-Token: chain-insights-dev-debug"
+```
+
+Inspect the local Chain Insights proxy:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  --cli chain-insights-mcp-proxy \
+  --method tools/list
+```
+
+## Graph Reports
+
+Graph-backed tools may return raw graph data in
+`_meta.chainInsights.graph.data`. Chain Insights stores that graph data under
+`reports/graphs/*.graph.json` in the active workspace and returns
+`_meta.chainInsights.graph.url` pointing to
+`/graph-reports/<filename>.graph.json`.
+
+The local graph report server binds to localhost. Chain Insights does not
+create duplicated `artifacts/` graph payloads; `reports/graphs/` is canonical.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "chain-insights",
+  "version": "0.2.16",
+  "description": "AML investigation toolkit for blockchain analysis",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "chain-insights": "./bin/cli.js",
+    "cia": "./bin/cli.js",
+    "chain-insights-mcp-proxy": "./bin/mcp-proxy.cjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "docs/*.md",
+    "docs/images"
+  ],
+  "scripts": {
+    "build": "tsdown && cp -r src/viz/templates dist/templates && mkdir -p dist/assets && cp -r src/wallet/mcp-proxy/assets/* dist/assets/",
+    "dev": "tsx src/cli.ts",
+    "release:check": "node scripts/check-release-gate.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.2",
+    "@modelcontextprotocol/ext-apps": "^1.7.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@x402/evm": "^2.12.0",
+    "@x402/fetch": "^2.12.0",
+    "commander": "^14.0.3",
+    "hono": "^4.12.18",
+    "open": "^11.0.0",
+    "viem": "^2.49.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.21.10",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "overrides": {
+    "ws": "8.20.1"
+  }
+}

package/skills/chain-insights-developer-experience/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: chain-insights-developer-experience
+description: Use when changing Chain Insights README, docs, skills, CLI UX, AML tool contracts, or developer-facing workflows. Keeps Chain Insights product-first while preserving accurate GraphRAG MCP and investigation details.
+---
+
+# Chain Insights Developer Experience
+
+Use this skill when improving Chain Insights as a product or developer-facing
+framework.
+
+## Product Frame
+
+Chain Insights is an AML tool framework layered on top of GraphRAG MCP.
+GraphRAG MCP provides generic graph-language access. Chain Insights provides
+investigation workflows, AML recipes, local cases, evidence, dossiers, reports,
+and graph visualizations.
+
+Use "GraphRAG MCP" in product-facing docs. Only use lower-level implementation
+names in debugging or contributor docs when the detail is necessary.
+
+## Current AML Tools
+
+- `address_risk`: screen one address for risk, behavior, neighborhood context,
+  and exchange exposure.
+- `track_funds`: trace victim/source funds through intermediaries to exchange
+  deposit candidates.
+- `scam_topology`: expand known victim incident topology into reviewable scam
+  infrastructure and label candidates.
+
+## GraphRAG MCP Layer
+
+GraphRAG MCP exposes generic tools such as:
+
+- `graph_query`
+- `graph_query_batch`
+
+Chain Insights tools should be implemented as local AML workflows over these
+generic graph primitives unless there is a product reason to add a new
+primitive.
+
+## Topology Language
+
+Use these names consistently:
+
+- `live_topology`: fast, cheaper, recent/hot topology.
+- `archive_topology`: wider historical topology; slower and potentially more
+  costly.
+- `facts`: labels, features, risk scores, assets, and enrichment.
+
+Tell users to discover current network capabilities before assuming data is
+available:
+
+```bash
+cia mcp networks
+cia mcp tools --refresh
+```
+
+## README Rules
+
+README starts from the product experience:
+
+1. What Chain Insights is.
+2. What users can do today.
+3. Fast setup and one working demo.
+4. AML tools.
+5. GraphRAG MCP and topology model.
+6. Links to deeper docs.
+
+Do not put debug-token setup, local bypasses, release gates, full test
+matrices, or client-specific desktop setup in README. Link to focused docs.
+
+## Adding AML Tools
+
+Every new AML tool needs:
+
+- User problem and intended analyst workflow.
+- Required inputs and optional inputs.
+- GraphRAG MCP primitives used.
+- Topology/facts scope.
+- Result contract.
+- Case evidence behavior.
+- Graph report behavior.
+- Tests.
+- Dogfood or UAT path.
+
+## Dogfood from a clean workspace
+
+Before claiming the developer experience is good, run from a clean directory
+outside this repository:
+
+```bash
+mkdir -p /home/aphex5/work/chain-insights-dx-dogfood
+cd /home/aphex5/work/chain-insights-dx-dogfood
+cia --version
+cia init .
+cia mcp networks
+cia mcp tools --refresh
+```
+
+Run at least one small investigation command, inspect generated files, and feed
+the friction back into README, docs, CLI help, or follow-up issues.