@blurt-blockchain/blurt-mcp-server 0.4.0

package/dist/utils/signer.js

@@ -0,0 +1,350 @@
+// Write-operation support: posting-key handling, least-privilege validation,
+// rate caps, and the broadcast operations (claim rewards, upvote, comment).
+//
+// SECURITY (see SECURITY.md):
+// - Only a Blurt POSTING key is ever accepted (active/owner are refused).
+// - The key flows ONLY into dblurt's local signing; never to the network, logs,
+//   or any other dependency.
+// - Write is enabled ONLY on the local stdio server by default. HTTP signing is
+//   possible only behind an explicit, dangerously named operator override.
+import { PrivateKey, Asset, buildReplyOperation, buildPostOperation, normalizeContentTags, buildFollowOperation, buildUnfollowOperation, buildMuteOperation, buildUnmuteOperation, buildCommunitySubscribeOperation, buildCommunityUnsubscribeOperation, buildReadNotificationOperation, buildReblogOperation, buildUndoReblogOperation, } from "@beblurt/dblurt";
+import logger from "./logger.js";
+import pkg from "../../package.json" with { type: "json" };
+/** json_metadata.app value stamped on content created through this connector. */
+const APP_TAG = `blurt-mcp/${pkg.version}`;
+/** Footer appended to every comment body. */
+const MCP_FOOTER = "<sub>via [Blurt-MCP](https://gitlab.com/blurt-blockchain/blurt-mcp-server)</sub>";
+/** Canonical list of every write tool's allowlist name. */
+export const WRITE_TOOLS = [
+    "claim-rewards",
+    "upvote",
+    "comment",
+    "follow",
+    "mute",
+    "subscribe-community",
+    "read-notifications",
+    "reblog",
+    "post",
+];
+/**
+ * Semantic write profiles. These are the recommended operator-facing control
+ * surface; individual tool names remain available as a subtractive legacy
+ * denylist for compatibility and emergency lockdown.
+ */
+export const WRITE_PROFILES = {
+    none: [],
+    // Low-risk curation/account-maintenance profile for new users.
+    curator: ["claim-rewards", "upvote"],
+    // Social graph/community/reblog operations, but no original text publishing.
+    social: [
+        "claim-rewards",
+        "upvote",
+        "follow",
+        "mute",
+        "subscribe-community",
+        "read-notifications",
+        "reblog",
+    ],
+    // All current content/social/reward tools. Future high-risk tools should be
+    // classified deliberately before they are added to this profile.
+    publisher: [
+        "claim-rewards",
+        "upvote",
+        "comment",
+        "follow",
+        "mute",
+        "subscribe-community",
+        "read-notifications",
+        "reblog",
+        "post",
+    ],
+    // Explicit full-access profile and legacy unset-profile behavior.
+    full: WRITE_TOOLS,
+};
+function normalizeWriteProfile(profileEnv) {
+    const raw = profileEnv?.trim().toLowerCase();
+    if (!raw)
+        return "full"; // backward compatibility for existing deployments
+    if (raw === "all" || raw === "legacy")
+        return "full";
+    if (raw in WRITE_PROFILES)
+        return raw;
+    throw new Error(`Invalid BLURT_WRITE_PROFILE=${profileEnv}. Expected one of: ${Object.keys(WRITE_PROFILES).join(", ")}.`);
+}
+/**
+ * Resolve which write tools are enabled.
+ *
+ * Backward compatibility: when `BLURT_WRITE_PROFILE` is unset, the historical
+ * behavior is preserved: every write tool is enabled and
+ * `BLURT_WRITE_TOOLS_BANNED` subtracts individual tools.
+ *
+ * New deployments should set a semantic `BLURT_WRITE_PROFILE` such as
+ * `curator`, `social`, or `publisher`, then optionally subtract individual tools
+ * with `BLURT_WRITE_TOOLS_BANNED`.
+ */
+export function enabledWriteTools(bannedEnv = process.env.BLURT_WRITE_TOOLS_BANNED, profileEnv = process.env.BLURT_WRITE_PROFILE) {
+    const profile = normalizeWriteProfile(profileEnv);
+    const banned = new Set((bannedEnv ?? "").split(",").map((s) => s.trim()).filter(Boolean));
+    return new Set(WRITE_PROFILES[profile].filter((t) => !banned.has(t)));
+}
+export function dryRunDefault(env = process.env) {
+    const raw = env.BLURT_DRY_RUN_DEFAULT?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    if (["1", "true", "yes", "on"].includes(raw))
+        return true;
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    throw new Error("Invalid BLURT_DRY_RUN_DEFAULT. Expected true/false, 1/0, yes/no, or on/off.");
+}
+export const HTTP_SIGNING_UNSAFE_OVERRIDE_ENV = "BLURT_UNSAFE_ALLOW_HTTP_SIGNING_WITH_POSTING_KEY";
+export const HTTP_SIGNING_UNSAFE_OVERRIDE_VALUE = "I_ACCEPT_FULL_RESPONSIBILITY_FOR_EXPOSING_BLURT_WRITE_TOOLS_OVER_HTTP";
+const HTTP_SIGNING_UNSAFE_WARNING = `
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!! UNSAFE HTTP SIGNING ENABLED                                        !!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+The Blurt MCP HTTP server is starting with BLURT_POSTING_KEY configured and
+${HTTP_SIGNING_UNSAFE_OVERRIDE_ENV}=${HTTP_SIGNING_UNSAFE_OVERRIDE_VALUE}.
+
+This exposes Blurt write/signing tools through the HTTP MCP endpoint. HTTP MCP
+clients may be remote, automated, compromised, misconfigured, or reachable through
+reverse-proxy mistakes. Any tool call that reaches this server can request signed
+posting operations for the configured account.
+
+Use this only for private, authenticated, access-controlled trusted deployments.
+Do not use it on the public hosted endpoint or on an unauthenticated LAN/WAN
+service. The operator accepts full responsibility for every signature, post,
+vote, custom_json, claim, or other on-chain operation produced by this process.
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`;
+/**
+ * Guard for the HTTP entrypoint: refuse to start if a posting key is configured
+ * unless the operator sets the exact, intentionally dangerous override value.
+ *
+ * Returns true only when HTTP signing has been explicitly allowed.
+ */
+export function assertNoKeyForHttp(options = {}) {
+    const env = options.env ?? process.env;
+    const warn = options.warn ?? ((message) => logger.error(message));
+    if (!env.BLURT_POSTING_KEY)
+        return false;
+    if (env[HTTP_SIGNING_UNSAFE_OVERRIDE_ENV] === HTTP_SIGNING_UNSAFE_OVERRIDE_VALUE) {
+        warn(HTTP_SIGNING_UNSAFE_WARNING);
+        return true;
+    }
+    const suffix = env[HTTP_SIGNING_UNSAFE_OVERRIDE_ENV]
+        ? ` To override anyway, ${HTTP_SIGNING_UNSAFE_OVERRIDE_ENV} must exactly equal ${HTTP_SIGNING_UNSAFE_OVERRIDE_VALUE}.`
+        : "";
+    throw new Error("BLURT_POSTING_KEY is set but the HTTP server must stay read-only by default. " +
+        "Run the stdio server (npm run start:stdio) for normal signing operations." +
+        suffix);
+}
+/**
+ * Build the write context from the environment. Returns null when no key is
+ * configured (read-only). Throws when a key is present but invalid or is not the
+ * account's posting key — the caller must then refuse to start.
+ */
+export async function createWriteContext(client) {
+    const account = process.env.BLURT_ACCOUNT?.trim();
+    const wif = process.env.BLURT_POSTING_KEY?.trim();
+    if (!account && !wif)
+        return null; // read-only
+    if (!account || !wif) {
+        throw new Error("Both BLURT_ACCOUNT and BLURT_POSTING_KEY must be set to enable write operations.");
+    }
+    let key;
+    try {
+        key = PrivateKey.fromString(wif);
+    }
+    catch {
+        throw new Error("BLURT_POSTING_KEY is not a valid WIF private key.");
+    }
+    await assertIsPostingKey(client, account, key);
+    return { account, key, enabledTools: enabledWriteTools() };
+}
+/**
+ * Least privilege: require a key that satisfies POSTING authority over the
+ * account, using dblurt's canonical Layer 1 authority traversal. The SDK reports
+ * owner/active matches as metadata rather than treating them as protocol errors;
+ * this MCP local-signing mode deliberately rejects those broader authorities as
+ * application policy.
+ */
+async function assertIsPostingKey(client, account, key) {
+    const result = await client.condenser.validatePostingAuthority(account, key);
+    if (result.matches.owner.authorized || result.matches.active.authorized) {
+        throw new Error("Refusing to use an owner/active key — only POSTING authority is allowed.");
+    }
+    if (!result.authorized) {
+        throw new Error(`The provided key has no posting authority over @${account} ` +
+            `(reason: ${result.reason}).`);
+    }
+    const viaDelegation = (result.matches.posting.approvedAccounts ?? []).length > 0;
+    logger.info(`Write enabled for @${account} (posting authority validated${viaDelegation ? ", via delegation" : ""}).`);
+}
+// --- Simple in-memory, per-tool rate cap -----------------------------------
+const callTimes = {};
+export function withinCap(tool, max, windowMs) {
+    const now = Date.now();
+    const recent = (callTimes[tool] = (callTimes[tool] ?? []).filter((t) => now - t < windowMs));
+    if (recent.length >= max)
+        return false;
+    recent.push(now);
+    return true;
+}
+export async function claimRewards(client, ctx, dryRun) {
+    const [acc] = await client.condenser.getAccounts([ctx.account]);
+    if (!acc)
+        throw new Error(`Account not found: @${ctx.account}`);
+    const reward_blurt = acc.reward_blurt_balance.toString();
+    const reward_vests = acc.reward_vesting_balance.toString();
+    const nothing = Asset.from(reward_blurt).amount === 0 && Asset.from(reward_vests).amount === 0;
+    const base = {
+        account: ctx.account,
+        pending_blurt: reward_blurt,
+        pending_vests: reward_vests,
+        pending_power_blurt: acc.reward_vesting_blurt.toString(),
+        nothing_to_claim: nothing,
+    };
+    if (dryRun || nothing) {
+        return { ...base, dry_run: dryRun, claimed: false };
+    }
+    const result = await client.broadcast.claimRewardBalance({ account: ctx.account, reward_blurt, reward_vests }, ctx.key);
+    return { ...base, dry_run: false, claimed: true, tx_id: result.id };
+}
+export async function upvote(client, ctx, args) {
+    const base = {
+        voter: ctx.account,
+        author: args.author,
+        permlink: args.permlink,
+        weight_percent: args.weight,
+    };
+    if (args.dryRun)
+        return { ...base, dry_run: true, voted: false };
+    // weight is a percentage (1-100); on chain 100% = 10000.
+    const result = await client.broadcast.vote({ voter: ctx.account, author: args.author, permlink: args.permlink, weight: args.weight * 100 }, ctx.key);
+    return { ...base, dry_run: false, voted: true, tx_id: result.id };
+}
+export async function comment(client, ctx, args) {
+    const body = `${args.body}\n\n${MCP_FOOTER}`;
+    const op = buildReplyOperation({
+        parentAuthor: args.parentAuthor,
+        parentPermlink: args.parentPermlink,
+        author: ctx.account,
+        body,
+        app: APP_TAG,
+        format: "markdown",
+        permlinkSuffix: Date.now().toString(36),
+    });
+    const payload = op[1];
+    const base = {
+        author: payload.author,
+        permlink: payload.permlink,
+        parent_author: payload.parent_author,
+        parent_permlink: payload.parent_permlink,
+        app: APP_TAG,
+        body: payload.body,
+    };
+    if (args.dryRun)
+        return { ...base, dry_run: true, posted: false };
+    const result = await client.broadcast.sendOperations([op], ctx.key);
+    return { ...base, dry_run: false, posted: true, tx_id: txId(result) };
+}
+// --- shared helpers ---------------------------------------------------------
+const txId = (r) => r.id;
+export async function follow(client, ctx, args) {
+    const operation = args.action === "follow"
+        ? buildFollowOperation({ follower: ctx.account, following: args.account })
+        : buildUnfollowOperation({ follower: ctx.account, following: args.account });
+    const payload = JSON.parse(operation[1].json);
+    const base = { follower: ctx.account, following: args.account, action: args.action };
+    if (args.dryRun)
+        return { ...base, dry_run: true, done: false, tx_id: undefined };
+    const result = args.action === "follow"
+        ? await client.broadcast.follow(ctx.account, args.account, ctx.key)
+        : await client.broadcast.unfollow(ctx.account, args.account, ctx.key);
+    void payload;
+    return { ...base, dry_run: false, done: true, tx_id: txId(result) };
+}
+export async function mute(client, ctx, args) {
+    const operation = args.action === "mute"
+        ? buildMuteOperation({ follower: ctx.account, following: args.account })
+        : buildUnmuteOperation({ follower: ctx.account, following: args.account });
+    const base = { follower: ctx.account, account: args.account, action: args.action };
+    if (args.dryRun) {
+        void operation;
+        return { ...base, dry_run: true, done: false, tx_id: undefined };
+    }
+    const result = args.action === "mute"
+        ? await client.broadcast.mute(ctx.account, args.account, ctx.key)
+        : await client.broadcast.unmute(ctx.account, args.account, ctx.key);
+    return { ...base, dry_run: false, done: true, tx_id: txId(result) };
+}
+export async function subscribeCommunity(client, ctx, args) {
+    const operation = args.action === "subscribe"
+        ? buildCommunitySubscribeOperation({ account: ctx.account, community: args.community })
+        : buildCommunityUnsubscribeOperation({ account: ctx.account, community: args.community });
+    const base = { account: ctx.account, community: args.community, action: args.action };
+    if (args.dryRun) {
+        void operation;
+        return { ...base, dry_run: true, done: false, tx_id: undefined };
+    }
+    const result = args.action === "subscribe"
+        ? await client.broadcast.communitySubscribe(ctx.account, args.community, ctx.key)
+        : await client.broadcast.communityUnsubscribe(ctx.account, args.community, ctx.key);
+    return { ...base, dry_run: false, done: true, tx_id: txId(result) };
+}
+// --- mark notifications read ------------------------------------------------
+export async function readNotifications(client, ctx, args) {
+    const date = new Date().toISOString().slice(0, 19); // YYYY-MM-DDTHH:mm:ss
+    const operation = buildReadNotificationOperation({ account: ctx.account, date });
+    const base = { account: ctx.account, marked_read_up_to: date };
+    if (args.dryRun) {
+        void operation;
+        return { ...base, dry_run: true, done: false, tx_id: undefined };
+    }
+    const result = await client.broadcast.readNotification(ctx.account, date, ctx.key);
+    return { ...base, dry_run: false, done: true, tx_id: txId(result) };
+}
+// --- reblog -----------------------------------------------------------------
+export async function reblog(client, ctx, args) {
+    const operation = args.undo
+        ? buildUndoReblogOperation({ account: ctx.account, author: args.author, permlink: args.permlink })
+        : buildReblogOperation({ account: ctx.account, author: args.author, permlink: args.permlink });
+    const base = { account: ctx.account, author: args.author, permlink: args.permlink, undo: args.undo };
+    if (args.dryRun) {
+        void operation;
+        return { ...base, dry_run: true, done: false, tx_id: undefined };
+    }
+    const result = args.undo
+        ? await client.broadcast.undoReblog(ctx.account, args.author, args.permlink, ctx.key)
+        : await client.broadcast.reblog(ctx.account, args.author, args.permlink, ctx.key);
+    return { ...base, dry_run: false, done: true, tx_id: txId(result) };
+}
+export async function post(client, ctx, args) {
+    const tags = normalizeContentTags(args.tags);
+    if (tags.length === 0)
+        throw new Error("At least one tag is required.");
+    const body = `${args.body}\n\n${MCP_FOOTER}`;
+    const op = buildPostOperation({
+        author: ctx.account,
+        title: args.title,
+        body,
+        tags,
+        app: APP_TAG,
+        format: "markdown",
+        permlinkSuffix: Date.now().toString(36),
+    });
+    const payload = op[1];
+    const base = {
+        author: payload.author,
+        permlink: payload.permlink,
+        parent_permlink: payload.parent_permlink,
+        title: payload.title,
+        tags,
+        app: APP_TAG,
+        body: payload.body,
+    };
+    if (args.dryRun)
+        return { ...base, dry_run: true, posted: false };
+    const result = await client.broadcast.sendOperations([op], ctx.key);
+    return { ...base, dry_run: false, posted: true, tx_id: txId(result) };
+}

package/docs/adr/0001-neutral-infrastructure.md

@@ -0,0 +1,50 @@
+# ADR 0001 — Official server remains neutral infrastructure
+
+## Status
+
+Accepted
+
+## Context
+
+The Blurt MCP server is the official MCP interface for Blurt capabilities. It exposes public chain data and optional posting-authority write tools to AI clients.
+
+During the Phase 3 write-security review, an earlier roadmap considered richer operator policy files: allowed/blocked accounts, blocked communities/tags, posting quotas, and a separate transaction-preview architecture. That direction was re-evaluated against Blurt's Layer 1 guarantees and ecosystem values:
+
+- posting authority cannot move funds;
+- Layer 1 already enforces resource costs and operational limits;
+- Blurt is intentionally designed around freedom of expression;
+- operators can enforce private deployment policy outside the official server if they need it.
+
+## Decision
+
+The official Blurt MCP server remains neutral infrastructure.
+
+It provides secure, predictable access to Blurt capabilities, but does not impose content, account, community, tag, or usage policy beyond protocol safety, transport safety, and explicit operator-selected execution mode.
+
+The server may implement neutral safeguards such as:
+
+- read-only public HTTP by default;
+- posting-authority validation;
+- refusal of owner/active keys;
+- explicit unsafe override for HTTP signing;
+- local signing and secret-handling protections;
+- capability/profile selection for which write tools are registered;
+- dry-run defaults and exact previews;
+- small technical rate caps to prevent accidental loops.
+
+The server should not become an official policy engine for:
+
+- allowed or blocked accounts;
+- allowed or blocked tags/communities;
+- content moderation rules;
+- posting/comment quotas as social policy;
+- paternalistic restrictions on how users use posting authority.
+
+Those policies belong in clients, wrappers, gateways, reverse proxies, external signers, custom deployments, or forks when an operator needs them.
+
+## Consequences
+
+- Phase 3 is reduced to the completed signing baseline, write-surface ergonomics, `BLURT_DRY_RUN_DEFAULT`, and documentation closeout.
+- The previously proposed policy-file work is removed from the official server roadmap.
+- A standalone transaction-preview architecture is deferred until a concrete external-signer, wallet, offline-signing, or multi-operation transaction milestone requires it.
+- Future write features such as governance, witness management, wallet/external-signer flows, and moderation tools should be evaluated against this neutrality principle before adding server-side policy controls.

package/docs/architecture.md

@@ -0,0 +1,62 @@
+# Architecture — how it works
+
+- **Two entrypoints, one server.** `server.ts` exposes the tools over **Streamable HTTP** — a single
+  Express route, `POST /mcp`, in **stateless** mode (no session id), with a fresh `McpServer` built
+  per request via `buildServer()` (`GET`/`DELETE` return `405`). It also exposes cheap operational
+  probes outside MCP: `GET /healthz` and `GET /readyz`. `server-stdio.ts` exposes the same tools over
+  **stdio** for local desktop use. Both call `buildServer()`.
+- **Shared Blurt client.** One `@beblurt/dblurt` `Client` is created on first use and reused so RPC
+  connections stay warm (only the first call pays the cold-connection cost). It is configured with
+  `rpcTransport: "core"` — the default "legacy" transport aborts each attempt after `(tries+1)*500ms`
+  and then crashes (`error.code.includes is not a function`) on slow requests under the HTTP server
+  context. The choice is guarded by `test/resilience.test.ts`.
+- **RPC node selection.** A background checker
+  ([`@beblurt/blurt-nodes-checker`](https://gitlab.com/beblurt/blurt-nodes-checker)) continuously
+  scores the configured nodes (latency, chain lag, version, reliability) and repoints the shared
+  client at the healthy ones, best-first — so a slow, stale, forked or offline node is avoided rather
+  than failing a request (`src/utils/rpc.ts`). dblurt's own failover then covers transient blips
+  within that healthy set.
+- **Two data layers.** Account, wallet, history and raw votes come from the **condenser API**
+  (Layer 1); profiles, ranked posts, account posts, discussions and communities come from the
+  **Nexus / Bridge API** (Layer 2).
+- **Market price.** `get-blurt-price`, `get-chain-status` and `get-vote-value` read the external price
+  feed (`BLURT_PRICE_URL`) through a shared helper that caches it for ~60s. Price is best-effort: if
+  the feed is down, on-chain data is still returned and USD fields are `null`.
+- **`search` / `fetch`.** `search` maps a free-form query to `blurt://…` resource links without any
+  network call; `fetch` resolves such a URI (or a shorthand id) to the raw JSON. This mirrors the
+  search/fetch connector convention used by ChatGPT-style clients.
+- **Write path (opt-in).** When a posting key is present, write tools are registered through a guarded
+  write context (`src/utils/signer.ts`); the key is validated as the account's posting authority, used
+  only for local signing, and never logged or sent to the network. New deployments should use semantic
+  `BLURT_WRITE_PROFILE` capability profiles; the historical `BLURT_WRITE_TOOLS_BANNED` denylist still
+  works as a subtractive compatibility control. `BLURT_DRY_RUN_DEFAULT=true` is a neutral preview-first
+  execution-mode default: omitted `dry_run` parameters preview without broadcasting, but explicit
+  `dry_run: false` still executes. HTTP stays read-only by default and exposes signing only behind the
+  explicit unsafe trusted-deployment override. The official server does not enforce content/account/
+  community policy files; see [ADR 0001](./adr/0001-neutral-infrastructure.md),
+  [write operations](./write-operations.md), and [SECURITY.md](../SECURITY.md).
+- **Errors.** Tool failures return `isError: true` with a short message rather than throwing, so the
+  model can react instead of seeing a transport error.
+
+## Project layout
+
+```
+src/
+  server.ts            # HTTP entrypoint: builds the app and listens
+  server-stdio.ts      # stdio entrypoint: same tools as a local child process
+  app.ts               # Builds the Express app + /mcp route (no side effects, testable)
+  buildServer.ts       # Registers all tools/resources on an McpServer; BLURT_CLIENT_OPTIONS
+  tools/               # One file per MCP tool
+  resources/           # blurt:// resource templates
+  utils/
+    logger.ts          # Leveled logger (human / JSON), writes to stderr
+    loadEnv.ts         # Loads BLURT_ENV_FILE / project .env regardless of cwd
+    rpc.ts             # Shared client + RPC node selection (blurt-nodes-checker)
+    signer.ts          # Write context: posting-key validation, rate caps, signing
+    price.ts           # Cached BLURT price feed helper
+    blurtUri.ts        # blurt:// URI parsing / shorthand mapping (used by search/fetch)
+test/
+  uri / search / resilience / write   # offline (no external network)
+  live                                # live, in-memory MCP client
+  http                                # live, real Streamable HTTP transport (E2E)
+```

package/docs/cache-policy.md

@@ -0,0 +1,42 @@
+# Cache and freshness policy
+
+The official MCP server should avoid broad response caching until result contracts consistently carry
+source/freshness metadata. Incorrectly cached blockchain data can mislead AI summaries and users.
+
+## Current cache
+
+The only intentional application cache is the BLURT price helper cache. It is narrow and short-lived:
+
+- external price feed only;
+- approximately 60 seconds;
+- best-effort;
+- failures do not invalidate on-chain data;
+- USD/BTC values may be `null` when unavailable.
+
+## No generic response cache yet
+
+Do not add a generic cache layer for account, wallet, history, witness, vote, post, community or pending
+reward tools in Phase 4. These values have different freshness expectations and source layers:
+
+- Layer 1 account/wallet/reward/vote/witness state changes with blocks and account activity;
+- Nexus/Bridge ranked posts and community views have their own indexing freshness;
+- external market prices have separate freshness and failure modes;
+- mixed dashboard-style tools combine several sources.
+
+## Requirement before broader caching
+
+Before introducing per-tool TTLs, structured results should expose provenance/freshness metadata such as:
+
+- source layer (`layer1`, `nexus`, `external`, `mixed`);
+- retrieval timestamp;
+- head block or index/version when available;
+- cache hit/miss or freshness age;
+- caveats for best-effort external data.
+
+Until then, prefer correctness and transparent latency over silent stale responses.
+
+## Deployment-level caching
+
+Reverse proxies and CDNs should not cache `/mcp` responses by default. MCP requests are JSON-RPC POSTs
+whose results depend on tool arguments and upstream state. If an operator experiments with caching, it
+should be explicit, endpoint-specific, and validated against stale-data risk.

package/docs/clients.md

@@ -0,0 +1,78 @@
+# MCP client compatibility
+
+How to connect AI clients to this server. **"Remote HTTP"** means native MCP Streamable HTTP or legacy
+HTTP+SSE — those clients can use the hosted endpoint `https://mcp.blurt-blockchain.com/mcp` directly.
+Clients that only speak **stdio** can still reach a remote server through the
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, or run the local stdio build.
+
+> The 10 most relevant clients are summarised in the [README](../README.md#compatible-clients). This
+> page lists the additional clients, full config-file paths, and the sources for **both** tables.
+> For copy-paste hosted/package snippets, see [install snippets](./install-snippets.md).
+>
+> This matrix is community-maintained and clients evolve fast — corrections welcome. **Information
+> current as of 2026-06-28.**
+
+## Highlighted clients (top 10) — full detail
+
+| Client | Type | Local (stdio) | Remote (HTTP) | Config file | Open source | Notes |
+| --- | --- | ---: | ---: | --- | ---: | --- |
+| ChatGPT web — Apps / Connectors | Web | No | Yes | UI only; no config file documented | No | Remote MCP over HTTPS; local dev requires a tunnel; Developer Mode / workspace limits. [1] |
+| Claude Desktop | Desktop app | Yes | Yes | `claude_desktop_config.json` (macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`) | No | Local stdio via config; remote via custom connectors. [2] |
+| Claude Code | CLI | Yes | Yes | `~/.claude.json`; project `.mcp.json` | No | Supports `stdio`, `http`, `sse`; project config can be shared. [3] |
+| OpenAI Codex — CLI / IDE extension | CLI / IDE | Yes | Yes | `~/.codex/config.toml`; project `.codex/config.toml` | Yes | MCP in CLI and IDE extension; local stdio + Streamable HTTP. [4] |
+| VS Code — GitHub Copilot agent mode | IDE | Yes | Yes | `.vscode/mcp.json`; user profile MCP config | Partial | Tries HTTP-stream first, falls back to SSE; Copilot/agent policies may restrict. [5] |
+| Cursor | IDE | Yes | Yes | `.cursor/mcp.json`; `~/.cursor/mcp.json` | No | Supports `stdio`, SSE, Streamable HTTP; Team/Enterprise admin controls. [6] |
+| Windsurf / Cascade / Devin Desktop | IDE | Yes | Yes | `mcp_config.json` (Codeium/Windsurf paths) | No | Supports stdio, Streamable HTTP, SSE; enterprise policy may restrict. [7] |
+| Gemini CLI | CLI | Yes | Yes | `~/.gemini/settings.json`; project `.gemini/settings.json` | Yes | Supports stdio, SSE, Streamable HTTP; `gemini mcp add`. [8] |
+| JetBrains AI Assistant | IDE | Yes | Yes | Settings → Tools → AI Assistant → MCP (file path Unknown) | No | MCP in JetBrains IDEs; large user base. [9] |
+| Cline | IDE extension / CLI | Yes | Yes | CLI `~/.cline/mcp.json`; extension MCP settings JSON | Yes | VS Code ecosystem client. [10] |
+
+## Other compatible clients
+
+| Client | Type | Local (stdio) | Remote (HTTP) | Config file | Open source | Notes |
+| --- | --- | ---: | ---: | --- | ---: | --- |
+| GitHub Copilot CLI | CLI | Yes | Yes | `~/.copilot/mcp-config.json` | Unknown | Local and remote HTTP examples documented; Copilot subscription/policies apply. [11] |
+| Visual Studio — GitHub Copilot agent mode | IDE | Yes | Yes | `.mcp.json`, `.vs/mcp.json`, `.vscode/mcp.json` (by scope) | Partial | Separate from VS Code; Windows/.NET audience. [12] |
+| ChatGPT Desktop app | Desktop app | Unknown | Unknown | Unknown | No | "Work with Apps" docs are not MCP client config; document separately from ChatGPT web connectors. [13] |
+| Mistral Vibe Work / former Le Chat | Web / mobile | No | Yes | UI only; no config file documented | No | "Le Chat is now Vibe"; Work custom MCP connectors require an admin and a server URL. [14] |
+| Mistral Vibe Code CLI | CLI / IDE / Web | Yes | Yes | `config.toml`; project `./.vibe/config.toml`; user `~/.vibe/config.toml` | Yes | Supports `stdio`, `http`, `streamable-http`; no OAuth MCP in CLI yet. [15] |
+| Hermes Agent — Nous Research | CLI / local web UI | Yes | Yes | `~/.hermes/config.yaml` | Yes | Agent runtime by Nous Research; local/self-hosted workflows. [16] |
+| Google Antigravity | IDE | Yes | Yes | `~/.gemini/config/mcp_config.json` | Unknown | Agentic IDE; docs show local and remote MCP config. [17] |
+| OpenClaw | CLI / Web gateway | Yes | Yes | `~/.openclaw/openclaw.json` | Yes | Personal AI assistant/gateway; MCP client registry and server. [18] |
+| Zed Agent | IDE | Yes | Yes | Zed `settings.json` / `context_servers` (path varies) | Yes | MCP context servers; good dev audience. [19] |
+| Roo Code | IDE extension | Yes | Yes | Global `mcp_settings.json`; project `.roo/mcp.json` | Yes | Supports STDIO, Streamable HTTP, SSE; Cline ecosystem. [20] |
+| Continue | IDE extension / CLI | Yes | Yes | `.continue/mcpServers/*.yaml` or `.../mcp.json` | Yes | Agent-mode only; `stdio`, `sse`, `streamable-http`. [21] |
+| LM Studio | Desktop app | Yes | Yes | `mcp.json` | No | Strong local-LLM audience; local and remote MCP since 0.3.17. [22] |
+| Open WebUI | Web | No | Yes | Admin Settings → External Tools | Yes | Native MCP is Streamable HTTP only; admin-only; stdio needs a proxy. [23] |
+| LibreChat | Web | Yes | Yes | `librechat.yaml` | Yes | `stdio`, `websocket`, `streamable-http`, `sse`; restart after config change. [24] |
+| OpenCode | CLI / TUI | Yes | Yes | `opencode.json` / `opencode.jsonc` | Yes | Local and remote MCP under `mcp`; OAuth for remote servers. [25] |
+
+## Sources
+
+Covering both the README top-10 table and the tables above.
+
+1. https://developers.openai.com/api/docs/guides/developer-mode — ChatGPT Developer mode
+2. https://modelcontextprotocol.io/docs/develop/connect-local-servers — Connect to local MCP servers
+3. https://code.claude.com/docs/en/mcp — Connect Claude Code to tools via MCP
+4. https://developers.openai.com/codex/mcp — Model Context Protocol – Codex
+5. https://code.visualstudio.com/docs/copilot/customization/mcp-servers — Add and manage MCP servers in VS Code
+6. https://cursor.com/docs/mcp.md — Cursor MCP docs
+7. https://docs.windsurf.com/windsurf/cascade/mcp — Cascade MCP Integration
+8. https://geminicli.com/docs/tools/mcp-server/ — MCP servers with Gemini CLI
+9. https://www.jetbrains.com/help/ai-assistant/mcp.html — Model Context Protocol (MCP) | AI Assistant
+10. https://docs.cline.bot/mcp/mcp-overview — Cline MCP
+11. https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers — Adding MCP servers for GitHub Copilot CLI
+12. https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers — Use MCP Servers to Extend GitHub Copilot (Visual Studio)
+13. https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt — Developer mode and MCP apps in ChatGPT
+14. https://docs.mistral.ai/vibe/overview — Vibe | Mistral Docs
+15. https://docs.mistral.ai/vibe/code/cli/mcp-servers — MCP servers | Mistral Docs
+16. https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp — MCP | Hermes Agent
+17. https://codelabs.developers.google.com/getting-started-google-antigravity — Getting Started with Google Antigravity
+18. https://docs.openclaw.ai/cli/mcp — MCP - OpenClaw
+19. https://zed.dev/docs/assistant/model-context-protocol — Model Context Protocol (MCP) in Zed
+20. https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo — Using MCP in Roo Code
+21. https://docs.continue.dev/customize/deep-dives/mcp — Set Up MCP in Continue
+22. https://lmstudio.ai/docs/app/mcp — Use MCP Servers (LM Studio)
+23. https://docs.openwebui.com/features/extensibility/mcp/ — MCP | Open WebUI
+24. https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers — MCP Servers (LibreChat)
+25. https://opencode.ai/docs/mcp-servers/ — MCP servers | OpenCode