@quidli/connect-mcp 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# @quidli/connect-mcp
+
+MCP server exposing [Quidli Connect](https://connect.quid.li) product APIs as tools for Cursor, Claude Desktop, and other MCP hosts.
+
+## Requirements
+
+- Node.js 20+
+- A Connect API key ([Enable API access](https://connect.quid.li))
+
+## Cursor configuration
+
+### Remote URL (recommended for production)
+
+Same pattern as GitHub MCP — Cursor connects to a hosted endpoint and sends your API key in headers:
+
+```json
+{
+  "mcpServers": {
+    "connect": {
+      "url": "https://mcp.connect.quid.li",
+      "headers": {
+        "x-api-key": "set-your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+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):
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkIiwiaGVhZGVycyI6eyJ4LWFwaS1rZXkiOiJzZXQteW91ci1hcGkta2V5LWhlcmUifX0=
+```
+
+Or generate programmatically:
+
+```typescript
+import { buildCursorMcpInstallDeeplink } from '@quidli/connect-mcp/deeplink';
+// buildCursorMcpInstallDeeplink() in published package once exported — see src/deeplink.ts
+```
+
+### Local stdio (npm / development)
+
+Add to `.cursor/mcp.json` (or global MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_KEY": "<your-api-key>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li"
+      }
+    }
+  }
+}
+```
+
+For local development from this monorepo:
+
+```json
+{
+  "mcpServers": {
+    "connect-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/connect-backend/packages/connect-mcp/dist/index.js"],
+      "env": {
+        "CONNECT_API_KEY": "<your-api-key>",
+        "CONNECT_API_BASE_URL": "https://api.staging.connect.quid.li"
+      }
+    }
+  }
+}
+```
+
+`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.
+
+## HTTP server (hosted deployment)
+
+### Embedded in connect-backend (production)
+
+MCP runs inside the **same Cloud Run service** as `api.connect.quid.li`. Map `mcp.connect.quid.li` as an additional custom domain on that service. Requests with MCP `Host` headers are routed to the MCP handler; API traffic is unchanged.
+
+See `docs/ai/deployment/feature-connect-api-mcp.md` in connect-backend for DNS, env vars, and smoke tests.
+
+### Standalone binary (local / debugging)
+
+```bash
+cd packages/connect-mcp
+npm run build
+CONNECT_API_BASE_URL=https://api.connect.quid.li npm run start:http
+```
+
+Environment:
+
+| 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 |
+
+Health check: `GET /health`
+
+## Tools (7)
+
+| 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 |
+
+Not exposed: `POST /lookup/exposed`, agent feedback, member/admin routes.
+
+## 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`.
+
+## Development
+
+```bash
+cd packages/connect-mcp
+npm install
+npm test
+npm run build
+CONNECT_API_KEY=<key> npm start
+```
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+(Requires `@quidli` npm org access.)

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { ConnectClientConfig } from './config.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export type HttpMethod = 'GET' | 'POST';
+export interface ConnectRequestOptions {
+    method: HttpMethod;
+    path: string;
+    authenticated?: boolean;
+    body?: unknown;
+    query?: Record<string, string | undefined>;
+    timeoutMs?: number;
+}
+export declare class ConnectClient {
+    private readonly config;
+    constructor(config: ConnectClientConfig);
+    request(options: ConnectRequestOptions): Promise<CallToolResult>;
+}

package/dist/client.js

@@ -0,0 +1,64 @@
+import { mapHttpError } from './errors.js';
+import { errorResult, successResult } from './result.js';
+export class ConnectClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(options) {
+        const { method, path, body, query, timeoutMs } = options;
+        const authenticated = options.authenticated ?? true;
+        const url = new URL(path, `${this.config.baseUrl}/`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const headers = {
+            accept: 'application/json',
+        };
+        if (authenticated) {
+            headers['x-api-key'] = this.config.apiKey;
+        }
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        const controller = new AbortController();
+        const timeout = timeoutMs
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : undefined;
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            const raw = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                if (response.status === 504) {
+                    return errorResult(mapHttpError(504, raw));
+                }
+                return errorResult(mapHttpError(response.status, raw));
+            }
+            return successResult({
+                httpStatus: response.status,
+                ...(typeof raw === 'object' && raw !== null ? raw : { data: raw }),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                return errorResult('Request timed out');
+            }
+            const message = error instanceof Error ? error.message : 'Network error';
+            return errorResult(message);
+        }
+        finally {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface ConnectClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface HttpServerConfig {
+    host: string;
+    port: number;
+    baseUrl: string;
+}
+export declare function loadHttpServerConfig(env?: NodeJS.ProcessEnv): HttpServerConfig;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ConnectClientConfig;

package/dist/config.js

@@ -0,0 +1,21 @@
+const DEFAULT_BASE_URL = 'https://api.connect.quid.li';
+const DEFAULT_HTTP_HOST = '0.0.0.0';
+const DEFAULT_HTTP_PORT = 8080;
+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);
+    const port = Number(portRaw);
+    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 };
+}
+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 baseUrl = (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
+    return { apiKey, baseUrl };
+}

package/dist/create-mcp-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ConnectClientConfig } from './config.js';
+export declare function createMcpServer(config: ConnectClientConfig): McpServer;

package/dist/create-mcp-server.js

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ConnectClient } from './client.js';
+import { CONNECT_MCP_SERVER_INFO } from './metadata.js';
+import { registerTools } from './tools/register.js';
+export function createMcpServer(config) {
+    const server = new McpServer({
+        ...CONNECT_MCP_SERVER_INFO,
+    });
+    const client = new ConnectClient(config);
+    registerTools(server, client);
+    return server;
+}

package/dist/deeplink.d.ts

@@ -0,0 +1,8 @@
+export interface CursorMcpRemoteConfig {
+    url: string;
+    headers: {
+        'x-api-key': string;
+    };
+}
+export declare function buildCursorRemoteMcpConfig(apiKey?: string): CursorMcpRemoteConfig;
+export declare function buildCursorMcpInstallDeeplink(serverName?: string, config?: CursorMcpRemoteConfig): string;

package/dist/deeplink.js

@@ -0,0 +1,13 @@
+import { CONNECT_MCP_API_KEY_PLACEHOLDER, CONNECT_MCP_REMOTE_URL } from './metadata.js';
+export function buildCursorRemoteMcpConfig(apiKey = CONNECT_MCP_API_KEY_PLACEHOLDER) {
+    return {
+        url: CONNECT_MCP_REMOTE_URL,
+        headers: {
+            'x-api-key': apiKey,
+        },
+    };
+}
+export function buildCursorMcpInstallDeeplink(serverName = '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

@@ -0,0 +1,2 @@
+export declare function parseNestErrorMessage(body: unknown): string;
+export declare function mapHttpError(status: number, body: unknown): string;

package/dist/errors.js

@@ -0,0 +1,31 @@
+export function parseNestErrorMessage(body) {
+    if (body && typeof body === 'object' && 'message' in body) {
+        const message = body.message;
+        if (Array.isArray(message)) {
+            return message.map(String).join(' ');
+        }
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    return 'Request failed';
+}
+export function mapHttpError(status, body) {
+    const detail = parseNestErrorMessage(body);
+    switch (status) {
+        case 400:
+            return detail;
+        case 401:
+            return `Unauthorized: ${detail}. Verify CONNECT_API_KEY at https://connect.quid.li`;
+        case 402:
+            return `Payment required (${detail}). MCP requires a valid Connect API key — x402 is not supported in MCP.`;
+        case 404:
+            return detail;
+        case 504:
+            return detail === 'Request failed'
+                ? 'Upstream agent did not respond within 60 seconds'
+                : detail;
+        default:
+            return status >= 500 ? `Connect API error (${status}): ${detail}` : detail;
+    }
+}

package/dist/http-auth.d.ts

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

package/dist/http-auth.js

@@ -0,0 +1,32 @@
+import { CONNECT_MCP_API_KEY_PLACEHOLDER } from './metadata.js';
+const PLACEHOLDER_API_KEYS = new Set([
+    'your-connect-api-key',
+    '<your-api-key>',
+    'set-your-api-key-here',
+    ...(CONNECT_MCP_API_KEY_PLACEHOLDER ? [CONNECT_MCP_API_KEY_PLACEHOLDER] : []),
+]);
+export function extractRequestApiKey(req) {
+    const raw = req.headers['x-api-key'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+}
+export function isPlaceholderApiKey(apiKey) {
+    return PLACEHOLDER_API_KEYS.has(apiKey);
+}
+export function validateRequestApiKey(req) {
+    const apiKey = extractRequestApiKey(req);
+    if (!apiKey) {
+        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.',
+        };
+    }
+    if (isPlaceholderApiKey(apiKey)) {
+        return {
+            ok: false,
+            message: 'Invalid API key. Set your Connect API key in Cursor MCP settings (headers.x-api-key). Get one at https://connect.quid.li',
+        };
+    }
+    return { ok: true, apiKey };
+}

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+export { isConnectMcpHost, mountConnectMcpHttp, resolveEmbeddedApiBaseUrl } from './mount.js';
+export declare function main(): Promise<void>;

package/dist/http.js

@@ -0,0 +1,19 @@
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { loadHttpServerConfig } from './config.js';
+import { mountConnectMcpHttp } from './mount.js';
+export { isConnectMcpHost, mountConnectMcpHttp, resolveEmbeddedApiBaseUrl } from './mount.js';
+export async function main() {
+    const { host, port, baseUrl } = loadHttpServerConfig();
+    const app = createMcpExpressApp({ host, allowedHosts: ['mcp.connect.quid.li', 'localhost'] });
+    mountConnectMcpHttp(app, { baseUrl });
+    await new Promise((resolve, reject) => {
+        app.listen(port, host, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            console.log(`Quidli Connect MCP HTTP server listening on http://${host}:${port}/`);
+            resolve();
+        });
+    });
+}

package/dist/index-http.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index-http.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from './http.js';
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from './server.js';
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/metadata.d.ts

@@ -0,0 +1,13 @@
+export declare const CONNECT_MCP_API_KEY_PLACEHOLDER = "";
+export declare const CONNECT_MCP_REMOTE_URL = "https://mcp.connect.quid.li";
+export declare const CONNECT_MCP_SERVER_INFO: {
+    name: string;
+    title: string;
+    version: string;
+    websiteUrl: string;
+    icons: {
+        src: string;
+        mimeType: string;
+        sizes: string[];
+    }[];
+};

package/dist/metadata.js

@@ -0,0 +1,20 @@
+export const CONNECT_MCP_API_KEY_PLACEHOLDER = '';
+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',
+    websiteUrl: 'https://connect.quid.li',
+    icons: [
+        {
+            src: 'https://connect.quid.li/theme/dark/squid.png',
+            mimeType: 'image/png',
+            sizes: ['48x48'],
+        },
+        {
+            src: 'https://assets.quid.li/icons/quidli/quidli_square.png',
+            mimeType: 'image/png',
+            sizes: ['64x64'],
+        },
+    ],
+};

package/dist/mount.d.ts

@@ -0,0 +1,8 @@
+import type { IRouter } from 'express';
+export { resolveRequestHost } from './request-host.js';
+export interface ConnectMcpMountOptions {
+    baseUrl: string;
+}
+export declare function resolveEmbeddedApiBaseUrl(port: number, env?: NodeJS.ProcessEnv): string;
+export declare function isConnectMcpHost(hostname: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function mountConnectMcpHttp(router: IRouter, options: ConnectMcpMountOptions): void;

package/dist/mount.js

@@ -0,0 +1,70 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpServer } from './create-mcp-server.js';
+import { validateRequestApiKey } from './http-auth.js';
+export { resolveRequestHost } from './request-host.js';
+function sendJsonRpcError(res, status, message) {
+    if (res.headersSent) {
+        return;
+    }
+    res.status(status).json({
+        jsonrpc: '2.0',
+        error: {
+            code: -32001,
+            message,
+        },
+        id: null,
+    });
+}
+export function resolveEmbeddedApiBaseUrl(port, env = process.env) {
+    const fromEnv = env.CONNECT_MCP_API_BASE_URL?.trim() || env.CONNECT_API_BASE_URL?.trim();
+    if (fromEnv) {
+        return fromEnv.replace(/\/$/, '');
+    }
+    return `http://127.0.0.1:${port}`;
+}
+export function isConnectMcpHost(hostname, env = process.env) {
+    const configured = env.CONNECT_MCP_HOSTS?.split(',')
+        .map((host) => host.trim().toLowerCase())
+        .filter(Boolean);
+    const normalized = hostname.toLowerCase();
+    if (configured?.length) {
+        return configured.includes(normalized);
+    }
+    return (normalized === 'mcp.connect.quid.li' ||
+        normalized === 'mcp.staging.connect.quid.li' ||
+        normalized.endsWith('.mcp.connect.quid.li'));
+}
+export function mountConnectMcpHttp(router, options) {
+    const { baseUrl } = options;
+    router.get('/health', (_req, res) => {
+        res.json({ ok: true, service: 'quidli-connect-mcp' });
+    });
+    // Stateless mode: each request creates a fresh server+transport.
+    // 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);
+            return;
+        }
+        try {
+            const server = createMcpServer({ apiKey: auth.apiKey, baseUrl });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless — no session tracking
+                enableJsonResponse: true,
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            res.on('close', () => {
+                transport.close().catch(() => undefined);
+                server.close().catch(() => undefined);
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Internal server error';
+            console.error('MCP HTTP error:', message);
+            sendJsonRpcError(res, 500, message);
+        }
+    });
+}

package/dist/request-host.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function resolveRequestHost(req: IncomingMessage): string;

package/dist/request-host.js

@@ -0,0 +1,13 @@
+export function resolveRequestHost(req) {
+    const forwarded = req.headers['x-forwarded-host'];
+    const forwardedHost = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    if (forwardedHost) {
+        return forwardedHost.split(',')[0]?.trim().split(':')[0]?.toLowerCase() ?? '';
+    }
+    const host = req.headers.host;
+    if (host) {
+        return host.split(':')[0]?.toLowerCase() ?? '';
+    }
+    const hostname = 'hostname' in req && typeof req.hostname === 'string' ? req.hostname : '';
+    return hostname.toLowerCase();
+}

package/dist/result.d.ts

@@ -0,0 +1,3 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare function successResult(data: unknown): CallToolResult;
+export declare function errorResult(message: string): CallToolResult;

package/dist/result.js

@@ -0,0 +1,11 @@
+export function successResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function errorResult(message) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+    };
+}

package/dist/schemas.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/** Unified recipient — API validates fully; MCP forwards JSON. */
+export declare const linkedAccountSchema: 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 lookupInputSchema: {
+    recipients: z.ZodArray<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">>, "many">;
+};
+export declare const scoresBatchInputSchema: {
+    users: z.ZodArray<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">>, "many">;
+    filter: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["quidli_score", "lens_score", "neynar_score", "ethos_twitter_reputation", "ethos_wallet_reputation"]>;
+        minScore: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "quidli_score" | "lens_score" | "neynar_score" | "ethos_twitter_reputation" | "ethos_wallet_reputation";
+        minScore: number;
+    }, {
+        type: "quidli_score" | "lens_score" | "neynar_score" | "ethos_twitter_reputation" | "ethos_wallet_reputation";
+        minScore: number;
+    }>>;
+};
+export declare const scoresByAccountInputSchema: {
+    platform: z.ZodEnum<["wallet", "email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack"]>;
+    identifier: z.ZodString;
+};
+export declare const scoresByUsernameInputSchema: {
+    username: z.ZodString;
+};
+export declare const dropInputSchema: {
+    idempotencyKey: z.ZodString;
+    chainId: z.ZodNumber;
+    tokenContract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    recipients: z.ZodArray<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">>, "many">;
+    amountInWeiPerRecipient: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    ignoreFailedRecipients: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const agentPromptInputSchema: {
+    prompt: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+};

package/dist/schemas.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+const recipientTypeSchema = z.enum([
+    'email',
+    'phone',
+    'telegram',
+    'discord',
+    'farcaster',
+    'twitter',
+    'github',
+    'linkedin',
+    'slack',
+    'wallet',
+    'username',
+]);
+/** Unified recipient — API validates fully; MCP forwards JSON. */
+export const linkedAccountSchema = z
+    .object({
+    type: recipientTypeSchema,
+    id: z.string().optional(),
+    username: z.string().optional(),
+})
+    .passthrough();
+export const lookupInputSchema = {
+    recipients: z
+        .array(linkedAccountSchema)
+        .min(1)
+        .describe('Recipients to resolve to EVM/Solana wallets'),
+};
+export const scoresBatchInputSchema = {
+    users: z.array(linkedAccountSchema).min(1).describe('Users to fetch scores for'),
+    filter: z
+        .object({
+        type: z.enum([
+            'quidli_score',
+            'lens_score',
+            'neynar_score',
+            'ethos_twitter_reputation',
+            'ethos_wallet_reputation',
+        ]),
+        minScore: z.number(),
+    })
+        .optional(),
+};
+export const scoresByAccountInputSchema = {
+    platform: z.enum([
+        'wallet',
+        'email',
+        'phone',
+        'telegram',
+        'discord',
+        'farcaster',
+        'twitter',
+        'github',
+        'linkedin',
+        'slack',
+    ]),
+    identifier: z.string().min(1),
+};
+export const scoresByUsernameInputSchema = {
+    username: z.string().min(1),
+};
+export const dropInputSchema = {
+    idempotencyKey: z.string().uuid(),
+    chainId: z.number().int(),
+    tokenContract: z.string().nullable().optional(),
+    recipients: z.array(linkedAccountSchema).min(1),
+    amountInWeiPerRecipient: z.string().optional().nullable(),
+    ignoreFailedRecipients: z.boolean().optional(),
+};
+export const agentPromptInputSchema = {
+    prompt: z.string().min(1).max(4000),
+    sessionId: z.string().uuid().optional(),
+};

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,9 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMcpServer } from './create-mcp-server.js';
+import { loadConfig } from './config.js';
+export async function main() {
+    const config = loadConfig();
+    const server = createMcpServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools/register.d.ts

@@ -0,0 +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 function registerTools(server: McpServer, client: ConnectClient): void;

package/dist/tools/register.js

@@ -0,0 +1,49 @@
+import { agentPromptInputSchema, dropInputSchema, 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_scores_batch',
+    'connect_scores_by_account',
+    'connect_scores_by_username',
+    'connect_drop',
+    'connect_agent_prompt',
+];
+export function registerTools(server, client) {
+    server.tool('connect_get_price', 'Get public x402 list prices for lookup, scores, and agent (reference only; live paywall amounts are in 402 responses).', {}, async () => client.request({ method: 'GET', path: '/price', authenticated: false }));
+    server.tool('connect_lookup', 'Resolve social identities to EVM and Solana wallet addresses. If status is processing, retry the same payload.', lookupInputSchema, async ({ recipients }) => client.request({
+        method: 'POST',
+        path: '/lookup',
+        body: { recipients },
+    }));
+    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',
+        body: { users, ...(filter ? { filter } : {}) },
+    }));
+    server.tool('connect_scores_by_account', 'Scores for a linked social account or wallet.', scoresByAccountInputSchema, async ({ platform, identifier }) => client.request({
+        method: 'GET',
+        path: `/scores/${encodeURIComponent(platform)}/${encodeURIComponent(identifier)}`,
+    }));
+    server.tool('connect_scores_by_username', 'Scores by Connect public username.', scoresByUsernameInputSchema, async ({ username }) => client.request({
+        method: 'GET',
+        path: `/scores/u/${encodeURIComponent(username.trim())}`,
+    }));
+    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,
+        query: ignoreFailedRecipients === true
+            ? { ignoreFailedRecipients: 'true' }
+            : undefined,
+    }));
+    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',
+        body: {
+            prompt,
+            ...(sessionId ? { sessionId } : {}),
+        },
+        timeoutMs: AGENT_TIMEOUT_MS,
+    }));
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@quidli/connect-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Quidli Connect product APIs",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "quidli",
+    "connect",
+    "web3",
+    "identity",
+    "ai",
+    "agent"
+  ],
+  "homepage": "https://connect.quid.li",
+  "author": {
+    "name": "Quidli",
+    "url": "https://quid.xyz"
+  },
+  "type": "module",
+  "bin": {
+    "connect-mcp": "dist/index.js",
+    "connect-mcp-http": "dist/index-http.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./mount": "./dist/mount.js",
+    "./http": "./dist/http.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js dist/index-http.js",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index-http.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "express": "^5.2.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}