Phase 8: Documentation Updates

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: akolotov

.env.example

@@ -32,6 +32,12 @@ BLOCKSCOUT_PRO_API_KEY=""
 #   When a client sends this header, its key takes precedence over BLOCKSCOUT_PRO_API_KEY for that request; absent it, the server key is used.
 #   A malformed client-supplied key fails any PRO API request that would use it, with no fallback; tools that don't use the PRO API are unaffected. Set to an empty string to disable client-supplied keys entirely.
 BLOCKSCOUT_PRO_API_KEY_HEADER="Blockscout-MCP-Pro-Api-Key"
+# Low-credits advisory threshold, in PRO API credits. When the remaining credit balance
+# reported by the PRO API (header `x-credits-remaining`) drops below this value, data tools
+# append an advisory note to their responses. Set to 0 to disable the note.
+#   Default rationale: per-call costs range 20–120 credits (see /api/json/config "endpoint_pricing");
+#   5000 ≈ 250 cheapest (20-credit) calls or ~41 most expensive (120-credit) calls.
+BLOCKSCOUT_PRO_API_LOW_CREDITS_THRESHOLD=5000
 BLOCKSCOUT_CHAINS_LIST_TTL_SECONDS=300
 BLOCKSCOUT_PROGRESS_INTERVAL_SECONDS="15.0"
 

AGENTS.md

@@ -23,7 +23,7 @@ mcp-server/
 │   ├── analytics.py            # Centralized Mixpanel analytics for tool invocations (HTTP mode only)
 │   ├── telemetry.py            # Fire-and-forget community telemetry reporting
 │   ├── client_meta.py          # Shared client metadata extraction helpers and defaults
-│   ├── pro_api_key_context.py  # Request-scoped client-supplied PRO API key state, resolver, and @pro_api_key_scope decorator
+│   ├── pro_api_key_context.py  # Request-scoped client-supplied PRO API key state, resolver, and @pro_api_key_scope decorator; per-invocation credit sink and @pro_api_credit_scope decorator
 │   ├── cache.py                # Simple in-memory cache for chain data
 │   ├── web3_pool.py            # Async Web3 connection pool manager
 │   ├── models.py               # Defines standardized Pydantic models for all tool responses
@@ -188,7 +188,8 @@ mcp-server/
 │       ├── test_common.py            # Unit tests for shared tool utilities
 │       ├── test_common_truncate.py   # Unit tests for truncation helpers
 │       ├── test_common_post_request.py   # Unit tests for POST request helper
-│       └── test_decorators.py        # Unit tests for logging decorators
+│       ├── test_decorators.py        # Unit tests for logging decorators
+│       └── test_credit_tracking.py   # Unit tests for PRO API credit capture and low-credits note
 ├── mcpb/                       # MCP Bundle package for Claude Desktop
 │   ├── README.md               # MCPB documentation and build instructions
 │   ├── manifest.json           # Bundle manifest for development builds
@@ -388,6 +389,7 @@ mcp-server/
         * Owns request-scoped resolution of a client-supplied Blockscout PRO API key, kept separate from logging/observability.
         * Provides a `ContextVar` of the per-request client-key state, a normalization/validation helper, `extract_client_pro_api_key_from_ctx()`, `resolve_pro_api_key()` (precedence: valid client key → server key → not-configured error; malformed client key → terminal error, no fallback), and the `@pro_api_key_scope` decorator.
         * Honored only for genuine MCP calls (ignored when `ctx.call_source == "rest"`); the key is never logged or placed in cache keys.
+        * Also defines the per-invocation credit-tracking symbols: `CreditSink`, the `_credit_sink` `ContextVar`, and the `@pro_api_credit_scope` decorator (a sibling of `@pro_api_key_scope`).
     * **`cache.py`**:
         * Encapsulates in-memory caching of chain data with TTL management.
     * **`web3_pool.py`**:

API.md

@@ -65,7 +65,7 @@ Tool endpoints under `/v1/` return a consistent JSON object that wraps the tool'
 
 - `data`: The main data payload of the response. Its structure is specific to each endpoint.
 - `data_description`: (Optional) A list of strings explaining the structure or fields of the `data` payload.
-- `notes`: (Optional) A list of important warnings or contextual notes, such as data truncation alerts.
+- `notes`: (Optional) A list of important warnings or contextual notes, such as data truncation alerts or a low-credits advisory emitted when the Blockscout PRO API credit balance drops below the configured threshold.
 - `instructions`: (Optional) A list of suggested follow-up actions for an AI agent.
 - `pagination`: (Optional) An object containing information to retrieve the next page of results.
 

README.md

@@ -231,6 +231,8 @@ export BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here
 
 **Client-supplied keys (HTTP MCP only).** When the server runs in HTTP mode, an MCP client can supply its own PRO API key in a request header — by default `Blockscout-MCP-Pro-Api-Key`, configurable via `BLOCKSCOUT_PRO_API_KEY_HEADER` (set it to an empty string to disable client-supplied keys entirely). A client-supplied key takes precedence over `BLOCKSCOUT_PRO_API_KEY` for that request; if the client sends no key, the server falls back to its own configured key; if neither is present, the request fails with the not-configured error. A client key that is present but malformed fails any request that needs the PRO API with no fallback (the server never silently uses its own key in place of a bad client key); tools that don't use the PRO API are unaffected. This makes it possible to run a shared HTTP server where each client authenticates with its own key. The client-key header is honored only for genuine MCP tool calls — the REST API ignores it and always authenticates with the server's configured key.
 
+**Low-credit warning.** Access to the PRO API is metered in credits. When the remaining balance reported by the API drops below a configurable threshold, every data tool appends an advisory note to its response, prompting operators to top up so PRO API access stays ready for continued high-volume usage. The threshold is set via `BLOCKSCOUT_PRO_API_LOW_CREDITS_THRESHOLD` (default `5000` credits; set to `0` to disable the note). The note fires for any balance below the threshold, including zero and negative balances.
+
 ### Running the Server
 
 The server runs in `stdio` mode by default:

SPEC.md

@@ -274,7 +274,7 @@ Credit-exhaustion responses on the PRO API *data path* are special-cased: the sh
 
    - `data`: The main data payload of the tool's response. The schema of this field can be specific to each tool.
    - `data_description`: An optional list of strings that explain the structure, fields, or conventions of the `data` payload (e.g., "The `method_call` field is actually the event signature...").
-   - `notes`: An optional list of important contextual notes, such as warnings about data truncation or data quality issues. This field includes guidance on how to retrieve full data if it has been truncated.
+   - `notes`: An optional list of important contextual notes, such as warnings about data truncation or data quality issues, or a low-credits advisory when the Blockscout PRO API credit balance falls below the configured threshold. This field includes guidance on how to retrieve full data if it has been truncated.
    - `instructions`: An optional list of suggested follow-up actions for the LLM to plan its next steps. When pagination is available, the server automatically appends pagination instructions to motivate LLMs to fetch additional pages.
    - `pagination`: An optional object that provides structured information for retrieving the next page of results.
 
@@ -601,6 +601,8 @@ Credit-exhaustion responses on the PRO API *data path* are special-cased: the sh
 
    When changing the retry policy, account for both surfaces.
 
+   **Credit usage visibility (advisory low-credits note).** When the PRO API reports a low remaining credit balance, the server surfaces it as an advisory note in `ToolResponse.notes`. The signal is best-effort and HTTP-backed — captured opportunistically from PRO API responses and never affecting the request outcome — and is gated by an operator-configurable threshold that can tune or disable it (configured via environment variable; see README and `.env.example`). It is the plan-agnostic early-warning complement to the credit-exhaustion hard-stop documented in §8 ("Credit Exhaustion"). Implementation mechanics are documented in the relevant code docstrings and exercised by focused unit tests, not restated in this specification.
+
 8. **HTTP Error Handling and Context Propagation**
 
    To enable AI agents to self-correct when API requests fail (e.g., due to invalid parameters like unsupported sort fields), the server implements a robust error propagation strategy.