@blurt-blockchain/blurt-mcp-server 0.4.0

package/README.md

@@ -0,0 +1,117 @@
+# blurt-mcp-server
+
+[![pipeline status](https://gitlab.com/blurt-blockchain/blurt-mcp-server/badges/main/pipeline.svg)](https://gitlab.com/blurt-blockchain/blurt-mcp-server/-/pipelines)
+[![license: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
+[![node >= 18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](docs/usage.md#requirements)
+
+**Talk to the [Blurt blockchain](https://blurt.blog) from any AI.**
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets Claude, ChatGPT,
+Grok, Mistral, Cursor and other MCP-capable assistants read Blurt in plain language — accounts, posts,
+communities, curation, witnesses and the BLURT market price. Built on
+[`@beblurt/dblurt`](https://www.npmjs.com/package/@beblurt/dblurt). **Read-only by default** — no
+private keys, no broadcasting.
+
+> 🟢 **Try it in 30 seconds — nothing to install.** A public hosted instance is live at
+> **`https://mcp.blurt-blockchain.com/mcp`**. Add it as a connector in your AI app
+> (see [Quick start](#quick-start)). Clone the repo only to self-host or contribute.
+
+## What you can ask
+
+You never name a tool — just ask, and the AI picks and chains them:
+
+- *"What is Blurt's market cap and how many BLURT are in circulation?"*
+- *"Give me a deep analysis of the account `nalexadre`: profile, vote value in USD, who follows them."*
+- *"Find a community about cats and show me its details."*
+- *"List the top 10 Blurt witnesses and flag any that look inactive or behind on version."*
+- *"Who are the biggest curators on this post, and how much is each of their upvotes worth?"*
+
+→ More examples and the full **25-tool** reference: **[docs/tools.md](docs/tools.md)**.
+
+## What it can do
+
+| Area | Tools |
+| --- | --- |
+| 👤 **Accounts & wallets** | profiles, balances, Blurt Power, operation history, rewards, pending rewards, relationships, delegations, `compare-accounts`, account lookup |
+| ✍️ **Content** | a post or its full discussion, an account's posts, trending/ranked publications |
+| 🌐 **Communities** | discovery, details, an account's subscriptions |
+| 🌱 **Onboarding** | an account's referrals (accounts it brought to Blurt) and their count |
+| 🏅 **Curation** | a post's voters & rebloggers, an upvote's value in BLURT & USD |
+| 🔔 **Notifications** | an account's notifications feed + unread count |
+| 🏛️ **Governance** | witness ranking + health, an account's witness votes |
+| 💰 **Market & network** | BLURT price, market cap, chain status |
+| 🔎 **search / fetch** | connector-style discovery of any Blurt resource |
+| ✍️ **Write** *(opt-in, local by default)* | claim, vote, comment, post, follow, mute, reblog, subscribe, read notifications — signed locally; HTTP signing requires an explicit unsafe trusted-deployment override ([details](docs/write-operations.md)) |
+
+## Quick start
+
+**1 — Hosted, native connector (Claude, ChatGPT, Grok, Mistral, …):** add a custom/remote connector
+and paste `https://mcp.blurt-blockchain.com/mcp`.
+
+**2 — Desktop app via a JSON config (e.g. Claude Desktop):** bridge with `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "blurt": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.blurt-blockchain.com/mcp"] }
+  }
+}
+```
+
+**3 — Fully local (stdio):** run the official package bin:
+
+```bash
+npx -y -p @blurt-blockchain/blurt-mcp-server blurt-mcp-stdio
+```
+
+→ Full install, configuration, package and per-client guide: **[docs/usage.md](docs/usage.md)** and
+**[docs/install-snippets.md](docs/install-snippets.md)**.
+
+## Compatible clients
+
+The 10 most relevant MCP clients. **Remote (HTTP)** clients use the hosted endpoint directly;
+stdio-only clients can bridge with `mcp-remote` or run the local stdio build.
+
+| Client | Type | Local (stdio) | Remote (HTTP) | Config file | Open source |
+| --- | --- | ---: | ---: | --- | ---: |
+| ChatGPT web — Apps / Connectors | Web | No | Yes | UI only | No |
+| Claude Desktop | Desktop | Yes | Yes | `claude_desktop_config.json` | No |
+| Claude Code | CLI | Yes | Yes | `~/.claude.json`, `.mcp.json` | No |
+| OpenAI Codex (CLI / IDE) | CLI / IDE | Yes | Yes | `~/.codex/config.toml` | Yes |
+| VS Code — Copilot agent | IDE | Yes | Yes | `.vscode/mcp.json` | Partial |
+| Cursor | IDE | Yes | Yes | `.cursor/mcp.json` | No |
+| Windsurf / Cascade | IDE | Yes | Yes | `mcp_config.json` | No |
+| Gemini CLI | CLI | Yes | Yes | `~/.gemini/settings.json` | Yes |
+| JetBrains AI Assistant | IDE | Yes | Yes | Settings UI | No |
+| Cline | IDE ext. / CLI | Yes | Yes | `~/.cline/mcp.json` | Yes |
+
+→ Full config paths, more clients (Copilot CLI, Mistral Vibe, Hermes, Antigravity, Zed, LM Studio,
+LibreChat, …) and sources: **[docs/clients.md](docs/clients.md)**. *(Community-maintained; as of 2026-06-28.)*
+
+## Documentation
+
+- [Tools & resources](docs/tools.md) — the full tool reference and example prompts
+- [Installation & usage](docs/usage.md) — requirements, configuration, running, connecting clients
+- [Install snippets](docs/install-snippets.md) — copy-paste hosted, package, stdio and client configs
+- [Write operations](docs/write-operations.md) — opt-in local signing (claim, vote, comment, post, follow, …)
+- [Compatible clients](docs/clients.md) — the full compatibility matrix
+- [Architecture](docs/architecture.md) — how it works and the project layout
+- [Deployment](docs/deployment.md) — HTTP deployment and reverse-proxy guidance
+- [Operations](docs/operations.md) — public endpoint operations notes
+- [Cache policy](docs/cache-policy.md) · [Load checks](docs/load-testing.md)
+- [ADR 0001](docs/adr/0001-neutral-infrastructure.md) — neutrality principle for the official server
+- [Development](docs/development.md) — testing and releasing
+- [Release/provenance notes](docs/release-provenance.md) — package validation and publish constraints
+- [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md)
+
+## Security
+
+The server is **read-only** by default and holds **no private keys**. Optional write tools are
+**opt-in and local (stdio) by default**, use a **posting key only** (which cannot move funds), and are
+not exposed over HTTP unless an operator deliberately enables the unsafe trusted-deployment override.
+New write deployments should start with a semantic capability profile such as `BLURT_WRITE_PROFILE=curator`.
+See **[SECURITY.md](SECURITY.md)** and **[write operations](docs/write-operations.md)**.
+
+## License
+
+[GPL-3.0-or-later](LICENSE) © nalexadre — Blurt blockchain

package/SECURITY.md

@@ -0,0 +1,107 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately via a
+[GitLab issue](https://gitlab.com/blurt-blockchain/blurt-mcp-server/-/issues) marked confidential,
+or by contacting the maintainer (`@nalexadre` on Blurt). Please do not disclose publicly until a fix
+is available.
+
+## Security model
+
+This connector is **read-only by default**. The public HTTP server reads public Blurt blockchain data and serves it over MCP. It holds **no private keys**, performs **no signing**, and can **not** post, vote, transfer, or otherwise modify on-chain state.
+
+Optional write tools exist for the local stdio server when the user explicitly configures a posting key. HTTP stays read-only by default and refuses to start if a posting key is present. An intentionally dangerous override exists for experienced operators of private, authenticated deployments, but it is disabled by default and must never be used for the public hosted endpoint. As long as the HTTP deployment remains read-only, its attack surface is limited to availability/abuse and to the correctness of the data returned.
+
+## Deployment hardening (HTTP)
+
+The HTTP endpoint (`POST /mcp`) has **no built-in authentication** and runs in stateless mode.
+
+- **Run it behind a reverse proxy** (nginx, Caddy, Traefik, …). The proxy should terminate **TLS**
+  and handle **rate limiting** and **`Host`/origin filtering** (this also covers DNS-rebinding
+  concerns). The application assumes a trusted proxy in front of it. See [deployment guidance](docs/deployment.md).
+- Keep the request body limit small (MCP requests are tiny; large payloads are responses, not
+  requests).
+- The public hosted endpoint intentionally remains anonymous and **read-only**. OAuth is deferred until user-specific capabilities, quotas, preferences or private resources become real requirements.
+
+## Private keys & write operations
+
+The connector exposes a set of opt-in write tools — claim rewards, upvote, comment, post, follow, mute,
+subscribe to a community, reblog, and mark notifications read — each signed locally. Because this
+introduces a private key into the system, the following principles are **mandatory** and define how
+every write tool is built.
+
+### 1. Least privilege — posting key only
+
+Only a Blurt **posting key** is ever used. The posting key authorizes social operations
+(`vote`, `comment`, `claim_reward_balance`, and posting `custom_json` such as follow / community /
+reblog / notify) but **cannot move funds** (transfers require the `active` key). Active and owner keys are **never** accepted; on startup the server verifies the key has
+**posting authority** over the account — either its own posting key, or a **delegated** posting
+authority (an account granted access via `account_auths`) — and refuses otherwise. Delegation is the
+recommended setup: it can be revoked in one operation without rotating your key (see
+[docs/write-operations.md](docs/write-operations.md)).
+
+### 2. Write is stdio-only by default; HTTP signing requires an unsafe override
+
+Write/signing tools are **only** registered on the local **stdio** server by default, and **only** when a valid key is present. The normal HTTP instance is public and unauthenticated; if a key is detected while running over HTTP, the server **refuses to start**.
+
+Experienced operators may override this guard only for private, trusted, access-controlled deployments by setting the intentionally alarming environment variable below to the exact value shown:
+
+```bash
+BLURT_UNSAFE_ALLOW_HTTP_SIGNING_WITH_POSTING_KEY=I_ACCEPT_FULL_RESPONSIBILITY_FOR_EXPOSING_BLURT_WRITE_TOOLS_OVER_HTTP
+```
+
+This opt-in is disabled by default. Any other value is ignored and startup still fails. When enabled, startup prints a large warning to `stderr`. The operator is solely responsible for authentication, network isolation, reverse-proxy configuration, client behavior, monitoring and every on-chain operation signed by the process. **Do not use this mode for the public hosted endpoint or any unauthenticated LAN/WAN service.** This override does not relax posting-key-only validation, owner/active-key refusal, write-tool gating, or rate caps.
+
+### 3. Human-in-the-loop at the signing layer
+
+The human approval that gates a write happens **in the AI client app** (it prompts before sending a
+tool call) — but this is a **client feature, not guaranteed by MCP**: some agent runners execute
+tools autonomously. Therefore the connector does **not** rely on the client alone:
+
+- **Server-side defense-in-depth**: semantic capability profiles (`BLURT_WRITE_PROFILE`, recommended
+  for new deployments), the backward-compatible denylist (`BLURT_WRITE_TOOLS_BANNED`, which removes
+  specific write tools so they are never registered), the neutral preview-first default
+  (`BLURT_DRY_RUN_DEFAULT=true`, which changes omitted `dry_run` parameters without restricting what
+  users may do), and **rate caps** (per-tool, per-window limits) that do not depend on the client.
+  The official server intentionally does not enforce content/account/community policy files; see
+  [ADR 0001](docs/adr/0001-neutral-infrastructure.md).
+- **Client-agnostic human gate (target)**: delegate signing to an external keystore/wallet that
+  prompts the human for each signature — **WhaleVault** (browser flows) or, ideally, Blurt's
+  roadmapped **SSM Wallet** (incl. headless server mode). The connector sends an **unsigned**
+  operation and receives a **signed** transaction, **never touching the key**.
+
+### 4. Compartmentalized, validated tools
+
+Each operation is its own tool (`blurt-vote`, `blurt-comment`, `blurt-post`, `blurt-claim-rewards`),
+not a single multi-purpose `broadcast` tool — so each has a tight, validated schema and a clear name
+in the client's approval dialog. Parameters are **never auto-derived from fetched on-chain content**:
+all content read from the chain is treated as **data, never instructions** (indirect prompt-injection
+defense).
+
+### 5. Key handling
+
+- The key never appears in the repository. Prefer keeping it in a file **outside** the repo and
+  pointing the stdio launcher at it with `BLURT_ENV_FILE` (so the launcher config holds no secret and
+  the key is not in the working tree). The launcher's own `env` block, or a secrets mechanism, are
+  also acceptable; the project `.env` is not (the HTTP server refuses to start when a key is present).
+- On a desktop, an **OS keychain** may be used. On a **headless server**, prefer **systemd
+  credentials** (`LoadCredential` / `systemd-creds`, encrypted at rest) or a **secrets manager**
+  (Vault, cloud KMS); a `chmod 600` env file owned by the service user is the minimum baseline.
+- The key flows **only** into dblurt's local signing function — **never** to the network (only the
+  signed transaction is broadcast), **never** to logs, error messages, or any other dependency.
+
+### 6. Logging
+
+Logs go to `stderr`. The signing path must **never** log the key or a raw signed transaction. Run
+production with `LOG_LEVEL=info` (not `debug`). A test asserts the signing tool does not emit the key.
+
+## Supply chain
+
+The signing path runs in the same process as its dependencies (dblurt, the SDK, the node checker), so
+dependency trust matters once a key is present:
+
+- A committed lockfile pins the dependency tree; `npm audit` runs in CI.
+- Updates to libraries on the signing path (especially `@beblurt/dblurt`) are reviewed before
+  merging.
+- The write path keeps its dependencies minimal.

package/dist/app.js

@@ -0,0 +1,88 @@
+// Logger — log level is read from process.env.LOG_LEVEL inside the logger itself.
+import logger from "./utils/logger.js";
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildServer } from "./buildServer.js";
+import pkg from "../package.json" with { type: "json" };
+import { getBlurtClient, rpcReadiness } from "./utils/rpc.js";
+/**
+ * Build the Express app exposing the MCP server over a stateless Streamable HTTP
+ * transport. Exported (without side effects like `listen`) so tests can run the
+ * exact production request path against an ephemeral port.
+ */
+export function createApp(options = {}) {
+    const app = express();
+    // MCP requests are small JSON-RPC payloads; cap the body to avoid memory abuse.
+    // (Large data is in responses, which this limit does not affect.)
+    app.use(express.json({ limit: "256kb" }));
+    const requestLogger = options.requestLogger ?? ((message) => logger.info(message));
+    app.use((req, res, next) => {
+        const started = process.hrtime.bigint();
+        res.on("finish", () => {
+            const durationMs = Number((process.hrtime.bigint() - started) / 1000000n);
+            requestLogger(`http_request method=${req.method} path=${req.path} status=${res.statusCode} duration_ms=${durationMs}`);
+        });
+        next();
+    });
+    app.get("/healthz", (_req, res) => {
+        res.status(200).json({
+            status: "ok",
+            service: "blurt-mcp-server",
+            version: pkg.version || "0.0.0",
+            time: new Date().toISOString(),
+        });
+    });
+    app.get("/readyz", (_req, res) => {
+        const rpc = rpcReadiness();
+        const ready = rpc.configured_nodes > 0 && rpc.active_nodes > 0;
+        res.status(ready ? 200 : 503).json({
+            status: ready ? "ready" : "not_ready",
+            service: "blurt-mcp-server",
+            version: pkg.version || "0.0.0",
+            time: new Date().toISOString(),
+            rpc,
+        });
+    });
+    app.post("/mcp", async (req, res) => {
+        try {
+            // Shared client, repointed at the healthiest RPC nodes by the node checker.
+            const server = buildServer(getBlurtClient(), { write: options.write });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // or custom for logs
+            });
+            res.on("close", () => {
+                logger.debug("Closing MCP transport/session");
+                transport.close();
+                server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            logger.error("MCP error: " + err.stack);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // GET and DELETE → not supported in stateless mode
+    app.get("/mcp", (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed." },
+            id: null,
+        });
+    });
+    app.delete("/mcp", (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed." },
+            id: null,
+        });
+    });
+    return app;
+}

package/dist/buildServer.js

@@ -0,0 +1,146 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import logger from "./utils/logger.js";
+import pkg from "../package.json" with { type: "json" };
+// Tools
+import { registerGetAccount } from "./tools/getAccount.js";
+import { registerGetAccountHistory } from "./tools/getAccountHistory.js";
+import { registerGetAccountPosts } from "./tools/getAccountPosts.js";
+import { registerGetPost } from "./tools/getPost.js";
+import { registerGetPublications } from "./tools/getPublications.js";
+import { registerSearchTool } from "./tools/search.js";
+import { registerFetchTool } from "./tools/fetch.js";
+// Network / investor
+import { registerGetBlurtPrice } from "./tools/getBlurtPrice.js";
+import { registerGetChainStatus } from "./tools/getChainStatus.js";
+// Social
+import { registerListCommunities } from "./tools/listCommunities.js";
+import { registerGetCommunity } from "./tools/getCommunity.js";
+// Curation
+import { registerGetPostVotes } from "./tools/getPostVotes.js";
+import { registerGetVoteValue } from "./tools/getVoteValue.js";
+// Governance
+import { registerListWitnesses } from "./tools/listWitnesses.js";
+import { registerGetWitness } from "./tools/getWitness.js";
+import { registerGetAccountWitnessVotes } from "./tools/getAccountWitnessVotes.js";
+// Account depth / social
+import { registerGetAccountRelationships } from "./tools/getAccountRelationships.js";
+import { registerGetPendingRewards } from "./tools/getPendingRewards.js";
+import { registerGetAccountSubscriptions } from "./tools/getAccountSubscriptions.js";
+import { registerCompareAccounts } from "./tools/compareAccounts.js";
+import { registerGetReferrals } from "./tools/getReferrals.js";
+import { registerGetAccountNotifications } from "./tools/getAccountNotifications.js";
+import { registerGetPostReblogs } from "./tools/getPostReblogs.js";
+import { registerGetDelegations } from "./tools/getDelegations.js";
+import { registerLookupAccounts } from "./tools/lookupAccounts.js";
+// Write (signing) — registered only when a write context is provided
+import { registerClaimRewards } from "./tools/claimRewards.js";
+import { registerUpvote } from "./tools/upvote.js";
+import { registerComment } from "./tools/comment.js";
+import { registerFollow } from "./tools/follow.js";
+import { registerMute } from "./tools/mute.js";
+import { registerSubscribeCommunity } from "./tools/subscribeCommunity.js";
+import { registerReadNotifications } from "./tools/readNotifications.js";
+import { registerReblog } from "./tools/reblog.js";
+import { registerPost } from "./tools/post.js";
+// Resources
+import { registerBlurtResources } from "./resources/blurtResource.js";
+/**
+ * Build a fully-wired MCP server (read-only tools + resources, plus write tools
+ * when `options.write` is present) bound to the given Blurt client.
+ */
+export function buildServer(client, options = {}) {
+    const server = new McpServer({
+        name: pkg.name || "blurt-mcp-server",
+        version: pkg.version || "0.1.0",
+    });
+    logger.info("Registering tools and resources...");
+    // Tools
+    registerGetAccount(server, client);
+    registerGetAccountHistory(server, client);
+    registerGetAccountPosts(server, client);
+    registerGetPost(server, client);
+    registerGetPublications(server, client);
+    // Network / investor
+    registerGetBlurtPrice(server);
+    registerGetChainStatus(server, client);
+    // Social (communities)
+    registerListCommunities(server, client);
+    registerGetCommunity(server, client);
+    // Curation
+    registerGetPostVotes(server, client);
+    registerGetVoteValue(server, client);
+    // Governance
+    registerListWitnesses(server, client);
+    registerGetWitness(server, client);
+    registerGetAccountWitnessVotes(server, client);
+    // Account depth / social
+    registerGetAccountRelationships(server, client);
+    registerGetPendingRewards(server, client);
+    registerGetAccountSubscriptions(server, client);
+    registerCompareAccounts(server, client);
+    registerGetReferrals(server, client);
+    registerGetAccountNotifications(server, client);
+    registerGetPostReblogs(server, client);
+    registerGetDelegations(server, client);
+    registerLookupAccounts(server, client);
+    // Search/fetch + resources
+    registerSearchTool(server);
+    registerFetchTool(server, client);
+    registerBlurtResources(server, client);
+    // Write tools — only when a validated posting key is present (stdio only).
+    if (options.write) {
+        const { enabledTools } = options.write;
+        if (enabledTools.has("claim-rewards"))
+            registerClaimRewards(server, client, options.write);
+        if (enabledTools.has("upvote"))
+            registerUpvote(server, client, options.write);
+        if (enabledTools.has("comment"))
+            registerComment(server, client, options.write);
+        if (enabledTools.has("follow"))
+            registerFollow(server, client, options.write);
+        if (enabledTools.has("mute"))
+            registerMute(server, client, options.write);
+        if (enabledTools.has("subscribe-community"))
+            registerSubscribeCommunity(server, client, options.write);
+        if (enabledTools.has("read-notifications"))
+            registerReadNotifications(server, client, options.write);
+        if (enabledTools.has("reblog"))
+            registerReblog(server, client, options.write);
+        if (enabledTools.has("post"))
+            registerPost(server, client, options.write);
+        logger.info(`Write tools enabled: ${[...enabledTools].join(", ") || "(none)"}`);
+    }
+    return server;
+}
+/**
+ * Options for the Blurt RPC client.
+ *
+ * `rpcTransport: "core"` is required: the default "legacy" transport aborts each
+ * attempt after (tries+1)*500ms and then crashes on the resulting abort error
+ * (`error.code.includes is not a function`) when a request is slow, which makes
+ * every RPC call fail under the Streamable HTTP server context.
+ */
+export const BLURT_CLIENT_OPTIONS = {
+    timeout: 4000,
+    failoverThreshold: 3,
+    rpcTransport: "core",
+};
+/**
+ * Optional non-mainnet (testnet) override. When `BLURT_CHAIN_ID` and
+ * `BLURT_ADDRESS_PREFIX` are set, they are passed to the dblurt client to target
+ * that chain. When unset, this returns `{}` and dblurt's mainnet defaults apply
+ * (chain id `cd8d90…`, address prefix `BLT`) — nothing to configure for mainnet.
+ *
+ * A testnet needs **both** values; if only one is set the other falls back to the
+ * mainnet default (see the warning logged in utils/rpc.ts).
+ */
+export function networkOptions() {
+    const chainId = process.env.BLURT_CHAIN_ID?.trim();
+    const addressPrefix = process.env.BLURT_ADDRESS_PREFIX?.trim();
+    return {
+        ...(chainId ? { chainId } : {}),
+        ...(addressPrefix ? { addressPrefix } : {}),
+    };
+}
+// The shared client and its RPC node selection live in ./utils/rpc.ts
+// (getBlurtClient / startNodeChecker), which scores nodes via blurt-nodes-checker.

package/dist/contracts/registerBlurtTool.js

@@ -0,0 +1,53 @@
+import { TOOL_REGISTRY, TOOL_RESULT_CONTRACT, TOOL_RESULT_OUTPUT_SCHEMA, toolSources, ttlSeconds, } from "./toolRegistry.js";
+export function buildToolResultMeta(name) {
+    const metadata = TOOL_REGISTRY[name];
+    return {
+        contract: TOOL_RESULT_CONTRACT,
+        tool: name,
+        sources: metadata ? toolSources(metadata) : ["mcp"],
+        retrieved_at: new Date().toISOString(),
+        freshness: {
+            cache: metadata?.cache ?? "none",
+            ttl_seconds: metadata ? ttlSeconds(metadata.cache) : null,
+        },
+        confidence: "high",
+        caveats: metadata && "caveats" in metadata && metadata.caveats ? [...metadata.caveats] : [],
+    };
+}
+function parseTextContent(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function inferData(result) {
+    const content = result.content ?? [];
+    if (content.length === 1 && content[0]?.type === "text") {
+        return parseTextContent(content[0].text ?? "");
+    }
+    return content;
+}
+export function withStandardStructuredContent(name, result) {
+    if (result.isError || result.structuredContent)
+        return result;
+    const structured = {
+        data: inferData(result),
+        meta: buildToolResultMeta(name),
+    };
+    return { ...result, structuredContent: structured };
+}
+export function registerBlurtTool(server, name, config, callback) {
+    const metadata = TOOL_REGISTRY[name];
+    const mergedConfig = {
+        ...config,
+        title: config.title ?? metadata.title,
+        description: config.description ?? metadata.description,
+        outputSchema: config.outputSchema ?? TOOL_RESULT_OUTPUT_SCHEMA,
+    };
+    return server.registerTool(name, mergedConfig, async (args, extra) => {
+        const result = await callback(args, extra);
+        return withStandardStructuredContent(name, result);
+    });
+}