@quidli/connect-mcp 0.3.0 → 0.4.0

package/README.md

@@ -8,38 +8,44 @@ Use [Quidli Connect](https://connect.quid.li) from Cursor, Claude Desktop, or an
 |                 | **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, x402 pay-per-call, or none for lookup/scores/agent                                |
-| **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                          |
+| **Auth**        | Optional API key. Without a key: lookup/scores/agent/price under a shared anonymous quota | API key, x402 pay-per-call, or none for lookup/scores/agent                                |
+| **Pros**        | No install; try without a key; always on Quidli infrastructure                       | Wallet private key never leaves your machine; pay per call with USDC instead of an API key |
+| **Cons**        | Anonymous traffic shares a global rate limit; 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          |
 
 
-Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access**.
+Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access** for higher limits, `connect_me`, and Smart Send.
 
 ---
 
 ## Hosted (recommended)
 
-Best if you have a Connect API key and want zero local setup.
+Zero local setup. Lookup, scores, agent, and price work without an API key (shared anonymous quota). Add a key for higher limits, your profile (`connect_me`), and Smart Send.
 
 ### 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==)
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkifQ==)
 
 Or paste into **Cursor Settings → MCP → Add new MCP server**:
 
 ```
-cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==
+cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkifQ==
 ```
 
-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"
+}
+```
+
+Optional — higher limits and Smart Send:
+
 ```json
 "quidli-connect": {
   "url": "https://mcp.connect.quid.li",
@@ -52,7 +58,7 @@ Merge this into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) un
 ### 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>`.
+2. Add a custom MCP connector with URL `https://mcp.connect.quid.li`. Optionally set header `x-api-key: <your-connect-api-key>`.
 
 Or merge this into your config file and restart Claude:
 
@@ -63,10 +69,7 @@ Or merge this into your config file and restart Claude:
 {
   "mcpServers": {
     "quidli-connect": {
-      "url": "https://mcp.connect.quid.li",
-      "headers": {
-        "x-api-key": "<your-connect-api-key>"
-      }
+      "url": "https://mcp.connect.quid.li"
     }
   }
 }
@@ -83,13 +86,8 @@ If your Claude version does not support remote `url` connectors, use the local b
         "-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>"
-      }
+        "https://mcp.connect.quid.li"
+      ]
     }
   }
 }
@@ -97,7 +95,7 @@ If your Claude version does not support remote `url` connectors, use the local b
 
 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.
 
-Until a valid API key is set, requests return `401` with setup instructions.
+Without a key, `initialize` / `tools/list` always succeed. Anonymous `tools/call` share a global quota (HTTP **429** when exceeded — get a key for higher limits). Placeholder keys still return **401**.
 
 ---
 

package/dist/anonymous-quota.d.ts

@@ -0,0 +1,28 @@
+import type { AnonymousQuotaConfig } from './config.js';
+export declare const ANON_QUOTA_EXEMPT_TOOLS: Set<string>;
+export declare const ANON_AGENT_TOOL = "connect_agent_prompt";
+export interface QuotaDecision {
+    allowed: boolean;
+    retryAfterSec?: number;
+    message?: string;
+}
+export declare class SlidingWindowLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private readonly now;
+    private hits;
+    constructor(limit: number, windowMs?: number, now?: () => number);
+    private prune;
+    wouldExceed(): {
+        exceeded: boolean;
+        retryAfterSec: number;
+    };
+    record(): void;
+}
+export declare class AnonymousToolQuota {
+    private readonly global;
+    private readonly agent;
+    constructor(global: SlidingWindowLimiter, agent: SlidingWindowLimiter);
+    static fromConfig(config: AnonymousQuotaConfig, now?: () => number): AnonymousToolQuota;
+    consume(body: unknown): QuotaDecision;
+}

package/dist/anonymous-quota.js

@@ -0,0 +1,78 @@
+import { getJsonRpcMethod, getJsonRpcToolName } from './jsonrpc.js';
+export const ANON_QUOTA_EXEMPT_TOOLS = new Set(['connect_get_price']);
+export const ANON_AGENT_TOOL = 'connect_agent_prompt';
+const GLOBAL_QUOTA_MESSAGE = 'Anonymous MCP quota exceeded. Get a Connect API key at https://connect.quid.li (Enable API access) for higher limits.';
+const AGENT_QUOTA_MESSAGE = 'Anonymous MCP agent quota exceeded. Get a Connect API key at https://connect.quid.li (Enable API access) for higher limits.';
+export class SlidingWindowLimiter {
+    limit;
+    windowMs;
+    now;
+    hits = [];
+    constructor(limit, windowMs = 60_000, now = Date.now) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    prune(now) {
+        const cutoff = now - this.windowMs;
+        while (this.hits.length > 0 && this.hits[0] <= cutoff) {
+            this.hits.shift();
+        }
+    }
+    wouldExceed() {
+        const now = this.now();
+        this.prune(now);
+        if (this.hits.length >= this.limit) {
+            const retryAfterSec = Math.max(1, Math.ceil((this.hits[0] + this.windowMs - now) / 1000));
+            return { exceeded: true, retryAfterSec };
+        }
+        return { exceeded: false, retryAfterSec: 0 };
+    }
+    record() {
+        this.hits.push(this.now());
+    }
+}
+export class AnonymousToolQuota {
+    global;
+    agent;
+    constructor(global, agent) {
+        this.global = global;
+        this.agent = agent;
+    }
+    static fromConfig(config, now) {
+        return new AnonymousToolQuota(new SlidingWindowLimiter(config.rpm, 60_000, now), new SlidingWindowLimiter(config.agentRpm, 60_000, now));
+    }
+    consume(body) {
+        const method = getJsonRpcMethod(body);
+        if (method !== 'tools/call') {
+            return { allowed: true };
+        }
+        const toolName = getJsonRpcToolName(body);
+        if (toolName && ANON_QUOTA_EXEMPT_TOOLS.has(toolName)) {
+            return { allowed: true };
+        }
+        if (toolName === ANON_AGENT_TOOL) {
+            const agentLimit = this.agent.wouldExceed();
+            if (agentLimit.exceeded) {
+                return {
+                    allowed: false,
+                    retryAfterSec: agentLimit.retryAfterSec,
+                    message: AGENT_QUOTA_MESSAGE,
+                };
+            }
+        }
+        const globalLimit = this.global.wouldExceed();
+        if (globalLimit.exceeded) {
+            return {
+                allowed: false,
+                retryAfterSec: globalLimit.retryAfterSec,
+                message: GLOBAL_QUOTA_MESSAGE,
+            };
+        }
+        if (toolName === ANON_AGENT_TOOL) {
+            this.agent.record();
+        }
+        this.global.record();
+        return { allowed: true };
+    }
+}

package/dist/config.d.ts

@@ -19,5 +19,12 @@ export declare function loadHttpServerConfig(env?: NodeJS.ProcessEnv): HttpServe
  * or with CONNECT_API_KEY / EVM_PRIVATE_KEY. /account/me and /drop require an API key.
  */
 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;
+export interface AnonymousQuotaConfig {
+    allowAnonymous: boolean;
+    rpm: number;
+    agentRpm: number;
+}
+export declare function isAnonymousMcpAllowed(env?: NodeJS.ProcessEnv): boolean;
+export declare function loadAnonymousQuotaConfig(env?: NodeJS.ProcessEnv): AnonymousQuotaConfig;
+/** Hosted HTTP MCP: api-key from request header when present. */
+export declare function createHostedClientConfig(apiKey: string | undefined, baseUrl: string): ConnectClientConfig;

package/dist/config.js

@@ -39,11 +39,35 @@ export function loadConfig(env = process.env) {
         x402EvmNetwork,
     };
 }
-/** Hosted HTTP MCP: api-key from request header only. */
+const DEFAULT_ANON_RPM = 50;
+const DEFAULT_ANON_AGENT_RPM = 5;
+export function isAnonymousMcpAllowed(env = process.env) {
+    const raw = env.CONNECT_MCP_ALLOW_ANONYMOUS?.trim().toLowerCase();
+    return raw === 'true' || raw === '1';
+}
+function parsePositiveInt(raw, fallback, name) {
+    if (!raw?.trim()) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${name} must be a positive integer (got "${raw}")`);
+    }
+    return value;
+}
+export function loadAnonymousQuotaConfig(env = process.env) {
+    return {
+        allowAnonymous: isAnonymousMcpAllowed(env),
+        rpm: parsePositiveInt(env.CONNECT_MCP_ANON_RPM, DEFAULT_ANON_RPM, 'CONNECT_MCP_ANON_RPM'),
+        agentRpm: parsePositiveInt(env.CONNECT_MCP_ANON_AGENT_RPM, DEFAULT_ANON_AGENT_RPM, 'CONNECT_MCP_ANON_AGENT_RPM'),
+    };
+}
+/** Hosted HTTP MCP: api-key from request header when present. */
 export function createHostedClientConfig(apiKey, baseUrl) {
+    const trimmed = apiKey?.trim() || undefined;
     return {
         baseUrl,
-        apiKey,
+        apiKey: trimmed,
         x402EvmNetwork: DEFAULT_X402_EVM_NETWORK,
     };
 }

package/dist/deeplink.d.ts

@@ -1,6 +1,6 @@
 export interface CursorMcpRemoteConfig {
     url: string;
-    headers: {
+    headers?: {
         'x-api-key': string;
     };
 }

package/dist/deeplink.js

@@ -1,9 +1,13 @@
 import { CONNECT_MCP_API_KEY_PLACEHOLDER, CONNECT_MCP_REMOTE_URL } from './metadata.js';
 export function buildCursorRemoteMcpConfig(apiKey = CONNECT_MCP_API_KEY_PLACEHOLDER) {
+    const trimmed = apiKey.trim();
+    if (!trimmed) {
+        return { url: CONNECT_MCP_REMOTE_URL };
+    }
     return {
         url: CONNECT_MCP_REMOTE_URL,
         headers: {
-            'x-api-key': apiKey,
+            'x-api-key': trimmed,
         },
     };
 }

package/dist/hosted-gate.d.ts

@@ -0,0 +1,21 @@
+import { AnonymousToolQuota } from './anonymous-quota.js';
+import { type HeaderCarrier } from './http-auth.js';
+export interface HostedMcpGateOk {
+    ok: true;
+    apiKey?: string;
+}
+export interface HostedMcpGateError {
+    ok: false;
+    status: number;
+    message: string;
+    code: number;
+    retryAfterSec?: number;
+}
+export type HostedMcpGateResult = HostedMcpGateOk | HostedMcpGateError;
+export interface HostedMcpGateRequest extends HeaderCarrier {
+    body?: unknown;
+}
+export declare function gateHostedMcpRequest(req: HostedMcpGateRequest, options: {
+    env?: NodeJS.ProcessEnv;
+    anonymousQuota: AnonymousToolQuota;
+}): HostedMcpGateResult;

package/dist/hosted-gate.js

@@ -0,0 +1,21 @@
+import { validateRequestApiKey } from './http-auth.js';
+export function gateHostedMcpRequest(req, options) {
+    const env = options.env ?? process.env;
+    const auth = validateRequestApiKey(req, env);
+    if (!auth.ok) {
+        return { ok: false, status: 401, message: auth.message, code: -32001 };
+    }
+    if (!auth.apiKey) {
+        const quota = options.anonymousQuota.consume(req.body);
+        if (!quota.allowed) {
+            return {
+                ok: false,
+                status: 429,
+                message: quota.message ?? 'Anonymous MCP quota exceeded.',
+                code: -32029,
+                retryAfterSec: quota.retryAfterSec,
+            };
+        }
+    }
+    return { ok: true, apiKey: auth.apiKey };
+}

package/dist/http-auth.d.ts

@@ -1,13 +1,16 @@
-import type { IncomingMessage } from 'node:http';
+import type { IncomingHttpHeaders } from 'node:http';
 export interface RequestApiKeyResult {
     ok: true;
-    apiKey: string;
+    apiKey?: string;
 }
 export interface RequestApiKeyError {
     ok: false;
     message: string;
 }
 export type RequestApiKeyValidation = RequestApiKeyResult | RequestApiKeyError;
-export declare function extractRequestApiKey(req: IncomingMessage): string | undefined;
+export interface HeaderCarrier {
+    headers: IncomingHttpHeaders;
+}
+export declare function extractRequestApiKey(req: HeaderCarrier): string | undefined;
 export declare function isPlaceholderApiKey(apiKey: string): boolean;
-export declare function validateRequestApiKey(req: IncomingMessage): RequestApiKeyValidation;
+export declare function validateRequestApiKey(req: HeaderCarrier, env?: NodeJS.ProcessEnv): RequestApiKeyValidation;

package/dist/http-auth.js

@@ -1,3 +1,4 @@
+import { isAnonymousMcpAllowed } from './config.js';
 import { CONNECT_MCP_API_KEY_PLACEHOLDER } from './metadata.js';
 const PLACEHOLDER_API_KEYS = new Set([
     'your-connect-api-key',
@@ -14,9 +15,12 @@ export function extractRequestApiKey(req) {
 export function isPlaceholderApiKey(apiKey) {
     return PLACEHOLDER_API_KEYS.has(apiKey);
 }
-export function validateRequestApiKey(req) {
+export function validateRequestApiKey(req, env = process.env) {
     const apiKey = extractRequestApiKey(req);
     if (!apiKey) {
+        if (isAnonymousMcpAllowed(env)) {
+            return { ok: true };
+        }
         return {
             ok: false,
             message: 'Missing x-api-key header. Get a key at https://connect.quid.li (Enable API access) and set it in your MCP headers.',

package/dist/jsonrpc.d.ts

@@ -0,0 +1,2 @@
+export declare function getJsonRpcMethod(body: unknown): string | undefined;
+export declare function getJsonRpcToolName(body: unknown): string | undefined;

package/dist/jsonrpc.js

@@ -0,0 +1,14 @@
+export function getJsonRpcMethod(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return undefined;
+    }
+    const method = body.method;
+    return typeof method === 'string' ? method : undefined;
+}
+export function getJsonRpcToolName(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return undefined;
+    }
+    const params = body.params;
+    return typeof params?.name === 'string' ? params.name : undefined;
+}

package/dist/metadata.js

@@ -3,7 +3,7 @@ export const CONNECT_MCP_REMOTE_URL = 'https://mcp.connect.quid.li';
 export const CONNECT_MCP_SERVER_INFO = {
     name: 'quidli-connect',
     title: 'Quidli Connect',
-    version: '0.1.0',
+    version: '0.4.0',
     websiteUrl: 'https://connect.quid.li',
     icons: [
         {

package/dist/mount.d.ts

@@ -1,7 +1,10 @@
 import type { IRouter } from 'express';
+import { AnonymousToolQuota } from './anonymous-quota.js';
 export { resolveRequestHost } from './request-host.js';
 export interface ConnectMcpMountOptions {
     baseUrl: string;
+    env?: NodeJS.ProcessEnv;
+    anonymousQuota?: AnonymousToolQuota;
 }
 export declare function resolveEmbeddedApiBaseUrl(port: number, env?: NodeJS.ProcessEnv): string;
 export declare function isConnectMcpHost(hostname: string, env?: NodeJS.ProcessEnv): boolean;

package/dist/mount.js

@@ -1,16 +1,20 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { createHostedClientConfig } from './config.js';
+import { AnonymousToolQuota } from './anonymous-quota.js';
+import { createHostedClientConfig, loadAnonymousQuotaConfig } from './config.js';
 import { createMcpServer } from './create-mcp-server.js';
-import { validateRequestApiKey } from './http-auth.js';
+import { gateHostedMcpRequest } from './hosted-gate.js';
 export { resolveRequestHost } from './request-host.js';
-function sendJsonRpcError(res, status, message) {
+function sendJsonRpcError(res, status, message, options) {
     if (res.headersSent) {
         return;
     }
+    if (options?.retryAfterSec) {
+        res.setHeader('Retry-After', String(options.retryAfterSec));
+    }
     res.status(status).json({
         jsonrpc: '2.0',
         error: {
-            code: -32001,
+            code: options?.code ?? -32001,
             message,
         },
         id: null,
@@ -37,6 +41,8 @@ export function isConnectMcpHost(hostname, env = process.env) {
 }
 export function mountConnectMcpHttp(router, options) {
     const { baseUrl } = options;
+    const env = options.env ?? process.env;
+    const anonymousQuota = options.anonymousQuota ?? AnonymousToolQuota.fromConfig(loadAnonymousQuotaConfig(env));
     router.get('/health', (_req, res) => {
         res.json({ ok: true, service: 'quidli-connect-mcp' });
     });
@@ -44,13 +50,16 @@ export function mountConnectMcpHttp(router, options) {
     // No in-memory session map, so Cloud Run restarts / multiple instances
     // never cause "Missing or invalid MCP session" errors.
     router.all('/', async (req, res) => {
-        const auth = validateRequestApiKey(req);
-        if (!auth.ok) {
-            sendJsonRpcError(res, 401, auth.message);
+        const gate = gateHostedMcpRequest(req, { env, anonymousQuota });
+        if (!gate.ok) {
+            sendJsonRpcError(res, gate.status, gate.message, {
+                code: gate.code,
+                retryAfterSec: gate.retryAfterSec,
+            });
             return;
         }
         try {
-            const server = createMcpServer(createHostedClientConfig(auth.apiKey, baseUrl));
+            const server = createMcpServer(createHostedClientConfig(gate.apiKey, baseUrl));
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // stateless — no session tracking
                 enableJsonResponse: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for Quidli Connect product APIs",
   "keywords": [
     "mcp",