shieldapi-mcp 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# ShieldAPI MCP Server
+
+Security intelligence tools for AI agents — check URLs, domains, IPs, emails, and passwords for threats. Pay-per-request with USDC micropayments via [x402](https://www.x402.org/), or use free demo mode.
+
+## Quick Start
+
+```bash
+npx shieldapi-mcp
+```
+
+That's it. Without a wallet configured, it runs in **demo mode** (free sample data).
+
+## Setup for Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "shieldapi": {
+      "command": "npx",
+      "args": ["-y", "shieldapi-mcp"],
+      "env": {
+        "SHIELDAPI_WALLET_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Setup for Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shieldapi": {
+      "command": "npx",
+      "args": ["-y", "shieldapi-mcp"],
+      "env": {
+        "SHIELDAPI_WALLET_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description | Price |
+|------|-------------|-------|
+| `check_url` | Check URL for malware, phishing (URLhaus + heuristics) | $0.003 |
+| `check_password` | Check SHA-1 hash against HIBP breach database | $0.001 |
+| `check_password_range` | HIBP k-Anonymity prefix lookup | $0.001 |
+| `check_domain` | Domain reputation (DNS, blacklists, SPF/DMARC, SSL) | $0.003 |
+| `check_ip` | IP reputation (blacklists, Tor exit, reverse DNS) | $0.002 |
+| `check_email` | Email breach lookup via HIBP | $0.005 |
+| `full_scan` | All checks combined on a single target | $0.01 |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHIELDAPI_URL` | `https://shield.vainplex.dev` | API base URL |
+| `SHIELDAPI_WALLET_PRIVATE_KEY` | *(none)* | EVM private key for USDC payments. If not set, uses free demo mode. |
+| `SHIELDAPI_NETWORK` | `base` | Network for payments (Base mainnet) |
+
+## Demo Mode
+
+Without `SHIELDAPI_WALLET_PRIVATE_KEY`, all tools return sample data for free. Great for testing your agent integration before configuring payments.
+
+## How Payments Work
+
+ShieldAPI uses [x402](https://www.x402.org/) — an open standard for HTTP-native micropayments:
+
+1. Your agent calls a tool (e.g. `check_url`)
+2. ShieldAPI responds with HTTP 402 + payment details
+3. The MCP server automatically pays with USDC on Base
+4. ShieldAPI returns the security data
+
+You need USDC on Base in your wallet. Typical cost: $0.001–$0.01 per request.
+
+## License
+
+MIT
+
+## Links
+
+- **API**: https://shield.vainplex.dev
+- **Docs**: https://shield.vainplex.dev/api/health
+- **Source**: https://github.com/alberthild/shieldapi-mcp

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * ShieldAPI MCP Server
+ *
+ * Exposes ShieldAPI security intelligence as native MCP tools.
+ * Handles x402 USDC micropayments automatically, with demo fallback.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const { SHIELDAPI_URL = 'https://shield.vainplex.dev', SHIELDAPI_WALLET_PRIVATE_KEY, SHIELDAPI_NETWORK = 'base', } = process.env;
+const demoMode = !SHIELDAPI_WALLET_PRIVATE_KEY;
+// --- x402 payment setup (lazy, only if wallet configured) ---
+let paymentFetch = fetch;
+async function initPaymentFetch() {
+    if (demoMode)
+        return;
+    const { wrapFetchWithPayment, x402Client } = await import('@x402/fetch');
+    const { ExactEvmScheme, toClientEvmSigner } = await import('@x402/evm');
+    const { createWalletClient, http, publicActions } = await import('viem');
+    const { privateKeyToAccount } = await import('viem/accounts');
+    const { base } = await import('viem/chains');
+    const account = privateKeyToAccount(SHIELDAPI_WALLET_PRIVATE_KEY);
+    const walletClient = createWalletClient({
+        account,
+        chain: base,
+        transport: http(),
+    }).extend(publicActions);
+    // Type assertion needed: viem walletClient.extend(publicActions) is structurally compatible
+    // but TypeScript can't prove it due to complex generic types in viem + @x402/evm
+    const signer = toClientEvmSigner(walletClient);
+    const client = new x402Client().register(`eip155:${base.id}`, new ExactEvmScheme(signer));
+    paymentFetch = wrapFetchWithPayment(fetch, client);
+}
+// --- API caller ---
+async function callShieldApi(endpoint, params) {
+    const url = new URL(`${SHIELDAPI_URL}/api/${endpoint}`);
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    if (demoMode) {
+        url.searchParams.set('demo', 'true');
+    }
+    const response = await paymentFetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`ShieldAPI ${endpoint} failed (${response.status}): ${body}`);
+    }
+    return response.json();
+}
+function formatResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: 'ShieldAPI',
+    version: '1.0.0',
+});
+// Tools
+server.tool('check_url', 'Check a URL for malware, phishing, and other threats. Uses URLhaus + heuristic analysis.', { url: z.string().describe('The URL to check (e.g. https://example.com)') }, async ({ url }) => formatResult(await callShieldApi('check-url', { url })));
+server.tool('check_password', 'Check if a password hash (SHA-1) has been exposed in known data breaches via HIBP.', { hash: z.string().describe('SHA-1 hash of the password (40 hex chars)') }, async ({ hash }) => formatResult(await callShieldApi('check-password', { hash })));
+server.tool('check_password_range', 'Look up a SHA-1 hash prefix in the HIBP k-Anonymity database.', { prefix: z.string().describe('First 5 characters of the SHA-1 password hash') }, async ({ prefix }) => formatResult(await callShieldApi('check-password-range', { prefix })));
+server.tool('check_domain', 'Check domain reputation: DNS records, blacklists (Spamhaus, SpamCop, SORBS), SPF/DMARC, SSL.', { domain: z.string().describe('Domain name to check (e.g. example.com)') }, async ({ domain }) => formatResult(await callShieldApi('check-domain', { domain })));
+server.tool('check_ip', 'Check IP reputation: blacklists, Tor exit node detection, reverse DNS.', { ip: z.string().describe('IPv4 address to check (e.g. 8.8.8.8)') }, async ({ ip }) => formatResult(await callShieldApi('check-ip', { ip })));
+server.tool('check_email', 'Check if an email address has been exposed in known data breaches via HIBP.', { email: z.string().describe('Email address to check') }, async ({ email }) => formatResult(await callShieldApi('check-email', { email })));
+server.tool('full_scan', 'Run all security checks on a target (URL, domain, IP, or email). Most comprehensive scan.', { target: z.string().describe('Target to scan — URL, domain, IP address, or email') }, async ({ target }) => formatResult(await callShieldApi('full-scan', { target })));
+// --- Start ---
+async function main() {
+    await initPaymentFetch();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`ShieldAPI MCP server running (${demoMode ? 'DEMO mode' : 'PAID mode'})`);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "shieldapi-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ShieldAPI",
+  "main": "dist/index.js",
+  "bin": {
+    "shieldapi-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "shieldapi",
+    "x402"
+  ],
+  "author": "Vainplex (https://vainplex.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alberthild/shieldapi-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "@x402/core": "2.5.0",
+    "@x402/evm": "2.5.0",
+    "@x402/fetch": "2.5.0",
+    "viem": "^2.17.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  },
+  "type": "module"
+}

package/src/index.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * ShieldAPI MCP Server
+ * 
+ * Exposes ShieldAPI security intelligence as native MCP tools.
+ * Handles x402 USDC micropayments automatically, with demo fallback.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const {
+  SHIELDAPI_URL = 'https://shield.vainplex.dev',
+  SHIELDAPI_WALLET_PRIVATE_KEY,
+  SHIELDAPI_NETWORK = 'base',
+} = process.env;
+
+const demoMode = !SHIELDAPI_WALLET_PRIVATE_KEY;
+
+// --- x402 payment setup (lazy, only if wallet configured) ---
+
+let paymentFetch: typeof fetch = fetch;
+
+async function initPaymentFetch(): Promise<void> {
+  if (demoMode) return;
+  
+  const { wrapFetchWithPayment, x402Client } = await import('@x402/fetch');
+  const { ExactEvmScheme, toClientEvmSigner } = await import('@x402/evm');
+  const { createWalletClient, http, publicActions } = await import('viem');
+  const { privateKeyToAccount } = await import('viem/accounts');
+  const { base } = await import('viem/chains');
+
+  const account = privateKeyToAccount(SHIELDAPI_WALLET_PRIVATE_KEY as `0x${string}`);
+  const walletClient = createWalletClient({
+    account,
+    chain: base,
+    transport: http(),
+  }).extend(publicActions);
+
+  // Type assertion needed: viem walletClient.extend(publicActions) is structurally compatible
+  // but TypeScript can't prove it due to complex generic types in viem + @x402/evm
+  const signer = toClientEvmSigner(walletClient as unknown as Parameters<typeof toClientEvmSigner>[0]);
+  const client = new x402Client().register(
+    `eip155:${base.id}`,
+    new ExactEvmScheme(signer)
+  );
+
+  paymentFetch = wrapFetchWithPayment(fetch, client);
+}
+
+// --- API caller ---
+
+async function callShieldApi(endpoint: string, params: Record<string, string>): Promise<unknown> {
+  const url = new URL(`${SHIELDAPI_URL}/api/${endpoint}`);
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, value);
+  }
+  if (demoMode) {
+    url.searchParams.set('demo', 'true');
+  }
+
+  const response = await paymentFetch(url.toString());
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`ShieldAPI ${endpoint} failed (${response.status}): ${body}`);
+  }
+  return response.json();
+}
+
+function formatResult(data: unknown): { content: Array<{ type: 'text'; text: string }> } {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: 'ShieldAPI',
+  version: '1.0.0',
+});
+
+// Tools
+
+server.tool(
+  'check_url',
+  'Check a URL for malware, phishing, and other threats. Uses URLhaus + heuristic analysis.',
+  { url: z.string().describe('The URL to check (e.g. https://example.com)') },
+  async ({ url }) => formatResult(await callShieldApi('check-url', { url }))
+);
+
+server.tool(
+  'check_password',
+  'Check if a password hash (SHA-1) has been exposed in known data breaches via HIBP.',
+  { hash: z.string().describe('SHA-1 hash of the password (40 hex chars)') },
+  async ({ hash }) => formatResult(await callShieldApi('check-password', { hash }))
+);
+
+server.tool(
+  'check_password_range',
+  'Look up a SHA-1 hash prefix in the HIBP k-Anonymity database.',
+  { prefix: z.string().describe('First 5 characters of the SHA-1 password hash') },
+  async ({ prefix }) => formatResult(await callShieldApi('check-password-range', { prefix }))
+);
+
+server.tool(
+  'check_domain',
+  'Check domain reputation: DNS records, blacklists (Spamhaus, SpamCop, SORBS), SPF/DMARC, SSL.',
+  { domain: z.string().describe('Domain name to check (e.g. example.com)') },
+  async ({ domain }) => formatResult(await callShieldApi('check-domain', { domain }))
+);
+
+server.tool(
+  'check_ip',
+  'Check IP reputation: blacklists, Tor exit node detection, reverse DNS.',
+  { ip: z.string().describe('IPv4 address to check (e.g. 8.8.8.8)') },
+  async ({ ip }) => formatResult(await callShieldApi('check-ip', { ip }))
+);
+
+server.tool(
+  'check_email',
+  'Check if an email address has been exposed in known data breaches via HIBP.',
+  { email: z.string().describe('Email address to check') },
+  async ({ email }) => formatResult(await callShieldApi('check-email', { email }))
+);
+
+server.tool(
+  'full_scan',
+  'Run all security checks on a target (URL, domain, IP, or email). Most comprehensive scan.',
+  { target: z.string().describe('Target to scan — URL, domain, IP address, or email') },
+  async ({ target }) => formatResult(await callShieldApi('full-scan', { target }))
+);
+
+// --- Start ---
+
+async function main(): Promise<void> {
+  await initPaymentFetch();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`ShieldAPI MCP server running (${demoMode ? 'DEMO mode' : 'PAID mode'})`);
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}