veriql-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veriql
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# veriql-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Crypto wallet and token risk checks as MCP tools, so an agent can ask "is this token safe to buy?" and get an answer with the math attached.
+
+Read-only. It never asks for a private key, a seed phrase or a wallet connection, and it never signs or moves anything. Every signal comes from public on-chain data.
+
+## Install
+
+Claude Desktop (`claude_desktop_config.json`), Claude Code, Cursor, or any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "veriql": {
+      "command": "npx",
+      "args": ["-y", "veriql-mcp"],
+      "env": { "VERIQL_API_KEY": "vq_live_your_key" }
+    }
+  }
+}
+```
+
+Get a free key at [veriql.app/api](https://veriql.app/api). No account, no card.
+
+| env | default | |
+| --- | --- | --- |
+| `VERIQL_API_KEY` | (required) | Free or prepaid key |
+| `VERIQL_BASE_URL` | `https://veriql.app` | Point at another deployment |
+
+## Tools
+
+**`veriql_scan`** (`address`)
+Risky token approvals for a public wallet across Ethereum, BNB Chain, Polygon, Arbitrum and Base. Returns a 0-100 Security Score with itemised drivers, every risky approval, and a best-effort USD value-at-risk.
+
+**`veriql_token`** (`address`, `chainId?`)
+Honeypot, punishing taxes, mintable supply, hidden owner and proxy risks, each as a plain-English flag. EVM chains plus Tron.
+
+**`veriql_launch`** (`address`, `chainId?`)
+A 0-100 launch-safety score with every penalty driver and the full metrics behind it. EVM chains plus Tron plus Solana.
+
+## Why the output is shaped like this
+
+Agents are the worst possible audience for a bare number, because they cannot tell a measurement from a fallback. So:
+
+- **Every score ships its drivers.** You get the penalties and what each one is for, not just the total. The complete scoring methodology, every weight, is published at [veriql.app/llms-full.txt](https://veriql.app/llms-full.txt).
+- **An incomplete check says so.** When a dimension could not be read, the result is marked incomplete and a clean verdict is **withdrawn** rather than reported at a capped number. A partial check that did find danger keeps the finding: incompleteness withdraws a clean verdict and never softens a dirty one.
+- **Absence is never zero.** A value nobody could establish comes back null. It is never substituted from another instrument, because borrowing a number across providers is how a tool reports a collapse that never happened.
+- **Much of it is read from chain, not resold.** Pool reserves (PumpSwap, Orca, Meteora), SPL mint authorities, transfer fees, permanent delegate, LP lock and holder concentration are our own reads, so a vendor outage degrades the answer honestly instead of silently.
+
+## Pay per call, with no account
+
+The same endpoints speak [x402](https://veriql.app/api#x402): call with no key, get a `402` describing exactly what to pay, retry with the payment attached. USDC on Base or Solana, no signup and no human in the loop. Useful when an agent has a wallet but cannot complete a checkout.
+
+## Limits, stated plainly
+
+A verdict is a structural risk assessment, not financial advice and not a prediction. It cannot tell you whether a price will go up. Holder concentration is an upper bound, because the largest token accounts can include AMM pool vaults and exchange wallets. A clean result means no known risks were found, which is not the same as safe.
+
+MIT licensed. Built by the team behind [Veriql](https://veriql.app).

package/dist/core.d.ts

@@ -0,0 +1,25 @@
+export type V1Endpoint = "scan" | "token" | "launch";
+export interface ClientOpts {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ApiResult {
+    ok: boolean;
+    status: number;
+    body: any;
+}
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+    [k: string]: unknown;
+}
+/** Compose {base}/api/v1/{endpoint}?params, trimming a trailing slash and dropping empty params. */
+export declare function buildUrl(baseUrl: string, endpoint: V1Endpoint, params: Record<string, string | undefined>): string;
+/** Call the Veriql Risk API with the configured key. Never throws on HTTP status — returns {ok,status,body}. */
+export declare function callVeriql(endpoint: V1Endpoint, params: Record<string, string | undefined>, o: ClientOpts): Promise<ApiResult>;
+/** Map an API result to an MCP tool result (pretty JSON on success; error flag + message otherwise). */
+export declare function toToolResult(r: ApiResult): ToolResult;

package/dist/core.js

@@ -0,0 +1,26 @@
+// Pure client core for the Veriql MCP server — kept free of the MCP SDK and the
+// network (fetch injected) so it is fully unit-testable. The stdio server
+// (server.ts) is a thin shell that wires these into MCP tools.
+/** Compose {base}/api/v1/{endpoint}?params, trimming a trailing slash and dropping empty params. */
+export function buildUrl(baseUrl, endpoint, params) {
+    const u = new URL(`${baseUrl.replace(/\/+$/, "")}/api/v1/${endpoint}`);
+    for (const [k, v] of Object.entries(params))
+        if (v != null && v !== "")
+            u.searchParams.set(k, v);
+    return u.toString();
+}
+/** Call the Veriql Risk API with the configured key. Never throws on HTTP status — returns {ok,status,body}. */
+export async function callVeriql(endpoint, params, o) {
+    const doFetch = o.fetchImpl ?? fetch;
+    const res = await doFetch(buildUrl(o.baseUrl, endpoint, params), { headers: { "x-api-key": o.apiKey } });
+    const body = await res.json().catch(() => ({}));
+    return { ok: res.ok, status: res.status, body };
+}
+/** Map an API result to an MCP tool result (pretty JSON on success; error flag + message otherwise). */
+export function toToolResult(r) {
+    if (r.ok)
+        return { content: [{ type: "text", text: JSON.stringify(r.body, null, 2) }] };
+    const msg = r.body?.error?.message || `Request failed (HTTP ${r.status}).`;
+    return { content: [{ type: "text", text: `Error ${r.status}: ${msg}` }], isError: true };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../src/mcp/core.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,0EAA0E;AAC1E,+DAA+D;AAsB/D,oGAAoG;AACpG,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,QAAoB,EAAE,MAA0C;IACxG,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,QAAQ,EAAE,CAAC,CAAC;IACvE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE;YAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjG,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,gHAAgH;AAChH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAoB,EACpB,MAA0C,EAC1C,CAAa;IAEb,MAAM,OAAO,GAAG,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;IACrC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,YAAY,CAAC,CAAY;IACvC,IAAI,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACxF,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,IAAI,wBAAwB,CAAC,CAAC,MAAM,IAAI,CAAC;IAC3E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3F,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Veriql Risk API — MCP server. Exposes the read-only risk engine as three MCP
+// tools so AI agents / Claude / Cursor can call it directly. A thin shell over
+// src/mcp/core.ts (all logic + tests live there); calls the public HTTP API with
+// the operator's key, so every agent call stays metered by the credits system.
+//
+// Config (env, set in your MCP client): VERIQL_API_KEY (get a free key at
+// https://veriql.app/api), optional VERIQL_BASE_URL (default https://veriql.app).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { callVeriql, toToolResult } from "./core.js";
+const baseUrl = process.env.VERIQL_BASE_URL || "https://veriql.app";
+const apiKey = process.env.VERIQL_API_KEY || "";
+const needKey = () => ({
+    content: [{ type: "text", text: "Set VERIQL_API_KEY to use this tool — get a free key at https://veriql.app/api" }],
+    isError: true,
+});
+const server = new McpServer({ name: "veriql-risk", version: "1.0.0" });
+server.registerTool("veriql_scan", {
+    title: "Veriql wallet scan",
+    description: "Scan a public wallet address for risky token approvals across 5 EVM chains (Ethereum, BNB Chain, Polygon, Arbitrum, Base). Returns a 0–100 Security Score with itemised drivers, every risky approval, and a best-effort USD value-at-risk.",
+    inputSchema: { address: z.string().describe("Public EVM address, 0x…") },
+}, async ({ address }) => (apiKey ? toToolResult(await callVeriql("scan", { address }, { baseUrl, apiKey })) : needKey()));
+server.registerTool("veriql_token", {
+    title: "Veriql token check",
+    description: "Check a token contract for honeypot, punishing taxes, mintable supply, hidden owner and proxy risks — each surfaced as a plain-English flag. EVM chains + Tron.",
+    inputSchema: {
+        address: z.string().describe("Token contract address"),
+        chainId: z.string().optional().describe("Chain id or key (e.g. 1, base, tron); defaults to Ethereum"),
+    },
+}, async ({ address, chainId }) => apiKey ? toToolResult(await callVeriql("token", { address, chainId }, { baseUrl, apiKey })) : needKey());
+server.registerTool("veriql_launch", {
+    title: "Veriql launch-safety score",
+    description: "A transparent 0–100 launch-safety score for a token/mint with itemised penalty drivers and full metrics. EVM chains + Tron + Solana.",
+    inputSchema: {
+        address: z.string().describe("Token contract / mint address"),
+        chainId: z.string().optional().describe("Chain id or key (e.g. 1, base, solana); defaults to Ethereum"),
+    },
+}, async ({ address, chainId }) => apiKey ? toToolResult(await callVeriql("launch", { address, chainId }, { baseUrl, apiKey })) : needKey());
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP channel — log to stderr only.
+    console.error(`veriql-risk MCP ready (base ${baseUrl}, key ${apiKey ? "set" : "MISSING — set VERIQL_API_KEY"})`);
+}
+main().catch((e) => {
+    console.error("veriql mcp fatal:", e);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "veriql-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Veriql Risk API as MCP tools: wallet approval scans, token honeypot/tax checks and a transparent 0-100 launch-safety score, for Claude, Cursor and any MCP agent.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "crypto",
+    "solana",
+    "ethereum",
+    "security",
+    "honeypot",
+    "rug-check",
+    "token-safety",
+    "wallet-security",
+    "web3",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://veriql.app/api",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "veriql-mcp": "dist/server.js"
+  },
+  "main": "dist/core.js",
+  "types": "dist/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}