criptokyc-mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +77 -3
  2. package/dist/cli.js +510 -0
  3. package/package.json +44 -6
package/README.md CHANGED
@@ -1,3 +1,77 @@
1
- # Temporary Holding Version
2
-
3
- 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.
1
+ # criptokyc-mcp
2
+
3
+ Sanctions screening inside your AI app. Ask Claude, Cursor or any MCP client whether a **person/entity name**
4
+ (UN Security Council list) or a **crypto wallet address** (OFAC, EU, UK, UN, Switzerland SECO, Israel NBCTF) is
5
+ sanctioned. You pay a few cents per screening in USDC, automatically, with no gas and no account.
6
+
7
+ > **Testnet only.** Payments use test USDC on Arc Testnet and have no real value.
8
+
9
+ ## Install (3 commands)
10
+
11
+ ```bash
12
+ npx -y criptokyc-mcp install
13
+ ```
14
+ Creates your agent wallet and registers the server in Claude Desktop, Cursor and Claude Code (whichever you have).
15
+
16
+ ```bash
17
+ # send test USDC (Arc Testnet) to the wallet address printed above: https://faucet.circle.com
18
+ npx -y criptokyc-mcp deposit 1
19
+ ```
20
+ Moves 1 test USDC into your payment balance (asks for confirmation; this is the only step that pays gas).
21
+
22
+ Then **restart your AI app** and ask: *"Is Noor Wali Mehsud on the UN sanctions list?"*
23
+
24
+ Check everything any time with `npx -y criptokyc-mcp status`.
25
+
26
+ ## Tools your AI gets
27
+
28
+ | Tool | Cost | What it does |
29
+ |---|---|---|
30
+ | `check_csnu_names` | per call (see `get_pricing`) | Names against the UN Security Council list, up to 50 per call |
31
+ | `check_wallet_sanctions` | per call | Wallet addresses against 6 official lists, up to 50 per call |
32
+ | `get_pricing` | free | Current prices |
33
+ | `get_budget` | free | Your wallet, balance and spending caps |
34
+
35
+ ## Safety
36
+
37
+ - **Your AI can only spend, never move funds.** There is no tool to deposit, withdraw or transfer.
38
+ - **Spending caps** (defaults): 0.05 USDC per call and 0.50 USDC per session. Change with the env vars
39
+ `CRIPTOKYC_MAX_PRICE_PER_CALL` and `CRIPTOKYC_MAX_SPEND_PER_SESSION`.
40
+ - The wallet's private key stays on your computer in `~/.criptokyc/wallet.json` (owner-only permissions on
41
+ macOS/Linux). It is never written to your AI app's config and never shown to the AI.
42
+ - It is a dedicated wallet: keep only the small amount you want the AI to be able to spend.
43
+ - Results are informational, based on official lists. They do not replace a compliance review.
44
+
45
+ ## Other clients
46
+
47
+ `install` auto-configures Claude Desktop, Cursor and Claude Code. For any other MCP client (Windsurf, Cline,
48
+ VS Code...), add this to its MCP settings, then run `npx -y criptokyc-mcp install` once to create the wallet:
49
+
50
+ ```json
51
+ { "mcpServers": { "criptokyc": { "command": "npx", "args": ["-y", "criptokyc-mcp"] } } }
52
+ ```
53
+
54
+ On Windows some apps need `"command": "cmd", "args": ["/c", "npx", "-y", "criptokyc-mcp"]` (the installer does this for you).
55
+
56
+ ## Troubleshooting
57
+
58
+ | Symptom | Fix |
59
+ |---|---|
60
+ | AI says "Insufficient Gateway balance" | Send test USDC to your wallet, then run `npx -y criptokyc-mcp deposit 1` |
61
+ | "Could not reach the screening service" | Run `npx -y criptokyc-mcp status`; the service may be offline |
62
+ | Tools do not appear | Fully quit and reopen the AI app after `install` |
63
+ | Spending cap reached | Restart the AI app (new session) or raise the caps with the env vars above |
64
+
65
+ ## Configuration (optional env vars)
66
+
67
+ `CRIPTOKYC_API_URL` (service URL), `CRIPTOKYC_MAX_PRICE_PER_CALL`, `CRIPTOKYC_MAX_SPEND_PER_SESSION`,
68
+ `CRIPTOKYC_HOME` (wallet folder), `CRIPTOKYC_BUYER_PRIVATE_KEY` (use your own key instead of the generated wallet).
69
+
70
+ ## Security notes
71
+
72
+ - Your wallet key lives only in `~/.criptokyc/wallet.json` (mode 600), never in your AI app's config file.
73
+ - The installed config **pins this package's version**, so a new release never runs on your machine by itself.
74
+ Update on purpose with `npx -y criptokyc-mcp@latest install`.
75
+ - The server **refuses to pay any address other than criptokyc.tech's**, and enforces spending caps
76
+ (0.05 USDC per call, 0.50 USDC per session by default).
77
+ - Use a dedicated wallet and keep a small balance in it.
package/dist/cli.js ADDED
@@ -0,0 +1,510 @@
1
+ #!/usr/bin/env node
2
+ var __getOwnPropNames = Object.getOwnPropertyNames;
3
+ var __esm = (fn, res, err) => function __init() {
4
+ if (err) throw err[0];
5
+ try {
6
+ return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
7
+ } catch (e) {
8
+ throw err = [e], e;
9
+ }
10
+ };
11
+
12
+ // config.ts
13
+ import { readFileSync } from "node:fs";
14
+ import { fileURLToPath } from "node:url";
15
+ function packageVersion() {
16
+ for (const rel of ["./package.json", "../package.json"]) {
17
+ try {
18
+ const pkg = JSON.parse(readFileSync(fileURLToPath(new URL(rel, import.meta.url)), "utf8"));
19
+ if (pkg.name === PACKAGE_NAME && pkg.version) return pkg.version;
20
+ } catch {
21
+ }
22
+ }
23
+ return "latest";
24
+ }
25
+ var DEFAULT_API_URL, CHAIN, FAUCET_URL, PACKAGE_NAME, SERVER_NAME, apiUrl, EXPECTED_PAY_TO, expectedPayTo;
26
+ var init_config = __esm({
27
+ "config.ts"() {
28
+ "use strict";
29
+ DEFAULT_API_URL = "https://agents.criptokyc.tech";
30
+ CHAIN = "arcTestnet";
31
+ FAUCET_URL = "https://faucet.circle.com";
32
+ PACKAGE_NAME = "criptokyc-mcp";
33
+ SERVER_NAME = "criptokyc";
34
+ apiUrl = () => (process.env.CRIPTOKYC_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
35
+ EXPECTED_PAY_TO = "0xd2f80f6cf27483392f70f21b3381109f9c33c390";
36
+ expectedPayTo = () => (process.env.CRIPTOKYC_PAY_TO ?? EXPECTED_PAY_TO).toLowerCase();
37
+ }
38
+ });
39
+
40
+ // wallet.ts
41
+ import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
42
+ import { homedir as homedir2 } from "node:os";
43
+ import { join as join2 } from "node:path";
44
+ import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
45
+ function parseKey(raw, where) {
46
+ if (typeof raw !== "string" || !KEY_RE.test(raw)) throw new Error(`Invalid private key in ${where} (expected 0x + 64 hex characters).`);
47
+ return raw;
48
+ }
49
+ function ensureWallet() {
50
+ const fromEnv = process.env.CRIPTOKYC_BUYER_PRIVATE_KEY;
51
+ if (fromEnv) {
52
+ const key2 = parseKey(fromEnv, "CRIPTOKYC_BUYER_PRIVATE_KEY");
53
+ return { key: key2, address: privateKeyToAccount(key2).address, source: "env", created: false };
54
+ }
55
+ const file = walletFile();
56
+ if (existsSync2(file)) {
57
+ try {
58
+ chmodSync(file, 384);
59
+ chmodSync(walletDir(), 448);
60
+ } catch {
61
+ }
62
+ const key2 = parseKey(JSON.parse(readFileSync3(file, "utf8")).privateKey, file);
63
+ return { key: key2, address: privateKeyToAccount(key2).address, source: "file", created: false };
64
+ }
65
+ mkdirSync2(walletDir(), { recursive: true, mode: 448 });
66
+ const key = generatePrivateKey();
67
+ const address = privateKeyToAccount(key).address;
68
+ writeFileSync2(file, JSON.stringify({ privateKey: key, address, network: "arcTestnet", createdAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), {
69
+ mode: 384,
70
+ flag: "wx"
71
+ });
72
+ return { key, address, source: "file", created: true };
73
+ }
74
+ var KEY_RE, walletDir, walletFile;
75
+ var init_wallet = __esm({
76
+ "wallet.ts"() {
77
+ "use strict";
78
+ KEY_RE = /^0x[0-9a-fA-F]{64}$/;
79
+ walletDir = () => process.env.CRIPTOKYC_HOME ?? join2(homedir2(), ".criptokyc");
80
+ walletFile = () => join2(walletDir(), "wallet.json");
81
+ }
82
+ });
83
+
84
+ // budget.ts
85
+ function usdcToAtomic(v, name) {
86
+ if (!/^\d+(\.\d{1,6})?$/.test(v)) throw new Error(`${name} inv\xE1lido: use um n\xFAmero de USDC, ex.: 0.05`);
87
+ const [whole, frac = ""] = v.split(".");
88
+ return BigInt(whole) * BigInt(ATOMIC) + BigInt((frac + "000000").slice(0, 6));
89
+ }
90
+ var ATOMIC, fmt, Budget;
91
+ var init_budget = __esm({
92
+ "budget.ts"() {
93
+ "use strict";
94
+ ATOMIC = 1e6;
95
+ fmt = (atomic) => {
96
+ const whole = atomic / BigInt(ATOMIC);
97
+ const frac = (atomic % BigInt(ATOMIC)).toString().padStart(6, "0");
98
+ return `${whole}.${frac}`;
99
+ };
100
+ Budget = class {
101
+ maxPerCall;
102
+ maxPerSession;
103
+ spent = 0n;
104
+ calls = 0;
105
+ constructor(env) {
106
+ this.maxPerCall = usdcToAtomic(env.CRIPTOKYC_MAX_PRICE_PER_CALL ?? "0.05", "CRIPTOKYC_MAX_PRICE_PER_CALL");
107
+ this.maxPerSession = usdcToAtomic(env.CRIPTOKYC_MAX_SPEND_PER_SESSION ?? "0.50", "CRIPTOKYC_MAX_SPEND_PER_SESSION");
108
+ }
109
+ /** Retorna o motivo da recusa, ou null se o pagamento é permitido. */
110
+ refusalReason(price) {
111
+ if (price > this.maxPerCall) {
112
+ return `per-call spending cap exceeded: this screening costs ${fmt(price)} USDC and the cap is ${fmt(this.maxPerCall)} USDC (CRIPTOKYC_MAX_PRICE_PER_CALL)`;
113
+ }
114
+ if (this.spent + price > this.maxPerSession) {
115
+ return `session spending cap exceeded: already spent ${fmt(this.spent)} of ${fmt(this.maxPerSession)} USDC (CRIPTOKYC_MAX_SPEND_PER_SESSION). Restart the AI app to start a new session.`;
116
+ }
117
+ return null;
118
+ }
119
+ record(amount) {
120
+ this.spent += amount;
121
+ this.calls += 1;
122
+ }
123
+ summary() {
124
+ return { spent: fmt(this.spent), calls: this.calls, remaining: fmt(this.maxPerSession - this.spent), maxPerCall: fmt(this.maxPerCall), maxPerSession: fmt(this.maxPerSession) };
125
+ }
126
+ };
127
+ }
128
+ });
129
+
130
+ // server.ts
131
+ var server_exports = {};
132
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
133
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
134
+ import { GatewayClient } from "@circle-fin/x402-batching/client";
135
+ import { z } from "zod";
136
+ async function explain(e) {
137
+ const base = fail(e);
138
+ const msg = base.content[0].text;
139
+ if (/cap exceeded|Could not reach|Insufficient Gateway/i.test(msg)) return base;
140
+ try {
141
+ const b = await client.getBalances();
142
+ if (b.gateway.available === 0n) return { isError: true, content: [{ type: "text", text: `Insufficient Gateway balance. ${NEXT_STEPS}` }] };
143
+ } catch {
144
+ }
145
+ return base;
146
+ }
147
+ var log, die, API_URL, wallet, KEY, budget, client, PAY_TO, queue, serialized, scrub, ok, NEXT_STEPS, friendly, fail, NOTE, item, server, paidHints;
148
+ var init_server = __esm({
149
+ async "server.ts"() {
150
+ "use strict";
151
+ init_budget();
152
+ init_config();
153
+ init_wallet();
154
+ log = (...a) => console.error("[criptokyc-mcp]", ...a);
155
+ die = (msg) => {
156
+ log(msg);
157
+ process.exit(1);
158
+ };
159
+ API_URL = apiUrl();
160
+ if ((process.env.CRIPTOKYC_CHAIN ?? CHAIN) !== CHAIN) {
161
+ die("This version only runs on testnet (arcTestnet). Mainnet is not enabled.");
162
+ }
163
+ try {
164
+ wallet = ensureWallet();
165
+ } catch (e) {
166
+ die(e instanceof Error ? e.message : String(e));
167
+ throw e;
168
+ }
169
+ KEY = wallet.key;
170
+ if (wallet.created) log(`new agent wallet created: ${wallet.address} (empty; needs test USDC, see get_budget)`);
171
+ try {
172
+ budget = new Budget(process.env);
173
+ } catch (e) {
174
+ die(e instanceof Error ? e.message : String(e));
175
+ throw e;
176
+ }
177
+ client = new GatewayClient({ chain: CHAIN, privateKey: KEY });
178
+ PAY_TO = expectedPayTo();
179
+ client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
180
+ if (selectedRequirements.payTo.toLowerCase() !== PAY_TO) {
181
+ return { abort: true, reason: "payment destination does not match the expected criptokyc.tech address; refusing to pay (possible spoofed service)" };
182
+ }
183
+ const reason = budget.refusalReason(BigInt(selectedRequirements.amount));
184
+ if (reason) return { abort: true, reason };
185
+ });
186
+ queue = Promise.resolve();
187
+ serialized = (fn) => {
188
+ const run = queue.then(fn, fn);
189
+ queue = run.catch(() => void 0);
190
+ return run;
191
+ };
192
+ scrub = (s) => s.replaceAll(KEY, "[redacted]").replace(/0x[0-9a-fA-F]{64}/g, "[redacted]");
193
+ ok = (text) => ({ content: [{ type: "text", text }] });
194
+ NEXT_STEPS = `The agent wallet ${wallet.address} has no spendable Gateway balance. The USER must: (1) send test USDC (Arc Testnet) to ${wallet.address}, for example from ${FAUCET_URL}; (2) run in a terminal: npx -y ${PACKAGE_NAME} deposit 1 . Then ask again.`;
195
+ friendly = (msg) => {
196
+ if (/insufficient/i.test(msg)) return `Insufficient Gateway balance. ${NEXT_STEPS}`;
197
+ if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|timed? ?out|aborted due to timeout/i.test(msg)) {
198
+ return `Could not reach the screening service at ${API_URL}. Check the internet connection, or try again shortly; the service may be offline.`;
199
+ }
200
+ return msg;
201
+ };
202
+ fail = (e) => ({
203
+ isError: true,
204
+ content: [{ type: "text", text: friendly(scrub(e instanceof Error ? e.message : String(e))) }]
205
+ });
206
+ NOTE = "Triagem informativa baseada em listas oficiais; n\xE3o substitui an\xE1lise de compliance.";
207
+ item = z.string().min(1).max(200);
208
+ server = new McpServer({ name: "criptokyc", version: "0.1.0" });
209
+ paidHints = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
210
+ server.registerTool(
211
+ "check_csnu_names",
212
+ {
213
+ title: "Check names against the UN Security Council (CSNU) sanctions list",
214
+ description: "Checks person or entity names against the UN Security Council consolidated sanctions list. COSTS USDC per call (see get_pricing), up to 50 names per call, paid automatically from the Gateway balance within the configured spending caps. One name per array item.",
215
+ inputSchema: { names: z.array(item).min(1).max(50) },
216
+ annotations: paidHints
217
+ },
218
+ ({ names }) => serialized(async () => {
219
+ try {
220
+ const r = await client.pay(
221
+ `${API_URL}/v1/csnu/check`,
222
+ { method: "POST", body: { names } }
223
+ );
224
+ budget.record(r.amount);
225
+ const lines = r.data.results.map((x) => `- ${x.name}: ${x.is_sanctioned ? "SANCTIONED (found in CSNU list)" : "not found"}`);
226
+ return ok(`CSNU: ${r.data.sanctioned_count} of ${r.data.results.length} sanctioned. Paid ${r.formattedAmount} USDC.
227
+ ${lines.join("\n")}
228
+ ${NOTE}`);
229
+ } catch (e) {
230
+ return explain(e);
231
+ }
232
+ })
233
+ );
234
+ server.registerTool(
235
+ "check_wallet_sanctions",
236
+ {
237
+ title: "Check crypto wallet addresses against international sanctions lists",
238
+ description: "Checks wallet addresses (EVM, Bitcoin, Tron, Solana, XRP and more) against OFAC (US), Israel NBCTF, UK OFSI, EU, UN and Switzerland SECO lists. COSTS USDC per call (see get_pricing), up to 50 addresses per call, paid automatically from the Gateway balance within the configured spending caps.",
239
+ inputSchema: { wallets: z.array(item).min(1).max(50) },
240
+ annotations: paidHints
241
+ },
242
+ ({ wallets }) => serialized(async () => {
243
+ try {
244
+ const r = await client.pay(
245
+ `${API_URL}/v1/wallets/check`,
246
+ { method: "POST", body: { wallets } }
247
+ );
248
+ budget.record(r.amount);
249
+ const lines = r.data.results.map(
250
+ (x) => `- ${x.address} (${x.chain ?? "unknown chain"}): ${x.is_sanctioned ? `SANCTIONED by ${x.sources.join(", ")}` : "not found in any list"}`
251
+ );
252
+ return ok(`Wallets: ${r.data.sanctioned_count} of ${r.data.results.length} sanctioned. Paid ${r.formattedAmount} USDC.
253
+ ${lines.join("\n")}
254
+ ${NOTE}`);
255
+ } catch (e) {
256
+ return explain(e);
257
+ }
258
+ })
259
+ );
260
+ server.registerTool(
261
+ "get_pricing",
262
+ {
263
+ title: "Get the price of each screening call",
264
+ description: "Free. Returns the current USDC price per call and the maximum items per call.",
265
+ inputSchema: {},
266
+ annotations: { readOnlyHint: true, openWorldHint: true }
267
+ },
268
+ async () => {
269
+ try {
270
+ const res = await fetch(`${API_URL}/v1/pricing`, { signal: AbortSignal.timeout(1e4) });
271
+ if (!res.ok) throw new Error(`pricing unavailable (HTTP ${res.status})`);
272
+ return ok(JSON.stringify(await res.json(), null, 2));
273
+ } catch (e) {
274
+ return fail(e);
275
+ }
276
+ }
277
+ );
278
+ server.registerTool(
279
+ "get_budget",
280
+ {
281
+ title: "Show payment balance and spending caps",
282
+ description: "Free. Shows the paying wallet address, its Gateway balance, how much was spent in this session and the spending caps.",
283
+ inputSchema: {},
284
+ annotations: { readOnlyHint: true, openWorldHint: true }
285
+ },
286
+ async () => {
287
+ try {
288
+ const b = await client.getBalances();
289
+ const s = budget.summary();
290
+ const hint = b.gateway.available === 0n ? [`Next step: ${NEXT_STEPS}`] : [];
291
+ return ok(
292
+ [
293
+ `Paying wallet: ${client.account.address}`,
294
+ `Gateway balance (spendable): ${b.gateway.formattedAvailable} USDC`,
295
+ `Wallet balance: ${b.wallet.formatted} USDC`,
296
+ `Session: spent ${s.spent} USDC in ${s.calls} call(s); remaining under cap ${s.remaining} USDC`,
297
+ `Caps: ${s.maxPerCall} USDC per call, ${s.maxPerSession} USDC per session`,
298
+ ...hint
299
+ ].join("\n")
300
+ );
301
+ } catch (e) {
302
+ return fail(e);
303
+ }
304
+ }
305
+ );
306
+ await server.connect(new StdioServerTransport());
307
+ log(`ready | api=${API_URL} | wallet=${client.account.address} | caps ${fmt(budget.maxPerCall)}/call ${fmt(budget.maxPerSession)}/session`);
308
+ }
309
+ });
310
+
311
+ // cli.ts
312
+ import { createInterface } from "node:readline/promises";
313
+
314
+ // clients.ts
315
+ init_config();
316
+ import { spawnSync } from "node:child_process";
317
+ import { constants, copyFileSync, existsSync, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
318
+ import { homedir } from "node:os";
319
+ import { dirname, join } from "node:path";
320
+ var ALL_CLIENTS = ["claude-desktop", "cursor", "claude-code"];
321
+ var isWin = () => process.platform === "win32";
322
+ var pinned = () => `${PACKAGE_NAME}@${packageVersion()}`;
323
+ function mcpEntry() {
324
+ const args = ["-y", pinned()];
325
+ return isWin() ? { command: "cmd", args: ["/c", "npx", ...args] } : { command: "npx", args };
326
+ }
327
+ function configPath(id) {
328
+ const home = homedir();
329
+ if (id === "cursor") return join(home, ".cursor", "mcp.json");
330
+ if (id === "claude-desktop") {
331
+ if (process.platform === "darwin") return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
332
+ if (isWin()) return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
333
+ return join(home, ".config", "Claude", "claude_desktop_config.json");
334
+ }
335
+ return null;
336
+ }
337
+ function hasClaudeCli() {
338
+ return spawnSync("claude", ["--version"], { stdio: "ignore", shell: isWin() }).status === 0;
339
+ }
340
+ function detectClients() {
341
+ const found = [];
342
+ for (const id of ["claude-desktop", "cursor"]) {
343
+ const p = configPath(id);
344
+ if (p && existsSync(dirname(p))) found.push(id);
345
+ }
346
+ if (hasClaudeCli()) found.push("claude-code");
347
+ return found;
348
+ }
349
+ function installInto(id) {
350
+ if (id === "claude-code") {
351
+ if (!hasClaudeCli()) {
352
+ return { client: id, status: "skipped", detail: `Claude Code CLI not found. Run: claude mcp add -s user ${SERVER_NAME} -- npx -y ${pinned()}` };
353
+ }
354
+ const add = () => spawnSync("claude", ["mcp", "add", "-s", "user", SERVER_NAME, "--", "npx", "-y", pinned()], { encoding: "utf8", shell: isWin() });
355
+ let r = add();
356
+ let out2 = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim().split("\n")[0] ?? "";
357
+ if (r.status !== 0 && /already exists/i.test(out2)) {
358
+ spawnSync("claude", ["mcp", "remove", "-s", "user", SERVER_NAME], { stdio: "ignore", shell: isWin() });
359
+ r = add();
360
+ out2 = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim().split("\n")[0] ?? "";
361
+ }
362
+ if (r.status === 0) return { client: id, status: "installed", detail: `registered with "claude mcp add" (${pinned()})` };
363
+ return { client: id, status: "failed", detail: out2 || "claude mcp add failed" };
364
+ }
365
+ const file = configPath(id);
366
+ let config = {};
367
+ if (existsSync(file)) {
368
+ try {
369
+ config = JSON.parse(readFileSync2(file, "utf8") || "{}");
370
+ } catch {
371
+ return { client: id, status: "failed", detail: `${file} is not valid JSON; left untouched. Fix it or add the entry by hand.` };
372
+ }
373
+ } else {
374
+ mkdirSync(dirname(file), { recursive: true });
375
+ }
376
+ const servers = config.mcpServers ??= {};
377
+ const entry = mcpEntry();
378
+ if (JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(entry)) return { client: id, status: "already", detail: file };
379
+ if (existsSync(file)) {
380
+ const bak = `${file}.criptokyc.bak`;
381
+ copyFileSync(file, existsSync(bak) ? `${bak}.${Date.now()}` : bak, constants.COPYFILE_EXCL);
382
+ }
383
+ servers[SERVER_NAME] = entry;
384
+ const tmp = `${file}.criptokyc.tmp`;
385
+ writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
386
+ renameSync(tmp, file);
387
+ return { client: id, status: "installed", detail: file };
388
+ }
389
+
390
+ // cli.ts
391
+ init_config();
392
+ init_wallet();
393
+ var [, , cmd, ...rest] = process.argv;
394
+ var flag = (name) => rest.includes(`--${name}`);
395
+ var option = (name) => {
396
+ const i = rest.indexOf(`--${name}`);
397
+ return i >= 0 ? rest[i + 1] : void 0;
398
+ };
399
+ var out = (...a) => console.log(...a);
400
+ async function gatewayClient() {
401
+ const { GatewayClient: GatewayClient2 } = await import("@circle-fin/x402-batching/client");
402
+ const w = ensureWallet();
403
+ return { w, client: new GatewayClient2({ chain: CHAIN, privateKey: w.key }) };
404
+ }
405
+ function nextSteps(address) {
406
+ out("\nNext steps:");
407
+ out(` 1. Send test USDC (Arc Testnet) to your agent wallet: ${address}`);
408
+ out(` Faucet: ${FAUCET_URL} (choose Arc Testnet)`);
409
+ out(` 2. Move some into the payment balance (one time, asks for confirmation): npx -y ${PACKAGE_NAME} deposit 1`);
410
+ out(" 3. Restart your AI app, then ask it to check a name or wallet against sanctions lists.");
411
+ }
412
+ async function install() {
413
+ const w = ensureWallet();
414
+ out(w.created ? `Agent wallet created: ${w.address}` : `Agent wallet: ${w.address}`);
415
+ out(` (private key stored only on this computer: ${w.source === "env" ? "environment variable" : walletFile()})`);
416
+ const requested = option("client");
417
+ let targets;
418
+ if (requested && requested !== "all") {
419
+ if (!ALL_CLIENTS.includes(requested)) {
420
+ out(`Unknown client "${requested}". Use: ${ALL_CLIENTS.join(", ")}, all`);
421
+ process.exit(1);
422
+ }
423
+ targets = [requested];
424
+ } else {
425
+ targets = requested === "all" ? ALL_CLIENTS : detectClients();
426
+ }
427
+ if (targets.length === 0) {
428
+ out("\nNo supported AI app detected automatically. Add this to the MCP settings of your app:");
429
+ out(JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpEntry() } }, null, 2));
430
+ } else {
431
+ out("");
432
+ for (const id of targets) {
433
+ const r = installInto(id);
434
+ out(` [${r.status}] ${id}: ${r.detail}`);
435
+ }
436
+ }
437
+ nextSteps(w.address);
438
+ }
439
+ async function deposit() {
440
+ const amount = rest.find((a) => /^\d+(\.\d+)?$/.test(a)) ?? "1";
441
+ const { w, client: client2 } = await gatewayClient();
442
+ const before = await client2.getBalances();
443
+ out(`Wallet ${w.address}`);
444
+ out(` wallet balance: ${before.wallet.formatted} USDC | payment (Gateway) balance: ${before.gateway.formattedAvailable} USDC`);
445
+ if (Number(before.wallet.formatted) < Number(amount)) {
446
+ out(`
447
+ Not enough USDC in the wallet to deposit ${amount}. Send test USDC to ${w.address} first (${FAUCET_URL}, Arc Testnet).`);
448
+ process.exit(1);
449
+ }
450
+ if (!flag("yes")) {
451
+ if (!process.stdin.isTTY) {
452
+ out("Run in an interactive terminal, or add --yes to confirm without asking.");
453
+ process.exit(1);
454
+ }
455
+ const rl = createInterface({ input: process.stdin, output: process.stdout });
456
+ const answer = await rl.question(`Deposit ${amount} USDC (testnet) into the payment balance? [y/N] `);
457
+ rl.close();
458
+ if (!/^y(es)?$/i.test(answer.trim())) {
459
+ out("Cancelled.");
460
+ return;
461
+ }
462
+ }
463
+ out("Depositing (one on-chain transaction, pays gas once)...");
464
+ await client2.deposit(amount);
465
+ const after = await client2.getBalances();
466
+ out(`Done. Payment (Gateway) balance: ${after.gateway.formattedAvailable} USDC. Your AI can now pay per screening, gas-free.`);
467
+ }
468
+ async function status() {
469
+ const { w, client: client2 } = await gatewayClient();
470
+ out(`Agent wallet: ${w.address} (${w.source === "env" ? "from environment" : walletFile()})`);
471
+ try {
472
+ const b = await client2.getBalances();
473
+ out(`Wallet balance: ${b.wallet.formatted} USDC | Payment (Gateway) balance: ${b.gateway.formattedAvailable} USDC`);
474
+ if (b.gateway.available === 0n) nextSteps(w.address);
475
+ } catch (e) {
476
+ out(`Could not read balances: ${e instanceof Error ? e.message : String(e)}`);
477
+ }
478
+ try {
479
+ const res = await fetch(`${apiUrl()}/health`, { signal: AbortSignal.timeout(8e3) });
480
+ out(`Service ${apiUrl()}: ${res.ok ? "online" : `HTTP ${res.status}`}`);
481
+ } catch {
482
+ out(`Service ${apiUrl()}: NOT reachable (offline, or CRIPTOKYC_API_URL is wrong)`);
483
+ }
484
+ }
485
+ function help() {
486
+ out(`${PACKAGE_NAME}: pay-per-use sanctions screening for AI apps (testnet)
487
+
488
+ npx -y ${PACKAGE_NAME} install [--client claude-desktop|cursor|claude-code|all]
489
+ npx -y ${PACKAGE_NAME} deposit [amount] [--yes]
490
+ npx -y ${PACKAGE_NAME} status
491
+ npx -y ${PACKAGE_NAME} run the MCP server (your AI app does this for you)`);
492
+ }
493
+ switch (cmd) {
494
+ case void 0:
495
+ case "serve":
496
+ await init_server().then(() => server_exports);
497
+ break;
498
+ case "install":
499
+ await install();
500
+ break;
501
+ case "deposit":
502
+ await deposit();
503
+ break;
504
+ case "status":
505
+ await status();
506
+ break;
507
+ default:
508
+ help();
509
+ process.exit(cmd === "help" || cmd === "--help" || cmd === "-h" ? 0 : 1);
510
+ }
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
- {
2
- "name": "criptokyc-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "criptokyc-mcp",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "MCP server for AI apps (Claude, Cursor and more): sanctions screening of names (UN Security Council) and crypto wallets (OFAC, EU, UK, UN, SECO, Israel), paid per call in USDC via x402. Testnet.",
6
+ "bin": {
7
+ "criptokyc-mcp": "dist/cli.js"
8
+ },
9
+ "scripts": {
10
+ "build": "node build.mjs",
11
+ "prepublishOnly": "npm run build",
12
+ "typecheck": "tsc --noEmit",
13
+ "test:client": "bun run test-client.ts"
14
+ },
15
+ "dependencies": {
16
+ "@circle-fin/x402-batching": "^4.0.0",
17
+ "@modelcontextprotocol/sdk": "^1.32.2",
18
+ "viem": "^2.58.2",
19
+ "zod": "^4.6.7"
20
+ },
21
+ "devDependencies": {
22
+ "@types/node": "^26.6.6",
23
+ "esbuild": "^0.28.2",
24
+ "typescript": "^7.0.2"
25
+ },
26
+ "license": "MIT",
27
+ "files": [
28
+ "dist",
29
+ "README.md"
30
+ ],
31
+ "engines": {
32
+ "node": ">=18"
33
+ },
34
+ "keywords": [
35
+ "mcp",
36
+ "model-context-protocol",
37
+ "x402",
38
+ "usdc",
39
+ "sanctions",
40
+ "compliance",
41
+ "arc",
42
+ "circle"
43
+ ]
44
+ }