chain-insights 0.58.2 → 0.58.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -8
- package/dist/mcp-proxy.cjs +1 -1
- package/dist/mcp-proxy.mjs +1 -1
- package/dist/mcp-proxy.mjs.map +1 -1
- package/docs/architecture.md +5 -1
- package/docs/contributing.md +70 -0
- package/docs/debugging.md +27 -13
- package/docs/development.md +86 -0
- package/docs/graph-query-compatibility.md +25 -38
- package/docs/graph-tools.md +19 -14
- package/docs/mcp-proxy.md +10 -7
- package/docs/stability.md +8 -2
- package/package.json +2 -3
- package/docs/images/topup-page.png +0 -0
package/docs/architecture.md
CHANGED
|
@@ -63,6 +63,7 @@ Supported config keys:
|
|
|
63
63
|
| `graphMcpAuthToken` | Chain Insights Graph bearer credential for test access keys or local debug UAT |
|
|
64
64
|
| `graphMcpMode` | Endpoint access mode: `paid` (default) or `debug` |
|
|
65
65
|
| `walletAddress` | Optional wallet metadata |
|
|
66
|
+
| `serverPort` | Reserved. Default `4321`. No current command reads it |
|
|
66
67
|
| `dataDir` | Local Chain Insights data directory |
|
|
67
68
|
| `version` | Config schema version |
|
|
68
69
|
|
|
@@ -77,9 +78,12 @@ Default local data directory:
|
|
|
77
78
|
~/.chain-insights/
|
|
78
79
|
config.json
|
|
79
80
|
wallet.json
|
|
80
|
-
mcp-schema
|
|
81
|
+
mcp-schema.json
|
|
81
82
|
cache/
|
|
82
83
|
schema-<network>-<endpoint hash>.json
|
|
84
|
+
runtime/
|
|
85
|
+
logs/
|
|
86
|
+
mcp-proxy.jsonl
|
|
83
87
|
```
|
|
84
88
|
|
|
85
89
|
## Security Model
|
package/docs/contributing.md
CHANGED
|
@@ -53,6 +53,76 @@ npm run release:check
|
|
|
53
53
|
git diff --check
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
+
## Repository rules
|
|
57
|
+
### Repository Invariants
|
|
58
|
+
|
|
59
|
+
- `AGENTS.md` and `CLAUDE.md` are twin files kept byte-identical. Edit both
|
|
60
|
+
together, or neither.
|
|
61
|
+
- Every PR that changes tracked files must bump `package.json`,
|
|
62
|
+
`package-lock.json`, and `CHANGELOG.md`. Enforced by
|
|
63
|
+
`npm run release:check` (`scripts/check-release-gate.mjs`) in
|
|
64
|
+
`verify.yml` on pull requests.
|
|
65
|
+
- This is a **public** repo. No private repository names, local workspace
|
|
66
|
+
paths, internal planning catalogs, private deployment details, or
|
|
67
|
+
org-only workflow names in tracked files. Use the name
|
|
68
|
+
"Chain Insights Graph" for the graph layer.
|
|
69
|
+
- Public workflow network support is one network: robinhood. The wallet
|
|
70
|
+
pays on Base mainnet as the payment chain only — not a graph-support
|
|
71
|
+
claim.
|
|
72
|
+
- Node 22 or newer is required (`package.json` engines). CI installs with
|
|
73
|
+
`npm ci --ignore-scripts`.
|
|
74
|
+
|
|
75
|
+
### Data And Findings Invariants
|
|
76
|
+
|
|
77
|
+
- Address labels are served by the Chain Insights Graph backend, never
|
|
78
|
+
written by this CLI.
|
|
79
|
+
|
|
80
|
+
### Development Workflow Rules
|
|
81
|
+
|
|
82
|
+
- `npm run build` is not plain compilation. It also copies wallet MCP-proxy
|
|
83
|
+
assets to `dist/assets`. Skipping it stales the packaged assets. See the
|
|
84
|
+
`dist/` trap in [development.md](development.md).
|
|
85
|
+
- `package.json` `files[]` ships `bin`, `dist`, `skills` and `docs/*.md`.
|
|
86
|
+
Adding a skill or doc changes the published tarball.
|
|
87
|
+
`verify.yml` runs `npm pack` and lists contents.
|
|
88
|
+
- npm overrides pin `ws` to 8.21.0 (`package.json`).
|
|
89
|
+
|
|
90
|
+
### CI Gotchas
|
|
91
|
+
|
|
92
|
+
- `verify.yml` runs on every pull request and every push to `main`, on the
|
|
93
|
+
self-hosted `chainswarm-runner` runners. Its three tiers are the files
|
|
94
|
+
under `ci/` (`t1.sh`, `lint.sh`, `build.sh`), so `bash ci/t1.sh` runs the
|
|
95
|
+
same gate locally.
|
|
96
|
+
- Repo CI has a release gate blocking non-release PRs and a secret scan
|
|
97
|
+
flagging `0x{64}` hex. Avoid committing 64-hex strings.
|
|
98
|
+
- UATs expecting unprefixed tool names (`address_risk`, `trace_funds`, …)
|
|
99
|
+
are stale. Those names are deliberately hidden, and
|
|
100
|
+
`assertPublicMcpToolName()` throws with a suggested `aml_*` / `meta_*`
|
|
101
|
+
replacement.
|
|
102
|
+
- Backend big-query memory limits can surface as generic timeout-like
|
|
103
|
+
errors on archive queries. Do not diagnose these as proxy bugs.
|
|
104
|
+
|
|
105
|
+
### Method Ownership (Reference, Do Not Restate)
|
|
106
|
+
|
|
107
|
+
- Inspector / ACP surface audits (tools/list, prompts/list, prefixed-name
|
|
108
|
+
sync): internal maintainer tooling, not part of this package.
|
|
109
|
+
- ACP release method: internal maintainer tooling.
|
|
110
|
+
- Real local UAT against the GraphRAG MCP: internal maintainer tooling.
|
|
111
|
+
- npm release testing: internal maintainer tooling.
|
|
112
|
+
- Graph serving tiers and sync detail: internal system knowledge, not this
|
|
113
|
+
repo.
|
|
114
|
+
|
|
115
|
+
### Documentation Rules
|
|
116
|
+
|
|
117
|
+
- Keep docs product-first and user-workflow-first: install → configure graph
|
|
118
|
+
access → run AML tools.
|
|
119
|
+
- Localhost endpoints are fine in debugging docs. Private paths are not.
|
|
120
|
+
- The shipped product skill under `skills/` is `chain-insights-cypher`.
|
|
121
|
+
It is a separate product surface
|
|
122
|
+
packaged into the npm tarball and enforced by
|
|
123
|
+
`tests/skills-contract.test.ts`. A capability no skill mentions is
|
|
124
|
+
invisible to agents — keep the skill in step with any change.
|
|
125
|
+
|
|
56
126
|
## Release Discipline
|
|
57
127
|
|
|
58
128
|
Every PR to `main` must:
|
package/docs/debugging.md
CHANGED
|
@@ -25,30 +25,28 @@ Start your local Chain Insights Graph development endpoint with debug bearer
|
|
|
25
25
|
auth enabled. The exact startup command depends on your Chain Insights Graph
|
|
26
26
|
checkout or deployment.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
export CHAIN_INSIGHTS_GRAPH_DEBUG_TOKEN=chain-insights-dev-debug
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
Point Chain Insights at the local endpoint:
|
|
28
|
+
Point Chain Insights at the local endpoint. The debug token and the endpoint
|
|
29
|
+
are command arguments; the CLI reads no environment variable for them:
|
|
34
30
|
|
|
35
31
|
```bash
|
|
36
32
|
node bin/cli.js debug on \
|
|
37
|
-
--token
|
|
38
|
-
--endpoint
|
|
33
|
+
--token chain-insights-dev-debug \
|
|
34
|
+
--endpoint http://localhost:8012/mcp
|
|
39
35
|
node bin/cli.js mcp tools --refresh
|
|
40
36
|
```
|
|
41
37
|
|
|
38
|
+
`cia debug off` returns to the paid production endpoint.
|
|
39
|
+
|
|
42
40
|
## Inspector
|
|
43
41
|
|
|
44
42
|
Inspect the Chain Insights Graph endpoint directly:
|
|
45
43
|
|
|
46
44
|
```bash
|
|
47
45
|
npx @modelcontextprotocol/inspector \
|
|
48
|
-
--cli
|
|
46
|
+
--cli http://localhost:8012/mcp \
|
|
49
47
|
--transport http \
|
|
50
48
|
--method tools/list \
|
|
51
|
-
--header "X-MCP-Debug-Token:
|
|
49
|
+
--header "X-MCP-Debug-Token: chain-insights-dev-debug"
|
|
52
50
|
```
|
|
53
51
|
|
|
54
52
|
Inspect the Chain Insights proxy:
|
|
@@ -61,9 +59,25 @@ npx @modelcontextprotocol/inspector \
|
|
|
61
59
|
|
|
62
60
|
## Environment Variables
|
|
63
61
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
|
62
|
+
Every variable the CLI and the proxy read. None is required.
|
|
63
|
+
|
|
64
|
+
| Variable | Purpose |
|
|
65
|
+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
66
|
+
| `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` | Chain Insights Graph endpoint override. Wins over the saved `graphMcpEndpoint`. `GRAPH_MCP_ENDPOINT` is the legacy alias. |
|
|
67
|
+
| `BASE_RPC_URL` | Base RPC override for the wallet balance and the local top-up page. |
|
|
68
|
+
| `CHAIN_INSIGHTS_MCP_LOG` | `0` turns the proxy's runtime log off. On by default. |
|
|
69
|
+
| `CHAIN_INSIGHTS_MCP_LOG_PATH` | Where the proxy writes its runtime log. Default `~/.chain-insights/runtime/logs/mcp-proxy.jsonl` (under the configured `dataDir`). |
|
|
70
|
+
| `CIA_ACTION_LOG` | Optional path to an append-only JSONL audit log of every MCP tool invocation (tool name, arguments, outcome, duration, and any `warnings`/`search_limits` surfaced by the result). Unset by default — no file is written. Intended for unattended runs where an operator or a later reviewing agent needs to see what ran and why a result looked the way it did. Never causes a tool call to fail: a write error (including an unwritable path) is swallowed silently. |
|
|
71
|
+
| `CHAIN_INSIGHTS_SKIP_UPDATE_CHECK` | `1` skips the update prompt `cia` shows in a terminal when npm has a newer release. |
|
|
72
|
+
| `CHAIN_INSIGHTS_NPM_REGISTRY_URL` | Registry the update check asks. Default npmjs. |
|
|
73
|
+
| `CHAIN_INSIGHTS_MAX_AUTO_APPROVAL_USDC` | Ceiling of the one-time USDC approval `cia wallet ready` grants. |
|
|
74
|
+
| `CHAIN_INSIGHTS_PAYMENT_ASSET_PREFERENCE` | Comma-separated symbols or addresses (`CHOICE,USDG,USDC`) that order the payment assets a server offers. Empty keeps the server's order. |
|
|
75
|
+
| `CHAIN_INSIGHTS_MCP_PROXY_MODE` | Proxy mode. The default, and the only public mode, is stateless. |
|
|
76
|
+
| `CHAIN_INSIGHTS_WORKSPACE` | Workspace root for the non-public workspace commands. |
|
|
77
|
+
| `CHAIN_INSIGHTS_SKILL_REFRESH` | `0` stops the proxy from bringing the installed skill copies up to its own release at start. |
|
|
78
|
+
|
|
79
|
+
The proxy's runtime log holds `tool.start`, `tool.end`, `topology.start`,
|
|
80
|
+
`topology.end` and `cypher.throw` events as JSON lines.
|
|
67
81
|
|
|
68
82
|
## Smoke Checks
|
|
69
83
|
|
package/docs/development.md
CHANGED
|
@@ -73,8 +73,94 @@ npm install -g .
|
|
|
73
73
|
cia --version
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
+
## Contracts the code keeps
|
|
77
|
+
The contracts Chain Insights exposes and consumes. Every statement here
|
|
78
|
+
names the source file it was verified against.
|
|
79
|
+
|
|
80
|
+
### Public MCP Tool Surface
|
|
81
|
+
|
|
82
|
+
- The canonical public tool surface is the prefixed set `graph_*` /
|
|
83
|
+
`meta_*` / `wallet_*`.
|
|
84
|
+
- `visibleRemoteTools()` in `src/mcp/tool-visibility.ts` hides unprefixed
|
|
85
|
+
backend names (`address_risk`, `trace_victim_funds`, `trace_suspect_funds`,
|
|
86
|
+
`trace_deposit_sources`, `trace_funds`, `track_funds`,
|
|
87
|
+
`network_capabilities`, `usage_status`, `balance`, `topup`, `help`,
|
|
88
|
+
`address_connection_risk` and the retired exchange-flows tool) via
|
|
89
|
+
`HIDDEN_REMOTE_TOOL_NAMES`. They never surface publicly. So does
|
|
90
|
+
`aml_address_risk`, hidden until its verdict is fixed.
|
|
91
|
+
- Local tools live in `src/mcp/proxy.ts` (`LOCAL_TOOL_NAMES`):
|
|
92
|
+
`meta_network_capabilities`, `meta_schema`, `meta_rules`, `meta_help`,
|
|
93
|
+
`meta_usage_status`, `meta_subscription_status`, `wallet_balance`,
|
|
94
|
+
`wallet_topup`, and `graph_expand`, which only the view calls
|
|
95
|
+
(`APP_ONLY_LOCAL_TOOL_NAMES`).
|
|
96
|
+
- `meta_schema` (`src/mcp/graph-schema.ts`) builds the live graph schema of one
|
|
97
|
+
network from the catalog statements of the graph endpoint (`CALL db.labels()`,
|
|
98
|
+
`CALL db.relationshipTypes()`, `CALL db.propertyKeys()`, `SHOW INDEXES`), a
|
|
99
|
+
sample of the main kinds and the published capabilities. It returns
|
|
100
|
+
`chain-insights.graph-schema.v1`, and keeps it on disk for 24 hours
|
|
101
|
+
(`src/mcp/graph-schema-cache.ts`).
|
|
102
|
+
- `meta_network_capabilities` repeats GraphRAG's advertised networks
|
|
103
|
+
(`mirrorGraphNetworkCapabilities` in `src/mcp/capabilities.ts`). CIA
|
|
104
|
+
preserves the tool status advertised for each network. It does not add
|
|
105
|
+
tools that the network did not advertise. It also repeats the blocks a
|
|
106
|
+
network publishes about its layers exactly as sent: `layers`,
|
|
107
|
+
`chain_admission`, `topology_admission` and `facts_admission`. A block the
|
|
108
|
+
server did not send stays absent, never empty. The limits of a layer are read
|
|
109
|
+
from these blocks, never written into a skill.
|
|
110
|
+
|
|
111
|
+
#### Tool Argument Contracts
|
|
112
|
+
|
|
113
|
+
- `PUBLIC_MCP_TOOL_REQUIRED_ARGS` / `PUBLIC_MCP_TOOL_ALLOWED_ARGS` in
|
|
114
|
+
`src/mcp/tool-visibility.ts` define the public arg contract. Examples:
|
|
115
|
+
`graph_query` requires query + network; `graph_query_batch` alone allows
|
|
116
|
+
`per_query_timeout_seconds`; both allow `time_scope`.
|
|
117
|
+
- An argument absent from the allowlist is silently stripped by
|
|
118
|
+
`normalizeRemoteToolArguments`. Every new tunable arg must be added here
|
|
119
|
+
and to the numeric-argument set in `src/mcp/call-args.ts` the moment it
|
|
120
|
+
appears on a tool schema.
|
|
121
|
+
|
|
122
|
+
### Endpoint Configuration
|
|
123
|
+
|
|
124
|
+
Precedence for the Chain Insights Graph endpoint:
|
|
125
|
+
|
|
126
|
+
1. `CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT` environment variable.
|
|
127
|
+
2. Legacy `GRAPH_MCP_ENDPOINT` environment variable.
|
|
128
|
+
3. Saved `graphMcpEndpoint` config value.
|
|
129
|
+
4. Default `https://mcp.chain-insights.ai/`.
|
|
130
|
+
|
|
131
|
+
Validation (`validateMcpEndpoint` in `src/config/mcp-endpoint.ts`):
|
|
132
|
+
|
|
133
|
+
- `http://` only for loopback or Kubernetes `*.svc.cluster.local` service DNS.
|
|
134
|
+
- Other remote hosts must use `https://`.
|
|
135
|
+
- No credentials, query string, or fragment in the URL.
|
|
136
|
+
|
|
137
|
+
The MCP proxy uses stateless operation by default. It returns tool results to
|
|
138
|
+
the caller and does not create local investigation files.
|
|
139
|
+
|
|
140
|
+
### Shared-Graph Model
|
|
141
|
+
|
|
142
|
+
The public surface exposes **one network** (`robinhood`, see Public MCP
|
|
143
|
+
Tool Surface). Address space details are a chain property, not a separate
|
|
144
|
+
query network.
|
|
145
|
+
|
|
146
|
+
Consequences:
|
|
147
|
+
|
|
148
|
+
- The `network` argument to `graph_query` selects the graph, not the address
|
|
149
|
+
subset. `network` is also a property of every node and relationship on
|
|
150
|
+
`USE topology`, `USE facts` and `USE chain`. Its value is the query's
|
|
151
|
+
`network`, it is computed and never stored, and only a `:Chain` node (the far
|
|
152
|
+
side of a bridge) stores its own, which names the remote chain. A filter on
|
|
153
|
+
`network` narrows nothing. Anchor a query on an address instead.
|
|
154
|
+
- `USE facts` carries `network` on its rows and endpoints too, with no view
|
|
155
|
+
column behind it. Facts serves `Address` only as a `TRANSFER` endpoint, so a
|
|
156
|
+
single-node `MATCH (a:Address)` is refused. Facts serves no kind label.
|
|
157
|
+
|
|
158
|
+
Verify against the live stack before restating it. Query-side detail:
|
|
159
|
+
[graph-query-compatibility.md](graph-query-compatibility.md).
|
|
160
|
+
|
|
76
161
|
## More Developer Docs
|
|
77
162
|
|
|
78
163
|
- Contributor workflow: `docs/contributing.md`
|
|
79
164
|
- Debugging and UAT: `docs/debugging.md`
|
|
80
165
|
- Graph tool contracts: `docs/graph-tools.md`
|
|
166
|
+
- Architecture index: `docs/architecture/ARCHITECTURE.md`
|
|
@@ -309,40 +309,26 @@ The translator compiles a defined grammar to StarRocks SQL. All literals are
|
|
|
309
309
|
bound as parameters (no SQL injection surface). Anything outside the grammar is
|
|
310
310
|
rejected with a typed contract error before execution.
|
|
311
311
|
|
|
312
|
-
###
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
|
319
|
-
|
|
|
320
|
-
|
|
|
321
|
-
|
|
|
322
|
-
|
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
| `
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
`tx_id` point lookup, or an address filter (window auto-applied) touches
|
|
333
|
-
every partition and is refused before any SQL runs. The refusal names the
|
|
334
|
-
remedy: _add a bare `block_date` bound, or query by `tx_id`, or filter by
|
|
335
|
-
address (a recency window is auto-applied)_.
|
|
336
|
-
|
|
337
|
-
| Rejected shape | Contract error |
|
|
338
|
-
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
339
|
-
| Predicate-less global aggregate | `count(i)` with no partition-bounding predicate → _StarRocks-backed aggregate graph queries require a partition-bounding predicate: add a bare `block_date` bound, or query by `tx_id`, or filter by address (a recency window is auto-applied)_ |
|
|
340
|
-
| No `LIMIT` and no partition-bounding predicate | → _StarRocks-backed graph queries require an explicit LIMIT or partition-bounding predicate: add a bare `block_date` bound, or query by `tx_id`, or filter by address (a recency window is auto-applied)_ |
|
|
341
|
-
| `TRANSFER` row-select or aggregate with no partition-bounding predicate, even with `LIMIT` | `facts_transfers_view` is a full transfer-history table — a bare `LIMIT` does not bound the scan → _StarRocks-backed TRANSFER graph queries require a partition-bounding predicate: add a bare `block_date` bound, or query by `tx_id`, or filter by address (a recency window is auto-applied)_ |
|
|
342
|
-
| `block_height` / `block_timestamp` range only | `t.block_height >= ?` bounds the sort key, not the day partitions → rejected with the remedy error |
|
|
343
|
-
| Wrapped `block_date` | `DATE(t.block_date) >= ?` wraps the partition column → rejected with the remedy error |
|
|
344
|
-
| `block_date` bound inside an `OR` arm | `t.block_height >= 0 OR t.block_date >= ?` — the optimizer cannot prune the unbounded arm → rejected with the remedy error |
|
|
345
|
-
| `LIMIT` above the ceiling | `LIMIT 5000` → _StarRocks-backed graph query LIMIT exceeds maximum 1000_ |
|
|
312
|
+
### A facts read names an address pair with one day
|
|
313
|
+
|
|
314
|
+
`USE facts` looks up rows you already know. The rule is stated once, in the
|
|
315
|
+
[`chain-insights-cypher` skill](../skills/chain-insights-cypher/SKILL.md#facts-an-address-pair-with-one-day),
|
|
316
|
+
and the server admits exactly that shape:
|
|
317
|
+
|
|
318
|
+
| Construct | Notes |
|
|
319
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
320
|
+
| `MATCH` on a mapped node / single relationship | `(from:Address {address:"…"})-[t:TRANSFER]->(to:Address {address:"…"})`. `SWAP`, `LIQUIDITY_ADD`, `LIQUIDITY_REMOVE` and `BRIDGE_CROSSING` are single-event rows on the same pattern. Never serves `FLOWS_TO`, `OPERATED_BY`, `LINKED`, `SWAPPED`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY` or `BRIDGED`. |
|
|
321
|
+
| The pair | Both addresses, from then to, each as `{address: "…"}`. One address alone is refused (`facts_no_anchor`). `IN` is refused: one read per pair, several in one `graph_query_batch`. |
|
|
322
|
+
| The day | `t.block_date = "YYYY-MM-DD"`. A day alone, a window of days, a block range and a bare `LIMIT` are not enough. For more days, send one read per day. |
|
|
323
|
+
| A time window inside the day | `t.block_timestamp >= 1783738500000 AND t.block_timestamp < 1783738560000` beside the day equality narrows the day to a window. `block_timestamp` is epoch milliseconds. On its own it bounds nothing. |
|
|
324
|
+
| `tx_id` equality | `t.tx_id = "…"` reads the rows of one transaction. `IN` is refused: one equality per transaction, several in one `graph_query_batch`. The chain's own record of a transaction (status, block, day) is a `USE chain` read. |
|
|
325
|
+
| `kind` filter | `t.kind = "internal"` beside the pair and the day narrows the read. It never replaces them. |
|
|
326
|
+
| Property projections with aliases | `RETURN a.address AS address, t.amount_usd AS amount_usd` |
|
|
327
|
+
| Aggregates | `count()` and `sum()` only, over the whole page. No grouping key, no `min()`, `max()` or `avg()` (`unsupported facts query shape`). |
|
|
328
|
+
| `LIMIT` | Optional. A reply holds at most 200 rows. No `ORDER BY`: rows come in the server's own order, sort the page yourself. |
|
|
329
|
+
|
|
330
|
+
A refusal names the shape it wants. Read its `fix` and rewrite the query from
|
|
331
|
+
its `example` once.
|
|
346
332
|
|
|
347
333
|
### `TRANSFER` rows and `kind`
|
|
348
334
|
|
|
@@ -376,7 +362,9 @@ StarRocks. Use the topology graph, or restructure:
|
|
|
376
362
|
| Construct | Instead |
|
|
377
363
|
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
378
364
|
| `FLOWS_TO` / `OPERATED_BY` topology edges | The topology graph — facts never serves either |
|
|
379
|
-
|
|
|
365
|
+
| A hop: two relationships in one pattern | The topology graph — a facts read has one relationship |
|
|
366
|
+
| `ORDER BY` | Sort the page yourself |
|
|
367
|
+
| One address with no counterparty, a day range, a block range, a bare `LIMIT` | Name the pair and one day; pick the pairs on the topology graph first |
|
|
380
368
|
| `SWAPPED`, `ADDED_LIQUIDITY`, `REMOVED_LIQUIDITY`, `BRIDGED`, the `:Pool` label | The topology graph. Facts serves the single events as `SWAP`, `LIQUIDITY_ADD`, `LIQUIDITY_REMOVE` and `BRIDGE_CROSSING` |
|
|
381
369
|
| Quantified paths and shortest selectors | The topology graph, or a single fixed-hop `LINKED` pattern |
|
|
382
370
|
| `WITH` pipelines | The topology graph |
|
|
@@ -434,9 +422,8 @@ reads it at one block.
|
|
|
434
422
|
- **Shortest paths rank by hop count.** Weighted money paths are not part of
|
|
435
423
|
the product. Use `SHORTEST 1` with a quantified bound instead of enumerating
|
|
436
424
|
hops client-side.
|
|
437
|
-
- **Facts stays
|
|
438
|
-
|
|
439
|
-
with `graph_query_batch`.
|
|
425
|
+
- **Facts stays one pair, one day.** Write one explicit pattern per pair and
|
|
426
|
+
per day and batch them with `graph_query_batch`.
|
|
440
427
|
- When a query is rejected, read the returned contract error — it names the exact
|
|
441
428
|
violated bound or unsupported shape.
|
|
442
429
|
|
package/docs/graph-tools.md
CHANGED
|
@@ -10,11 +10,14 @@ the `cia mcp` commands. Results are returned as text and structured facts.
|
|
|
10
10
|
|
|
11
11
|
The Chain Insights Graph surface is intentionally small:
|
|
12
12
|
|
|
13
|
-
| Tool
|
|
14
|
-
|
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
|
|
13
|
+
| Tool | Purpose |
|
|
14
|
+
| ------------------- | ----------------------------------------------------------------------- |
|
|
15
|
+
| `graph_query` | Run one read-only GQL/Cypher query through the universal graph endpoint |
|
|
16
|
+
| `graph_query_batch` | Run related read-only graph-language queries as one MCP call |
|
|
17
|
+
|
|
18
|
+
The networks and layers a backend serves are read through
|
|
19
|
+
`meta_network_capabilities`; the backend's own capability tool is never
|
|
20
|
+
exposed by name.
|
|
18
21
|
|
|
19
22
|
`aml_address_risk` is hidden until its verdict is fixed. The MCP proxy does
|
|
20
23
|
not list it and refuses a call to it as an unknown tool.
|
|
@@ -25,8 +28,9 @@ indexed, and `cia mcp networks` for the full network capability matrix with
|
|
|
25
28
|
each network's remote tools.
|
|
26
29
|
Use `cia mcp call` for low-level GraphRAG calls and custom read-only queries.
|
|
27
30
|
|
|
28
|
-
The Chain Insights MCP proxy adds
|
|
29
|
-
`
|
|
31
|
+
The Chain Insights MCP proxy adds the local tools `meta_network_capabilities`,
|
|
32
|
+
`meta_schema`, `meta_rules`, `meta_help`, `meta_usage_status`,
|
|
33
|
+
`meta_subscription_status`, `wallet_balance` and `wallet_topup`. On hosted
|
|
30
34
|
backends, `meta_usage_status` can reflect remote quota telemetry. On
|
|
31
35
|
backends without a quota tool, Chain Insights returns a local unmetered
|
|
32
36
|
primitive-backend status instead.
|
|
@@ -341,7 +345,7 @@ and `:Sanctioned`. Each role also has a flag on the node.
|
|
|
341
345
|
`kind` is a column and a filter. Add `t.kind = "internal"` to the pair and the
|
|
342
346
|
day to read only the internal rows.
|
|
343
347
|
- Use `meta_usage_status` through Chain Insights before public hosted reads
|
|
344
|
-
when you need the caller's remaining free-
|
|
348
|
+
when you need the caller's remaining free-tier allowance.
|
|
345
349
|
- Hosted endpoints expose a free tier for graph_query and graph_query_batch:
|
|
346
350
|
5,000 units a day per address (an IP address block), 30 requests a minute,
|
|
347
351
|
reset at midnight UTC. A unit is one returned row, node, edge or list
|
|
@@ -357,11 +361,12 @@ and `:Sanctioned`. Each role also has a flag on the node.
|
|
|
357
361
|
sets.
|
|
358
362
|
- Chain Insights Graph does not append `LIMIT`; Chain Insights recipes own their
|
|
359
363
|
own limits and pagination.
|
|
360
|
-
- Use bounded `graph_query` calls for public no-wallet free-
|
|
364
|
+
- Use bounded `graph_query` calls for public no-wallet free-tier usage.
|
|
361
365
|
`graph_query_batch` is also included in the free tier; use it for related
|
|
362
366
|
reads that should share one call.
|
|
363
|
-
- `per_query_timeout_seconds` is
|
|
364
|
-
`USE facts`). It can lower a
|
|
367
|
+
- `per_query_timeout_seconds` is a `graph_query_batch` argument only. It is
|
|
368
|
+
optional and capped at `60` by default (`30` for `USE facts`). It can lower a
|
|
369
|
+
limit. It cannot raise one. `graph_query` takes no timeout argument.
|
|
365
370
|
- Returned rows live in `structuredContent.facts`.
|
|
366
371
|
|
|
367
372
|
Agent installers ship one skill:
|
|
@@ -407,8 +412,8 @@ cia mcp call graph_query_batch \
|
|
|
407
412
|
```
|
|
408
413
|
|
|
409
414
|
A batch is one call and counts the units of all its returned rows. The free
|
|
410
|
-
|
|
411
|
-
the remaining free-
|
|
415
|
+
tier includes batches. On public hosted endpoints, a batch that would pass
|
|
416
|
+
the remaining free-tier allowance can ask for paid x402 access.
|
|
412
417
|
|
|
413
418
|
Batch result facts include:
|
|
414
419
|
|
|
@@ -432,7 +437,7 @@ Hosted `USE topology` queries share one graph database, so every query is
|
|
|
432
437
|
bounded:
|
|
433
438
|
|
|
434
439
|
- **Time:** the graph database stops a query when its time budget ends
|
|
435
|
-
(60 seconds by default, or
|
|
440
|
+
(60 seconds by default, or the lower `per_query_timeout_seconds` of a batch).
|
|
436
441
|
- **Concurrency:** topology queries share the slots of the hosted endpoint, so
|
|
437
442
|
a query waits for a free slot inside its own time budget, and a busy endpoint
|
|
438
443
|
answers `topology_busy`. The number of slots is the server's to publish, not
|
package/docs/mcp-proxy.md
CHANGED
|
@@ -81,8 +81,10 @@ The proxy:
|
|
|
81
81
|
| --------------------------- | ------------------------------------------------------------------------------------ |
|
|
82
82
|
| `meta_network_capabilities` | Show the current Chain Insights network/tool support matrix |
|
|
83
83
|
| `meta_schema` | Show the live graph schema of a network: labels, link types, fields, indexes |
|
|
84
|
-
| `
|
|
84
|
+
| `meta_rules` | Read the answer rules when the `chain-insights-cypher` skill is not loaded |
|
|
85
85
|
| `meta_help` | Show Chain Insights tool and workflow guidance |
|
|
86
|
+
| `meta_usage_status` | Check the caller's daily free-tier graph query allowance |
|
|
87
|
+
| `meta_subscription_status` | Check the caller's $CIA subscription window and allowance |
|
|
86
88
|
| `wallet_balance` | Show the local payment wallet address, payment network, token, and amount |
|
|
87
89
|
| `wallet_topup` | Show the local payment wallet address and its QR code, with a Claude view |
|
|
88
90
|
| `graph_expand` | Expand a node or list a link's transfers in an open picture; called by the view only |
|
|
@@ -242,7 +244,7 @@ cia access-key set ci_test_REDACTED --endpoint https://mcp.chain-insights.ai/
|
|
|
242
244
|
cia access-key status
|
|
243
245
|
```
|
|
244
246
|
|
|
245
|
-
Daily free-
|
|
247
|
+
Daily free-tier graph usage:
|
|
246
248
|
|
|
247
249
|
```bash
|
|
248
250
|
cia mcp call meta_usage_status
|
|
@@ -282,11 +284,6 @@ cia mcp call --json graph_query \
|
|
|
282
284
|
"query=USE topology MATCH (a:Address) RETURN a.address AS address LIMIT 10"
|
|
283
285
|
```
|
|
284
286
|
|
|
285
|
-
UAT on 2026-05-31 showed the earlier free tier was enough for exact
|
|
286
|
-
address checks, sample address reads, sample flow reads, and the
|
|
287
|
-
free-to-paid handoff, but bounded sample reads still returned topology data
|
|
288
|
-
inside the same daily allowance.
|
|
289
|
-
|
|
290
287
|
For graph reads, install `chain-insights-cypher`. It teaches ISO GQL, the
|
|
291
288
|
three read layers, one query for each kind of graph search, and how to find
|
|
292
289
|
the fields of the graph.
|
|
@@ -341,9 +338,13 @@ flags:
|
|
|
341
338
|
cia setup claude-code
|
|
342
339
|
cia setup claude-desktop
|
|
343
340
|
cia setup codex
|
|
341
|
+
cia setup chatgpt
|
|
344
342
|
cia setup hermes
|
|
345
343
|
```
|
|
346
344
|
|
|
345
|
+
`cia setup chatgpt` sets up the ChatGPT desktop app: its Codex chats run
|
|
346
|
+
Chain Insights. Ask there, not in a plain ChatGPT chat.
|
|
347
|
+
|
|
347
348
|
`cia setup claude` is an alias for `cia setup
|
|
348
349
|
claude-code`. `cia setup claude-desktop` writes the proxy into Claude
|
|
349
350
|
Desktop's `claude_desktop_config.json`, keeps every other entry, saves a
|
|
@@ -365,7 +366,9 @@ the plugin: `codex plugin remove chain-insights@chain-insights`, then
|
|
|
365
366
|
Current MCP prompts exposed by the local proxy:
|
|
366
367
|
|
|
367
368
|
- `meta-network-capabilities`
|
|
369
|
+
- `meta-schema`
|
|
368
370
|
- `meta-usage-status`
|
|
371
|
+
- `meta-subscription-status`
|
|
369
372
|
- `graph-query`
|
|
370
373
|
- `graph-query-batch`
|
|
371
374
|
- `wallet-balance`
|
package/docs/stability.md
CHANGED
|
@@ -18,17 +18,23 @@ Exit codes are contract. Scripts and agent harnesses may rely on them.
|
|
|
18
18
|
|
|
19
19
|
### MCP tool names
|
|
20
20
|
|
|
21
|
-
The public MCP surface is these
|
|
21
|
+
The public MCP surface is these ten tools:
|
|
22
22
|
|
|
23
23
|
- `graph_query`
|
|
24
24
|
- `graph_query_batch`
|
|
25
|
-
- `meta_help`
|
|
26
25
|
- `meta_network_capabilities`
|
|
27
26
|
- `meta_schema`
|
|
27
|
+
- `meta_rules`
|
|
28
|
+
- `meta_help`
|
|
28
29
|
- `meta_usage_status`
|
|
30
|
+
- `meta_subscription_status`
|
|
29
31
|
- `wallet_balance`
|
|
30
32
|
- `wallet_topup`
|
|
31
33
|
|
|
34
|
+
`graph_expand` is the eleventh tool the proxy registers. The view calls it
|
|
35
|
+
when you click in a picture; hosts keep it out of the model's tool list. It
|
|
36
|
+
is not part of the public surface.
|
|
37
|
+
|
|
32
38
|
Tool names are contract. Removing or renaming one is a deprecation event.
|
|
33
39
|
Tool _arguments_ may grow additively at any time; existing argument names and
|
|
34
40
|
meanings are stable.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "chain-insights",
|
|
3
|
-
"version": "0.58.
|
|
3
|
+
"version": "0.58.4",
|
|
4
4
|
"description": "AML investigation CLI and MCP proxy for blockchain risk screening and Chain Insights Graph access",
|
|
5
5
|
"homepage": "https://chain-insights.ai",
|
|
6
6
|
"repository": {
|
|
@@ -50,8 +50,7 @@
|
|
|
50
50
|
"dist",
|
|
51
51
|
"skills",
|
|
52
52
|
"!skills/rbmk-*",
|
|
53
|
-
"docs/*.md"
|
|
54
|
-
"docs/images"
|
|
53
|
+
"docs/*.md"
|
|
55
54
|
],
|
|
56
55
|
"scripts": {
|
|
57
56
|
"build": "tsdown && mkdir -p dist/assets dist/apps && cp -r src/wallet/mcp-proxy/assets/* dist/assets/ && cp src/mcp/apps/claude-view.html dist/apps/",
|
|
Binary file
|