@quidli/connect-mcp 0.2.0 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ 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 **or** x402 pay-per-call                                                           |
+| **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                          |
 | **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          |
@@ -152,6 +152,26 @@ No API key. Authenticated calls pay automatically when the API returns HTTP 402.
 
 Use `84532` for Base Sepolia when pointing at a staging API.
 
+#### Option C — no credentials (lookup / scores / agent)
+
+The MCP process starts without `CONNECT_API_KEY` or `EVM_PRIVATE_KEY`. `connect_lookup`, `connect_scores_*`, `connect_agent_prompt`, and `connect_get_price` call the API without auth. That succeeds when x402 is disabled (price `0`, typical for local). On production with x402 enabled, those tools return HTTP 402 until you set a key or wallet.
+
+`connect_me`, `connect_drop`, and `connect_drop_balance` still require `CONNECT_API_KEY`.
+
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_BASE_URL": "http://127.0.0.1:3011"
+      }
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
 1. Open **Claude → Settings → Developer → Edit Config** (enable Developer mode first if you do not see it).
@@ -199,7 +219,7 @@ Use `84532` for Base Sepolia when pointing at a staging API.
 
 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.
+Credentials are optional in local mode. Without either variable, lookup/scores/agent still work when the API does not charge x402. `connect_me` and Smart Send tools require `CONNECT_API_KEY`.
 
 ---
 
@@ -210,10 +230,13 @@ At least one of `CONNECT_API_KEY` or `EVM_PRIVATE_KEY` is required for local mod
 | ---------------------------- | --------------------------------------------------------- |
 | `connect_get_price`          | List reference prices (no auth)                           |
 | `connect_lookup`             | Resolve social identities to EVM and SOL wallet addresses |
+| `connect_lookup_exposed`     | List platforms a recipient has exposed on Connect         |
 | `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_me`                 | API key owner profile, scores, and linked accounts — **API key only** |
 | `connect_drop`               | Smart Send (batch token transfer) — **API key only**      |
+| `connect_drop_balance`       | Smart Send wallet balances on a chain — **API key only**  |
 | `connect_agent_prompt`       | Natural-language agent for recipients discovery           |
 
 

package/dist/client.d.ts

@@ -6,6 +6,8 @@ export interface ConnectRequestOptions {
     method: HttpMethod;
     path: string;
     authenticated?: boolean;
+    /** Fail before calling the API when CONNECT_API_KEY is unset (Smart Send /me). */
+    requireApiKey?: boolean;
     body?: unknown;
     query?: Record<string, string | undefined>;
     timeoutMs?: number;

package/dist/client.js

@@ -7,7 +7,7 @@ export class ConnectClient {
     paidFetch;
     constructor(config) {
         this.config = config;
-        this.authMode = config.apiKey ? 'api-key' : 'x402';
+        this.authMode = config.evmPrivateKey && !config.apiKey ? 'x402' : 'api-key';
         if (!config.apiKey && config.evmPrivateKey) {
             this.paidFetch = createPaidFetch(config.evmPrivateKey, config.x402EvmNetwork);
         }
@@ -21,6 +21,9 @@ export class ConnectClient {
     async request(options) {
         const { method, path, body, query, timeoutMs } = options;
         const authenticated = options.authenticated ?? true;
+        if (options.requireApiKey && !this.config.apiKey) {
+            return errorResult('This tool requires CONNECT_API_KEY. Get a key at https://connect.quid.li (Enable API access). x402 wallet auth is not supported for this action.');
+        }
         const url = new URL(path, `${this.config.baseUrl}/`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {

package/dist/config.d.ts

@@ -13,7 +13,11 @@ 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). */
+/**
+ * Stdio MCP: credentials are optional.
+ * Lookup/scores/agent work without auth when the API allows it (x402 price 0)
+ * 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;

package/dist/config.js

@@ -23,14 +23,15 @@ export function loadHttpServerConfig(env = process.env) {
     }
     return { host, port, baseUrl: loadBaseUrl(env) };
 }
-/** Stdio MCP: CONNECT_API_KEY and/or EVM_PRIVATE_KEY (at least one required). */
+/**
+ * Stdio MCP: credentials are optional.
+ * Lookup/scores/agent work without auth when the API allows it (x402 price 0)
+ * or with CONNECT_API_KEY / EVM_PRIVATE_KEY. /account/me and /drop require an API key.
+ */
 export function loadConfig(env = process.env) {
     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.');
-    }
     return {
         baseUrl: loadBaseUrl(env),
         apiKey,

package/dist/schemas.d.ts

@@ -28,6 +28,21 @@ export declare const lookupInputSchema: {
         username: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
 };
+export declare const lookupExposedInputSchema: {
+    recipient: z.ZodObject<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>;
+};
 export declare const scoresBatchInputSchema: {
     users: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
@@ -60,6 +75,9 @@ export declare const scoresByAccountInputSchema: {
 export declare const scoresByUsernameInputSchema: {
     username: z.ZodString;
 };
+export declare const dropBalanceInputSchema: {
+    chainId: z.ZodNumber;
+};
 export declare const dropInputSchema: {
     idempotencyKey: z.ZodString;
     chainId: z.ZodNumber;

package/dist/schemas.js

@@ -26,6 +26,9 @@ export const lookupInputSchema = {
         .min(1)
         .describe('Recipients to resolve to EVM/Solana wallets'),
 };
+export const lookupExposedInputSchema = {
+    recipient: linkedAccountSchema.describe('Recipient whose exposed linked accounts and Connect profile should be listed'),
+};
 export const scoresBatchInputSchema = {
     users: z.array(linkedAccountSchema).min(1).describe('Users to fetch scores for'),
     filter: z
@@ -59,6 +62,9 @@ export const scoresByAccountInputSchema = {
 export const scoresByUsernameInputSchema = {
     username: z.string().min(1),
 };
+export const dropBalanceInputSchema = {
+    chainId: z.number().int().describe('EVM chain ID (Smart Send supported chains only)'),
+};
 export const dropInputSchema = {
     idempotencyKey: z.string().uuid(),
     chainId: z.number().int(),

package/dist/tools/register.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ConnectClient } from '../client.js';
-export declare const CONNECT_MCP_TOOL_NAMES: readonly ["connect_get_price", "connect_lookup", "connect_scores_batch", "connect_scores_by_account", "connect_scores_by_username", "connect_drop", "connect_agent_prompt"];
+export declare const CONNECT_MCP_TOOL_NAMES: readonly ["connect_get_price", "connect_lookup", "connect_lookup_exposed", "connect_scores_batch", "connect_scores_by_account", "connect_scores_by_username", "connect_me", "connect_drop", "connect_drop_balance", "connect_agent_prompt"];
 export declare function registerTools(server: McpServer, client: ConnectClient): void;

package/dist/tools/register.js

@@ -1,12 +1,15 @@
-import { agentPromptInputSchema, dropInputSchema, lookupInputSchema, scoresBatchInputSchema, scoresByAccountInputSchema, scoresByUsernameInputSchema, } from '../schemas.js';
+import { agentPromptInputSchema, dropBalanceInputSchema, dropInputSchema, lookupExposedInputSchema, lookupInputSchema, scoresBatchInputSchema, scoresByAccountInputSchema, scoresByUsernameInputSchema, } from '../schemas.js';
 const AGENT_TIMEOUT_MS = 65_000;
 export const CONNECT_MCP_TOOL_NAMES = [
     'connect_get_price',
     'connect_lookup',
+    'connect_lookup_exposed',
     'connect_scores_batch',
     'connect_scores_by_account',
     'connect_scores_by_username',
+    'connect_me',
     'connect_drop',
+    'connect_drop_balance',
     'connect_agent_prompt',
 ];
 export function registerTools(server, client) {
@@ -16,6 +19,11 @@ export function registerTools(server, client) {
         path: '/lookup',
         body: { recipients },
     }));
+    server.tool('connect_lookup_exposed', 'List platforms a recipient has exposed on Connect, with enriched profile, scores, and wallet addresses. May require x402 payment when the profile owner charges for lookups.', lookupExposedInputSchema, async ({ recipient }) => client.request({
+        method: 'POST',
+        path: '/lookup/exposed',
+        body: { recipient },
+    }));
     server.tool('connect_scores_batch', 'Batch scores for linked accounts or Connect usernames. Optional filter excludes users below minScore.', scoresBatchInputSchema, async ({ users, filter }) => client.request({
         method: 'POST',
         path: '/scores',
@@ -29,14 +37,25 @@ export function registerTools(server, client) {
         method: 'GET',
         path: `/scores/u/${encodeURIComponent(username.trim())}`,
     }));
+    server.tool('connect_me', 'Get the Connect profile, scores, and all linked accounts for the API key owner. Use to identify which user the key belongs to.', {}, async () => client.request({
+        method: 'GET',
+        path: '/account/me',
+    }));
     server.tool('connect_drop', 'Execute a Smart Send (batch token transfer). Returns 201 when submitted or 202 when recipients still processing — retry with same idempotencyKey.', dropInputSchema, async ({ ignoreFailedRecipients, ...body }) => client.request({
         method: 'POST',
         path: '/drop',
         body,
+        requireApiKey: true,
         query: ignoreFailedRecipients === true
             ? { ignoreFailedRecipients: 'true' }
             : undefined,
     }));
+    server.tool('connect_drop_balance', 'Get native and ERC-20 balances for the API key owner Smart Send embedded wallet on a chain. Use before connect_drop to verify gas and token funds.', dropBalanceInputSchema, async ({ chainId }) => client.request({
+        method: 'GET',
+        path: '/drop/balance',
+        requireApiKey: true,
+        query: { chainId: String(chainId) },
+    }));
     server.tool('connect_agent_prompt', 'Natural-language agent turn for Farcaster/Lens cohort discovery. Blocking up to 60s. Omit sessionId to start; include to continue. Do not send requester.', agentPromptInputSchema, async ({ prompt, sessionId }) => client.request({
         method: 'POST',
         path: '/agent',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for Quidli Connect product APIs",
   "keywords": [
     "mcp",
@@ -39,8 +39,8 @@
     "./http": "./dist/http.js"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js dist/index-http.js",
-    "prepublishOnly": "npm run build",
+    "build": "tsc",
+    "prepublishOnly": "npm run build && chmod +x dist/index.js dist/index-http.js",
     "start": "node dist/index.js",
     "start:http": "node dist/index-http.js",
     "test": "vitest run",