@quidli/connect-mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,57 +1,128 @@
-# @quidli/connect-mcp
+# Quidli Connect MCP
 
-MCP server exposing [Quidli Connect](https://connect.quid.li) product APIs as tools for Cursor, Claude Desktop, and other MCP hosts.
+Use [Quidli Connect](https://connect.quid.li) from Cursor, Claude Desktop, or any MCP-compatible client — wallet lookup, scores, Smart Send drops, and the Connect agent.
 
-## Requirements
+## Choose how to connect
 
-- Node.js 20+
-- A Connect API key ([Enable API access](https://connect.quid.li))
 
-## Cursor configuration
+|                 | **Hosted** (`mcp.connect.quid.li`)                                                   | **Local** (`npx @quidli/connect-mcp`)                                                      |
+| --------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| **Setup**       | Add a URL in MCP settings                                                            | Run a local process via `npx`                                                              |
+| **Auth**        | Connect API key only                                                                 | API key **or** x402 pay-per-call                                                           |
+| **Pros**        | No install; always on Quidli infrastructure; simplest setup                          | Wallet private key never leaves your machine; pay per call with USDC instead of an API key |
+| **Cons**        | Requires a Connect API key; no pay-per-call billing                                  | Requires Node.js 20+; `npx` may download the package on first run                          |
+| **Limitations** | Cannot use x402 / wallet auth — do **not** send a private key to the hosted endpoint | x402 mode needs USDC on Base (mainnet `8453`); `connect_drop` requires an API key          |
 
-### Remote URL (recommended for production)
 
-Same pattern as GitHub MCP — Cursor connects to a hosted endpoint and sends your API key in headers:
+Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access**.
+
+---
+
+## Hosted (recommended)
+
+Best if you have a Connect API key and want zero local setup.
+
+### Cursor
+
+**If you already have other MCP servers:** skip the deeplink and [add manually](#cursor-manual) — the one-click install can overwrite your entire `mcp.json` in some Cursor versions.
+
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==)
+
+Or paste into **Cursor Settings → MCP → Add new MCP server**:
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==
+```
+
+Then open **Cursor Settings → MCP → quidli-connect** and set `headers.x-api-key` to your Connect API key.
+
+#### Add manually {#cursor-manual}
+
+Merge this into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) under `mcpServers` — do not replace your existing entries:
+
+```json
+"quidli-connect": {
+  "url": "https://mcp.connect.quid.li",
+  "headers": {
+    "x-api-key": "<your-connect-api-key>"
+  }
+}
+```
+
+### Claude Desktop
+
+1. Open **Claude → Settings → Connectors** (or **Settings → Developer → Edit Config** on older versions).
+2. Add a custom MCP connector with URL `https://mcp.connect.quid.li` and header `x-api-key: <your-connect-api-key>`.
+
+Or merge this into your config file and restart Claude:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
-    "connect": {
+    "quidli-connect": {
       "url": "https://mcp.connect.quid.li",
       "headers": {
-        "x-api-key": "set-your-api-key-here"
+        "x-api-key": "<your-connect-api-key>"
       }
     }
   }
 }
 ```
 
-After one-click install, open **Cursor Settings → MCP → connect** and replace `set-your-api-key-here` with your real API key from [connect.quid.li](https://connect.quid.li) (Enable API access). Until you do, the server returns `401` with setup instructions.
-
-**Add to Cursor** deeplink (placeholder key pre-filled):
+If your Claude version does not support remote `url` connectors, use the local bridge instead (still hosted API, runs a small local helper):
 
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkIiwiaGVhZGVycyI6eyJ4LWFwaS1rZXkiOiJzZXQteW91ci1hcGkta2V5LWhlcmUifX0=
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "--http",
+        "https://mcp.connect.quid.li",
+        "--header",
+        "x-api-key:${CONNECT_API_KEY}"
+      ],
+      "env": {
+        "CONNECT_API_KEY": "<your-connect-api-key>"
+      }
+    }
+  }
+}
 ```
 
-Or generate programmatically:
+Requires **Node.js 20+** for the bridge. Restart Claude Desktop after saving. You should see a hammer icon in the chat input when tools are available.
 
-```typescript
-import { buildCursorMcpInstallDeeplink } from '@quidli/connect-mcp/deeplink';
-```
+Until a valid API key is set, requests return `401` with setup instructions.
+
+---
+
+## Local (stdio)
+
+Best if you want pay-per-call with a wallet, or prefer credentials in a local env file.
+
+Requires **Node.js 20+**.
+
+### Cursor
+
+Add one of the following to `.cursor/mcp.json` (project) or your global MCP settings.
 
-### Local stdio (npm / development)
+#### Option A — API key
 
-Add to `.cursor/mcp.json` (or global MCP settings):
+Same billing model as hosted; credentials stay on your machine.
 
 ```json
 {
   "mcpServers": {
-    "connect": {
+    "quidli-connect": {
       "command": "npx",
       "args": ["-y", "@quidli/connect-mcp"],
       "env": {
-        "CONNECT_API_KEY": "<your-api-key>",
+        "CONNECT_API_KEY": "<your-connect-api-key>",
         "CONNECT_API_BASE_URL": "https://api.connect.quid.li"
       }
     }
@@ -59,59 +130,91 @@ Add to `.cursor/mcp.json` (or global MCP settings):
 }
 ```
 
-`CONNECT_API_KEY` is **required** for stdio mode — the process exits at startup if missing. Remote HTTP mode reads `x-api-key` from each request instead.
+#### Option B — x402 pay-per-call (wallet)
 
-## Standalone HTTP server (local / debugging)
+No API key. Authenticated calls pay automatically when the API returns HTTP 402. Your wallet private key is only read by the local process.
 
-```bash
-cd packages/connect-mcp
-npm run build
-CONNECT_API_BASE_URL=https://api.connect.quid.li npm run start:http
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x<wallet-with-usdc-on-base>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li",
+        "CONNECT_X402_EVM_NETWORK": "8453"
+      }
+    }
+  }
+}
 ```
 
-Environment:
+Use `84532` for Base Sepolia when pointing at a staging API.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CONNECT_MCP_HTTP_HOST` | `0.0.0.0` | Bind address |
-| `CONNECT_MCP_HTTP_PORT` | `8080` | Listen port |
-| `CONNECT_API_BASE_URL` | `https://api.connect.quid.li` | Upstream Connect API |
+### Claude Desktop
 
-Health check: `GET /health`
+1. Open **Claude → Settings → Developer → Edit Config** (enable Developer mode first if you do not see it).
+2. Merge one of the blocks below into `mcpServers` in:
 
-## Tools (7)
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
-| Tool | HTTP | Auth |
-|------|------|------|
-| `connect_get_price` | `GET /price` | none |
-| `connect_lookup` | `POST /lookup` | api-key |
-| `connect_scores_batch` | `POST /scores` | api-key |
-| `connect_scores_by_account` | `GET /scores/:platform/:identifier` | api-key |
-| `connect_scores_by_username` | `GET /scores/u/:username` | api-key |
-| `connect_drop` | `POST /drop` | api-key |
-| `connect_agent_prompt` | `POST /agent` | api-key |
+3. Restart Claude Desktop.
 
-Not exposed: `POST /lookup/exposed`, agent feedback, member/admin routes.
+#### Option A — API key
 
-## Auth notes
-
-- **MCP uses api-key only.** x402 pay-per-call and Privy Bearer are HTTP-only (use [API docs](https://connect.quid.li/docs) or skills directly).
-- `connect_get_price` is public on the HTTP API and does not send `x-api-key`.
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_KEY": "<your-connect-api-key>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li"
+      }
+    }
+  }
+}
+```
 
-## Development
+#### Option B — x402 pay-per-call (wallet)
 
-```bash
-cd packages/connect-mcp
-npm install
-npm test
-npm run build
-CONNECT_API_KEY=<key> npm start
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x<wallet-with-usdc-on-base>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li",
+        "CONNECT_X402_EVM_NETWORK": "8453"
+      }
+    }
+  }
+}
 ```
 
-## Publish
+If both `CONNECT_API_KEY` and `EVM_PRIVATE_KEY` are set, the API key is used.
+
+At least one of `CONNECT_API_KEY` or `EVM_PRIVATE_KEY` is required for local mode.
+
+---
+
+## Tools
+
+
+| Tool                         | What it does                                              |
+| ---------------------------- | --------------------------------------------------------- |
+| `connect_get_price`          | List reference prices (no auth)                           |
+| `connect_lookup`             | Resolve social identities to EVM and SOL wallet addresses |
+| `connect_scores_batch`       | Batch scores for accounts or usernames                    |
+| `connect_scores_by_account`  | Scores for one linked account                             |
+| `connect_scores_by_username` | Scores by Connect username                                |
+| `connect_drop`               | Smart Send (batch token transfer) — **API key only**      |
+| `connect_agent_prompt`       | Natural-language agent for recipients discovery           |
 
-```bash
-npm publish --access public
-```
 
-(Requires `@quidli` npm org access.)
+Ask your client to use these tools when you need Connect data or actions.

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import type { ConnectClientConfig } from './config.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export type HttpMethod = 'GET' | 'POST';
+export type ConnectAuthMode = 'api-key' | 'x402';
 export interface ConnectRequestOptions {
     method: HttpMethod;
     path: string;
@@ -11,6 +12,9 @@ export interface ConnectRequestOptions {
 }
 export declare class ConnectClient {
     private readonly config;
+    private readonly authMode;
+    private readonly paidFetch?;
     constructor(config: ConnectClientConfig);
+    private resolveFetch;
     request(options: ConnectRequestOptions): Promise<CallToolResult>;
 }

package/dist/client.js

@@ -1,9 +1,22 @@
 import { mapHttpError } from './errors.js';
 import { errorResult, successResult } from './result.js';
+import { createPaidFetch } from './x402-fetch.js';
 export class ConnectClient {
     config;
+    authMode;
+    paidFetch;
     constructor(config) {
         this.config = config;
+        this.authMode = config.apiKey ? 'api-key' : 'x402';
+        if (!config.apiKey && config.evmPrivateKey) {
+            this.paidFetch = createPaidFetch(config.evmPrivateKey, config.x402EvmNetwork);
+        }
+    }
+    resolveFetch(authenticated) {
+        if (authenticated && this.paidFetch) {
+            return this.paidFetch;
+        }
+        return fetch;
     }
     async request(options) {
         const { method, path, body, query, timeoutMs } = options;
@@ -19,7 +32,7 @@ export class ConnectClient {
         const headers = {
             accept: 'application/json',
         };
-        if (authenticated) {
+        if (authenticated && this.config.apiKey) {
             headers['x-api-key'] = this.config.apiKey;
         }
         if (body !== undefined) {
@@ -29,8 +42,9 @@ export class ConnectClient {
         const timeout = timeoutMs
             ? setTimeout(() => controller.abort(), timeoutMs)
             : undefined;
+        const httpFetch = this.resolveFetch(authenticated);
         try {
-            const response = await fetch(url, {
+            const response = await httpFetch(url, {
                 method,
                 headers,
                 body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -39,9 +53,9 @@ export class ConnectClient {
             const raw = await response.json().catch(() => ({}));
             if (!response.ok) {
                 if (response.status === 504) {
-                    return errorResult(mapHttpError(504, raw));
+                    return errorResult(mapHttpError(504, raw, this.authMode));
                 }
-                return errorResult(mapHttpError(response.status, raw));
+                return errorResult(mapHttpError(response.status, raw, this.authMode));
             }
             return successResult({
                 httpStatus: response.status,

package/dist/config.d.ts

@@ -1,6 +1,11 @@
 export interface ConnectClientConfig {
     baseUrl: string;
-    apiKey: string;
+    /** When set, sent on every authenticated Connect API request. */
+    apiKey?: string;
+    /** When apiKey is unset, authenticated requests pay via x402 on 402. */
+    evmPrivateKey?: `0x${string}`;
+    /** EVM chain id for x402 (default 8453 = Base mainnet). */
+    x402EvmNetwork: number;
 }
 export interface HttpServerConfig {
     host: string;
@@ -8,4 +13,7 @@ export interface HttpServerConfig {
     baseUrl: string;
 }
 export declare function loadHttpServerConfig(env?: NodeJS.ProcessEnv): HttpServerConfig;
+/** Stdio MCP: CONNECT_API_KEY and/or EVM_PRIVATE_KEY (at least one required). */
 export declare function loadConfig(env?: NodeJS.ProcessEnv): ConnectClientConfig;
+/** Hosted HTTP MCP: api-key from request header only. */
+export declare function createHostedClientConfig(apiKey: string, baseUrl: string): ConnectClientConfig;

package/dist/config.js

@@ -1,6 +1,19 @@
+import { normalizeEvmPrivateKey } from './x402-fetch.js';
 const DEFAULT_BASE_URL = 'https://api.connect.quid.li';
 const DEFAULT_HTTP_HOST = '0.0.0.0';
 const DEFAULT_HTTP_PORT = 8080;
+const DEFAULT_X402_EVM_NETWORK = 8453;
+function parseX402EvmNetwork(env) {
+    const raw = env.CONNECT_X402_EVM_NETWORK?.trim() || env.X402_EVM_NETWORK?.trim() || String(DEFAULT_X402_EVM_NETWORK);
+    const network = Number(raw);
+    if (!Number.isInteger(network) || network < 1) {
+        throw new Error(`CONNECT_X402_EVM_NETWORK must be a positive integer (got "${raw}")`);
+    }
+    return network;
+}
+function loadBaseUrl(env) {
+    return (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
+}
 export function loadHttpServerConfig(env = process.env) {
     const host = env.CONNECT_MCP_HTTP_HOST?.trim() || DEFAULT_HTTP_HOST;
     const portRaw = env.CONNECT_MCP_HTTP_PORT?.trim() || String(DEFAULT_HTTP_PORT);
@@ -8,14 +21,28 @@ export function loadHttpServerConfig(env = process.env) {
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
         throw new Error(`CONNECT_MCP_HTTP_PORT must be a valid port (got "${portRaw}")`);
     }
-    const baseUrl = (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
-    return { host, port, baseUrl };
+    return { host, port, baseUrl: loadBaseUrl(env) };
 }
+/** Stdio MCP: CONNECT_API_KEY and/or EVM_PRIVATE_KEY (at least one required). */
 export function loadConfig(env = process.env) {
-    const apiKey = env.CONNECT_API_KEY?.trim();
-    if (!apiKey) {
-        throw new Error('CONNECT_API_KEY is required. Get a key at https://connect.quid.li (Enable API access).');
+    const apiKey = env.CONNECT_API_KEY?.trim() || undefined;
+    const evmPrivateKey = normalizeEvmPrivateKey(env.EVM_PRIVATE_KEY);
+    const x402EvmNetwork = parseX402EvmNetwork(env);
+    if (!apiKey && !evmPrivateKey) {
+        throw new Error('CONNECT_API_KEY or EVM_PRIVATE_KEY is required. Get an API key at https://connect.quid.li (Enable API access), or set EVM_PRIVATE_KEY for pay-per-call x402.');
     }
-    const baseUrl = (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
-    return { apiKey, baseUrl };
+    return {
+        baseUrl: loadBaseUrl(env),
+        apiKey,
+        evmPrivateKey: apiKey ? undefined : evmPrivateKey,
+        x402EvmNetwork,
+    };
+}
+/** Hosted HTTP MCP: api-key from request header only. */
+export function createHostedClientConfig(apiKey, baseUrl) {
+    return {
+        baseUrl,
+        apiKey,
+        x402EvmNetwork: DEFAULT_X402_EVM_NETWORK,
+    };
 }

package/dist/deeplink.js

@@ -7,7 +7,7 @@ export function buildCursorRemoteMcpConfig(apiKey = CONNECT_MCP_API_KEY_PLACEHOL
         },
     };
 }
-export function buildCursorMcpInstallDeeplink(serverName = 'connect', config = buildCursorRemoteMcpConfig()) {
+export function buildCursorMcpInstallDeeplink(serverName = 'quidli-connect', config = buildCursorRemoteMcpConfig()) {
     const encoded = Buffer.from(JSON.stringify(config), 'utf8').toString('base64');
     return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(serverName)}&config=${encoded}`;
 }

package/dist/errors.d.ts

@@ -1,2 +1,3 @@
 export declare function parseNestErrorMessage(body: unknown): string;
-export declare function mapHttpError(status: number, body: unknown): string;
+export type ConnectAuthMode = 'api-key' | 'x402';
+export declare function mapHttpError(status: number, body: unknown, authMode?: ConnectAuthMode): string;

package/dist/errors.js

@@ -10,15 +10,19 @@ export function parseNestErrorMessage(body) {
     }
     return 'Request failed';
 }
-export function mapHttpError(status, body) {
+export function mapHttpError(status, body, authMode = 'api-key') {
     const detail = parseNestErrorMessage(body);
     switch (status) {
         case 400:
             return detail;
         case 401:
-            return `Unauthorized: ${detail}. Verify CONNECT_API_KEY at https://connect.quid.li`;
+            return authMode === 'api-key'
+                ? `Unauthorized: ${detail}. Verify CONNECT_API_KEY at https://connect.quid.li`
+                : `Unauthorized: ${detail}. Verify EVM_PRIVATE_KEY and wallet USDC balance for x402.`;
         case 402:
-            return `Payment required (${detail}). MCP requires a valid Connect API key — x402 is not supported in MCP.`;
+            return authMode === 'api-key'
+                ? `Payment required (${detail}). Set CONNECT_API_KEY or use local stdio with EVM_PRIVATE_KEY for x402.`
+                : `Payment failed (${detail}). Ensure your wallet has USDC on the expected network and EVM_PRIVATE_KEY is correct.`;
         case 404:
             return detail;
         case 504:

package/dist/mount.js

@@ -1,4 +1,5 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createHostedClientConfig } from './config.js';
 import { createMcpServer } from './create-mcp-server.js';
 import { validateRequestApiKey } from './http-auth.js';
 export { resolveRequestHost } from './request-host.js';
@@ -49,7 +50,7 @@ export function mountConnectMcpHttp(router, options) {
             return;
         }
         try {
-            const server = createMcpServer({ apiKey: auth.apiKey, baseUrl });
+            const server = createMcpServer(createHostedClientConfig(auth.apiKey, baseUrl));
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // stateless — no session tracking
                 enableJsonResponse: true,

package/dist/x402-fetch.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeEvmPrivateKey(value: string | undefined): `0x${string}` | undefined;
+export declare function createPaidFetch(evmPrivateKey: `0x${string}`, chainId: number): typeof fetch;

package/dist/x402-fetch.js

@@ -0,0 +1,30 @@
+import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { toClientEvmSigner } from '@x402/evm';
+import { privateKeyToAccount } from 'viem/accounts';
+import { createPublicClient, http } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+const EVM_CHAIN_BY_ID = {
+    8453: base,
+    84532: baseSepolia,
+};
+export function normalizeEvmPrivateKey(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return (trimmed.startsWith('0x') ? trimmed : `0x${trimmed}`);
+}
+function getEvmPublicClient(chainId) {
+    const chain = EVM_CHAIN_BY_ID[chainId] ?? base;
+    return createPublicClient({ chain, transport: http() });
+}
+export function createPaidFetch(evmPrivateKey, chainId) {
+    const account = privateKeyToAccount(evmPrivateKey);
+    const evmSigner = toClientEvmSigner(account, getEvmPublicClient(chainId));
+    const client = new x402Client();
+    const scheme = new ExactEvmScheme(evmSigner);
+    client.register(`eip155:${chainId}`, scheme);
+    client.register('eip155:*', scheme);
+    return wrapFetchWithPayment(fetch, client);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server for Quidli Connect product APIs",
   "keywords": [
     "mcp",
@@ -13,6 +13,11 @@
     "agent"
   ],
   "homepage": "https://connect.quid.li",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quidli/sns-backend.git",
+    "directory": "packages/connect-mcp"
+  },
   "author": {
     "name": "Quidli",
     "url": "https://quid.xyz"
@@ -47,10 +52,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
+    "@x402/evm": "~2.5.0",
+    "@x402/fetch": "~2.5.0",
     "express": "^5.2.1",
+    "viem": "^2.50.4",
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^22.13.10",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"