deepsearch-x402-mcp 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# deepsearch-x402-mcp
+
+MCP server for [DeepSearch Korean Stock Intelligence API](https://x402.deepsearch.com).
+
+Pay-per-query via x402 micropayments — USDC on Base Mainnet. No API key needed.
+
+## Setup
+
+### 1. Get a wallet with USDC
+
+You need an EVM wallet with USDC on **Base Mainnet**.
+- Buy USDC on [Coinbase](https://coinbase.com) and send to Base
+- Or bridge from Ethereum via [bridge.base.org](https://bridge.base.org)
+
+### 2. Add to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "deepsearch-stocks": {
+      "command": "npx",
+      "args": ["deepsearch-x402-mcp"],
+      "env": {
+        "MCP_WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see **13 tools** available.
+
+### 3. Try it
+
+Ask Claude:
+- *"What is Samsung Electronics' current PER and ROE?"*
+- *"Show me SK Hynix stock performance over the last year"*
+- *"Analyze the investment risks for NAVER (035420)"*
+
+## Tools & Pricing
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `get_company` | Fundamentals: market cap, PER, PBR, ROE, financials | $0.01 |
+| `get_financials` | Latest quarterly financial statements | $0.01 |
+| `get_dividend` | Dividend schedule and amounts | $0.01 |
+| `get_news` | Recent 30-day news with sentiment | $0.01 |
+| `get_stock_1m` | 1-month daily price history | $0.01 |
+| `get_stock_3m` | 3-month daily price history | $0.02 |
+| `get_financials_2y` | 2-year quarterly financials | $0.02 |
+| `get_stock_1y` | 1-year daily price history | $0.03 |
+| `get_financials_5y` | 5-year quarterly financials | $0.03 |
+| `get_issue` | News-driven issue analysis | $0.05 |
+| `get_risk` | Investment risk assessment | $0.05 |
+| `get_stock_3y` | 3-year daily price history | $0.05 |
+| `get_financials_all` | All available quarterly data | $0.05 |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MCP_WALLET_PRIVATE_KEY` | ✅ | EVM private key (0x...) — wallet must hold USDC on Base Mainnet |
+| `RESOURCE_SERVER_URL` | ❌ | Override API server URL (default: https://x402.deepsearch.com) |
+
+## Ticker Format
+
+Korean stocks use 6-digit KRX codes:
+- `005930` — Samsung Electronics
+- `000660` — SK Hynix  
+- `035420` — NAVER
+- `005380` — Hyundai Motor
+- `051910` — LG Chem
+
+## Links
+
+- [API Server](https://x402.deepsearch.com)
+- [x402scan listing](https://www.x402scan.com/server/2034f172-ed34-42dd-8aca-df9a0ab35027)
+- [x402 Protocol](https://x402.org)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// ============================================================
+// DeepSearch Korean Stock Intelligence — MCP Server
+//
+// Claude Desktop / Cursor / 기타 MCP 클라이언트용.
+// tool 호출 시 x402 결제(USDC on Base Mainnet)를 자동 처리.
+//
+// 환경 변수:
+//   MCP_WALLET_PRIVATE_KEY  결제 지갑 private key (0x...)
+//   RESOURCE_SERVER_URL     API 서버 URL (기본: https://x402.deepsearch.com)
+// ============================================================
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { x402Client } from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { privateKeyToAccount } from "viem/accounts";
+// ── 환경 변수 ───────────────────────────────────────────────
+const PRIVATE_KEY = (process.env.MCP_WALLET_PRIVATE_KEY ?? "");
+const RESOURCE_URL = (process.env.RESOURCE_SERVER_URL ?? "https://x402.deepsearch.com").replace(/\/$/, "");
+if (!PRIVATE_KEY?.startsWith("0x")) {
+    process.stderr.write([
+        "❌ MCP_WALLET_PRIVATE_KEY is not set.",
+        "",
+        "Set it to an EVM private key (0x...) for a wallet holding USDC on Base Mainnet.",
+        "",
+        "Claude Desktop config example:",
+        JSON.stringify({
+            mcpServers: {
+                "deepsearch-stocks": {
+                    command: "npx",
+                    args: ["deepsearch-x402-mcp"],
+                    env: { MCP_WALLET_PRIVATE_KEY: "0x..." },
+                },
+            },
+        }, null, 2),
+        "",
+        "Get testnet USDC: https://faucet.circle.com",
+    ].join("\n") + "\n");
+    process.exit(1);
+}
+// ── x402 클라이언트 ──────────────────────────────────────────
+const account = privateKeyToAccount(PRIVATE_KEY);
+const x402 = new x402Client();
+registerExactEvmScheme(x402, { signer: account });
+const fetchWithPayment = wrapFetchWithPayment(fetch, x402);
+async function callAPI(path, params = {}) {
+    const url = new URL(`${RESOURCE_URL}${path}`);
+    for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, v);
+    const res = await fetchWithPayment(url.toString());
+    if (!res.ok)
+        throw new Error(`API ${res.status}: ${await res.text()}`);
+    return res.json();
+}
+// ── MCP 서버 ────────────────────────────────────────────────
+const server = new Server({ name: "deepsearch-korean-stocks", version: "1.0.0" }, { capabilities: { tools: {} } });
+// ── Tool 정의 ────────────────────────────────────────────────
+const TICKER_PROP = {
+    type: "string",
+    description: "Stock ticker. Korean stocks: 6-digit KRX code (e.g. 005930 Samsung, 000660 SK Hynix, 035420 NAVER, 005380 Hyundai). US stocks: symbol (e.g. AAPL)",
+};
+const EXCHANGE_PROP = {
+    type: "string",
+    description: "Exchange code. Default: KRX (Korea). For US stocks: NASDAQ or NYSE",
+};
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_company",
+            description: "Get company fundamentals for a Korean or global stock ($0.01 USDC). Returns market cap, PER, PBR, ROE, EPS, dividend yield, business overview, latest stock price with 52-week range, and most recent quarterly financials (revenue, operating profit, net income).",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_financials",
+            description: "Get latest quarterly financial statements ($0.01 USDC). Returns revenue, gross profit, operating profit, net income, total assets, equity, fiscal end date, and currency.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_dividend",
+            description: "Get dividend schedule ($0.01 USDC). Returns ex-dividend date, payment date, dividend amount, and forecast flag. Use for dividend investing analysis.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_news",
+            description: "Get recent 30-day news articles ($0.01 USDC). Returns title, summary, published date, and per-company sentiment (positive/negative/neutral).",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_stock_1m",
+            description: "Get 1-month daily stock price history ($0.01 USDC). Returns daily close, change %, market cap.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_stock_3m",
+            description: "Get 3-month daily stock price history ($0.02 USDC). Returns daily close, change %, market cap + period high/low/return.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_financials_2y",
+            description: "Get 2-year quarterly financials history ($0.02 USDC). Up to 8 quarters of revenue, operating profit, net income, assets, equity trends.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_stock_1y",
+            description: "Get 1-year daily stock price history ($0.03 USDC). Returns daily close + annual high/low/return. Use for medium-term trend analysis.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_financials_5y",
+            description: "Get 5-year quarterly financials history ($0.03 USDC). Up to 20 quarters of financial trends. Use for long-term growth analysis.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_issue",
+            description: "Get current news-driven issues analysis ($0.05 USDC). Based on 30 days of Korean financial news — returns key issues, sentiment labels, relevance scores. Use to understand what's happening with a company right now: earnings surprises, leadership changes, product launches, regulatory actions.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_risk",
+            description: "Get investment risk assessment ($0.05 USDC). Based on 60 days of news and regulatory filings — returns overall risk level (high/medium/low), risk items by category (financial, legal, operational, market), and mitigating factors. Use before recommending a stock or writing an investment memo.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_stock_3y",
+            description: "Get 3-year daily stock price history ($0.05 USDC). Returns daily close + 3-year high/low/cumulative return. Use for long-term performance analysis.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+        {
+            name: "get_financials_all",
+            description: "Get all available quarterly financials history ($0.05 USDC). Up to 10 years of quarterly financial data.",
+            inputSchema: { type: "object", properties: { ticker: TICKER_PROP, exchange: EXCHANGE_PROP }, required: ["ticker"] },
+        },
+    ],
+}));
+// ── Tool → 경로 매핑 ─────────────────────────────────────────
+const TOOL_PATHS = {
+    get_company: "/v1/context/company",
+    get_financials: "/v1/context/financials",
+    get_dividend: "/v1/context/dividend",
+    get_news: "/v1/context/news",
+    get_stock_1m: "/v1/context/stock/1m",
+    get_stock_3m: "/v1/context/stock/3m",
+    get_stock_1y: "/v1/context/stock/1y",
+    get_stock_3y: "/v1/context/stock/3y",
+    get_issue: "/v1/context/issue",
+    get_risk: "/v1/context/risk",
+    get_financials_2y: "/v1/context/financials/2y",
+    get_financials_5y: "/v1/context/financials/5y",
+    get_financials_all: "/v1/context/financials/all",
+};
+// ── Tool 실행 ────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args ?? {});
+    const ticker = String(a.ticker ?? "").trim();
+    const exchange = String(a.exchange ?? "KRX").trim();
+    if (!ticker) {
+        return { content: [{ type: "text", text: "Error: ticker parameter is required." }], isError: true };
+    }
+    const basePath = TOOL_PATHS[name];
+    if (!basePath) {
+        return { content: [{ type: "text", text: `Error: unknown tool ${name}` }], isError: true };
+    }
+    // period 히스토리 경로: /v1/context/stock/1m → /v1/context/stock/{ticker}/1m
+    const periodMatch = basePath.match(/\/(1m|3m|1y|3y|2y|5y|all)$/);
+    const path = periodMatch
+        ? basePath.replace(`/${periodMatch[1]}`, `/${ticker}/${periodMatch[1]}`)
+        : `${basePath}/${ticker}`;
+    const params = exchange !== "KRX" ? { exchange } : {};
+    try {
+        const data = await callAPI(path, params);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/insufficient|balance|usdc/i.test(msg)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Insufficient USDC balance.\nWallet: ${account.address}\nGet Base Mainnet USDC: https://coinbase.com or bridge from other chains.`,
+                    }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    }
+});
+// ── 시작 ────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+process.stderr.write(`DeepSearch Korean Stock MCP — wallet: ${account.address} | server: ${RESOURCE_URL}\n`);
+await server.connect(transport);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "deepsearch-x402-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for DeepSearch Korean Stock Intelligence API — pay-per-query via x402 USDC micropayments on Base Mainnet",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "deepsearch-x402-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "korean-stocks",
+    "krx",
+    "x402",
+    "usdc",
+    "deepsearch",
+    "finance",
+    "stock-data"
+  ],
+  "author": "DeepSearch <huni@deepsearch.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deepsearch-hq/deepsearch-x402.git"
+  },
+  "homepage": "https://x402.deepsearch.com",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@x402/core": "latest",
+    "@x402/evm": "latest",
+    "@x402/fetch": "latest",
+    "viem": "^2.21.0"
+  }
+}