@secondlayer/mcp 7.2.1 → 7.4.0

package/README.md

@@ -3,9 +3,10 @@
 Gives your coding agent direct access to the Stacks data on your own instance —
 Index (decoded rows), Subgraphs (tables you define, served from your instance),
 and Streams (raw inputs). Exposes the golden-path tools only: Index reads, the
-subgraph lifecycle, subscriptions, and contract discovery/scaffolding.
-Everything else (single-record lookups, mempool, stacking, proofs, codegen,
-credits, live Streams reads) is available over REST `/v1` + OpenAPI.
+subgraph lifecycle, subscriptions, contract discovery/scaffolding, instance
+status, archive verify/bootstrap, and hosted credits/quote. Everything else
+(single-record lookups, mempool, stacking, proofs, live Streams reads) is
+available over REST `/v1` + OpenAPI. There is no `consume` tool.
 
 ## Install
 
@@ -15,7 +16,7 @@ bun add @secondlayer/mcp
 
 ## Auth
 
-Most reads are public: `index_*` and `contracts_find` work with no key. Subgraph tools need an `INSTANCE_TOKEN` past loopback; separately, **public** subgraphs are anon-readable over HTTP at `GET /v1/subgraphs/<name>/<table>` (`{ rows, next_cursor, tip }` cursor envelope), while private ones need the instance token (anon → 404). `streams_dumps` needs no key: the dumps manifest is public; the tool only needs `SL_STREAMS_DUMPS_URL` configured. Every other `streams_*` tool is key-mandatory (keyless → 401). Writes (deploy, reindex, delete, subscriptions) need a key: set `INSTANCE_TOKEN` from `secondlayer init`. `SL_API_KEY` is a legacy alias of `INSTANCE_TOKEN`. Read `secondlayer://context` first: it reports auth state and read-auth tiers.
+Most reads are public: `index_*` and `contracts_find` work with no key. Subgraph tools need an `INSTANCE_TOKEN` past loopback; separately, **public** subgraphs are anon-readable over HTTP at `GET /v1/subgraphs/<name>/<table>` (`{ rows, next_cursor, tip }` cursor envelope), while private ones need the instance token (anon → 404). `streams_dumps` needs no key: the dumps manifest is public; the tool only needs `SL_STREAMS_DUMPS_URL` configured. Every other `streams_*` tool is key-mandatory (keyless → 401). Writes (deploy, reindex, delete, subscriptions) need a key: set `INSTANCE_TOKEN` from `secondlayer init`. Hosted credits/quote use `SECONDLAYER_API_KEY` (`sk-sl_*`). Read `secondlayer://context` first: it reports auth state and read-auth tiers.
 
 ## Quick Start — Stdio (IDE)
 
@@ -50,9 +51,11 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
-| `INSTANCE_TOKEN` | Writes only | — | From `secondlayer init`. Required for write tools; reads are public. `SL_API_KEY` is a legacy alias. |
-| `SL_API_URL` | No | `http://127.0.0.1:3800` | Instance API. |
-| `SECONDLAYER_API_URL` | No | — | Overrides `SL_API_URL`. |
+| `INSTANCE_TOKEN` | Writes only | — | From `secondlayer init`. Required for write tools; reads are public. Not valid for hosted credits. |
+| `SECONDLAYER_API_KEY` | Hosted credits/quote/latest | — | `sk-sl_*` for `api.secondlayer.tools`. `SL_API_KEY` / `SL_ARCHIVE_API_KEY` are one-release fallbacks. |
+| `SECONDLAYER_API_URL` | No | `http://127.0.0.1:3800` | Instance API. `SL_API_URL` is a one-release fallback. |
+| `SECONDLAYER_BIN` | CLI tools | `secondlayer` on PATH | Path to the CLI binary (`setup`, `bootstrap`, `repair`). |
+| `SECONDLAYER_CWD` | CLI tools | process cwd | Compose project directory. |
 | `SECONDLAYER_MCP_PORT` | No | `3100` | HTTP transport port. |
 | `SECONDLAYER_MCP_SECRET` | No | — | Bearer token for HTTP auth. Disabled if unset. |
 
@@ -65,16 +68,22 @@ bunx -p @secondlayer/mcp secondlayer-mcp-http
 | **Subscriptions** (13) | `subscriptions_create`, `subscriptions_list`, `subscriptions_get`, `subscriptions_update`, `subscriptions_delete`, `subscriptions_test`, `subscriptions_pause`, `subscriptions_resume`, `subscriptions_rotate_secret`, `subscriptions_deliveries`, `subscriptions_dead`, `subscriptions_requeue`, `subscriptions_replay` |
 | **Streams** (7) | `streams_tip`, `streams_events`, `streams_events_by_tx`, `streams_block_events`, `streams_canonical`, `streams_reorgs`, `streams_dumps` |
 | **Contracts** (2) | `contracts_find`, `contracts_get_abi` |
+| **Instance** (1) | `instance_status` |
+| **Archive** (5) | `archive_verify`, `archive_bootstrap`, `archive_repair`, `archive_latest`, `archive_quote` |
+| **Setup** (1) | `setup` |
+| **Credits** (1) | `credits_balance` (needs `SECONDLAYER_API_KEY`) |
 | **Account** (2) | `account_whoami`, `account_create_key` (only when pointed at `https://api.secondlayer.tools`) |
 
 Verify after mutating: `subgraphs_operations` for deploy/reindex/backfill/stop,
-`subscriptions_deliveries` for create/test/replay.
+`subscriptions_deliveries` for create/test/replay. Empty index: `setup` or
+`archive_bootstrap`, poll `instance_status` until decoders are ok, then
+`archive_verify`, then `codegen_index_schema`.
 
 Periphery surfaces (single block/tx lookups, mempool, stacking, proofs,
 credits/caps, live Streams SSE) are REST-only: see the OpenAPI spec at the API
 host. Following the chain over MCP means polling `streams_events` with a cursor.
 
-Point the server at your instance with `SL_API_URL` (default
+Point the server at your instance with `SECONDLAYER_API_URL` (default
 `http://127.0.0.1:3800`). Writes use `INSTANCE_TOKEN` from
 `secondlayer init`. `account_*` tools appear only when the server is pointed at
 `https://api.secondlayer.tools`.