@quidli/connect-mcp 0.5.8 → 0.6.0

package/README.md

@@ -153,6 +153,17 @@ Without a key, `initialize` / `tools/list` always succeed. Anonymous `tools/call
 
 ---
 
+### Grok
+
+1. Go to [grok.com/connectors](https://grok.com/connectors) and select **Custom**.
+2. Enter the server URL: `https://mcp.connect.quid.li`
+
+This gives Grok access to the anonymous-tier tools -- lookup, scores, agent, and price -- under the shared quota.
+
+**Current limitation:** Grok's custom connector UI does not currently support attaching an API key or custom header. That means `connect_me`, `connect_drop`, and `connect_drop_balance` (all **API key only**) are not usable through Grok yet -- calls to them will return an unauthorized error. This isn't a `connect-mcp` limitation; it's Grok's custom-connector setup not exposing an auth field at this time.
+
+---
+
 ## Smithery
 
 If you already use [Smithery](https://smithery.ai/servers/quidli/connect), it will handle auth and sessions for you. Requires a Smithery account.
@@ -286,6 +297,67 @@ Credentials are optional in local mode. Without either variable, lookup/scores s
 
 ---
 
+## Troubleshooting
+
+### `npx` hangs with no output when run from a background service
+
+If you're launching `@quidli/connect-mcp` via `npx` from inside a background
+process manager -- a macOS `launchd` agent, a systemd unit, a supervisor, or
+any client config running without a normal interactive shell -- it can hang
+**indefinitely with zero output and no error**. This isn't a crash; `npx` is
+stuck resolving `PATH` in an environment that doesn't provide the same shell
+initialization an interactive terminal gets.
+
+**Workaround:** if you have [Bun](https://bun.sh) installed, use `bunx`
+instead of `npx`. It performs the same job -- running the package without a
+local install -- but doesn't hit this hang in restricted-`PATH` environments.
+
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "bunx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+If you're spawning the process yourself (rather than through a client's MCP
+config) and want to be resilient to `bunx` not being on `PATH` either,
+resolve it by absolute path first:
+
+```ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const BUNX_PATH = (() => {
+  const candidate = join(homedir(), ".bun", "bin", "bunx");
+  return existsSync(candidate) ? candidate : "bunx";
+})();
+
+const proc = spawn(BUNX_PATH, ["-y", "@quidli/connect-mcp"], {
+  stdio: ["pipe", "pipe", "pipe"],
+});
+```
+
+This isn't a general claim that Bun is better than npm -- it's a targeted fix
+for one specific, reproducible failure mode when `npx` is spawned outside an
+interactive shell.
+
+### Wrong environment variable name for the API key
+
+Double-check you're setting `CONNECT_API_KEY`, not `API_KEY` -- the server
+only reads `CONNECT_API_KEY`, and a mismatch here fails silently: your calls
+will run in anonymous/unauthenticated mode instead of erroring, which can
+look like a working-but-oddly-limited connection rather than a config
+mistake.
+
 ## Tools
 
 
@@ -299,7 +371,7 @@ Credentials are optional in local mode. Without either variable, lookup/scores s
 | `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`               | Smart Send (EVM batch or Solana SOL/SPL) — **API key only** |
 | `connect_drop_balance`       | Smart Send wallet balances on a chain — **API key only**  |
 
 

package/dist/schemas.js

@@ -83,25 +83,25 @@ export const scoresByUsernameInputSchema = {
     username: z.string().min(1),
 };
 export const dropBalanceInputSchema = {
-    chainId: z.number().int().describe('EVM chain ID (Smart Send supported chains only)'),
+    chainId: z.number().int().describe('EVM chain ID or 1399811149 for Solana mainnet (Smart Send)'),
 };
 export const dropInputSchema = {
     idempotencyKey: z.string().uuid(),
-    chainId: z.number().int().describe('EVM chain ID (Smart Send supported chains only)'),
+    chainId: z.number().int().describe('EVM chain ID or 1399811149 for Solana mainnet'),
     tokenContract: z
         .string()
         .nullable()
         .optional()
-        .describe('ERC-20 contract address. Omit or null for the chain native token (ETH, POL, AVAX). Do not use the zero address.'),
+        .describe('EVM ERC-20 contract or Solana SPL mint. Omit or null for the native token (ETH/POL/AVAX, or SOL on 1399811149). Do not use the zero address.'),
     recipients: z
         .array(linkedAccountSchema)
         .min(1)
-        .describe('Wallet or social recipients (all wallet or all social, no mix). Optional amountInWei per recipient uses the same smallest-unit rules as amountInWeiPerRecipient.'),
+        .describe('Wallet or social recipients (all wallet or all social, no mix). Optional amountInWei per recipient uses the same smallest-unit rules as amountInWeiPerRecipient. On Solana, wallet ids are base58 pubkeys; social lookup pays solWalletAddress.'),
     amountInWeiPerRecipient: z
         .string()
         .optional()
         .nullable()
-        .describe('Uniform amount in smallest units (wei). Native ETH uses 18 decimals; ERC-20 uses token decimals from connect_drop_balance (USDC usually 6). Omit when setting amountInWei on each recipient.'),
+        .describe('Uniform amount in smallest units. Native ETH uses 18 decimals; SOL uses 9; ERC-20/SPL uses token decimals from connect_drop_balance (USDC usually 6). Omit when setting amountInWei on each recipient.'),
     ignoreFailedRecipients: z
         .boolean()
         .optional()

package/dist/tools/register.js

@@ -31,7 +31,7 @@ const SPENDS_FUNDS = {
 };
 export function registerTools(server, client) {
     server.tool('connect_get_price', 'Get public x402 list prices for lookup and scores (reference only; live paywall amounts are in 402 responses).', {}, READ_ONLY, async () => client.request({ method: 'GET', path: '/price', authenticated: false }));
-    server.tool('connect_get_chains', 'List product chains with per-feature compatibility. lookup is true for EVM catalog chains and Solana; drop is true only for Smart Send EVM chains (use those chainIds for connect_drop / connect_drop_balance).', {}, READ_ONLY, async () => client.request({ method: 'GET', path: '/chains', authenticated: false }));
+    server.tool('connect_get_chains', 'List product chains with per-feature compatibility. lookup is true for EVM catalog chains and Solana; drop is true for Smart Send EVM chains and Solana (chainId 1399811149 for connect_drop / connect_drop_balance).', {}, READ_ONLY, async () => client.request({ method: 'GET', path: '/chains', authenticated: false }));
     server.tool('connect_lookup', 'Resolve social identities to EVM and Solana wallet addresses. Resolving a recipient who has no wallet provisions one for them, so this is read-only for the caller but not for the recipient. If status is processing, retry the same payload.', lookupInputSchema, READ_ONLY, async ({ recipients }) => client.request({
         method: 'POST',
         path: '/lookup',
@@ -59,7 +59,10 @@ export function registerTools(server, client) {
         method: 'GET',
         path: '/account/me',
     }));
-    server.tool('connect_drop', 'Execute a Smart Send (batch native or ERC-20 transfer). Omit tokenContract or set it to null for the chain native token (ETH on 1/8453/10/42161/480, POL on 137, AVAX on 43114); pass the ERC-20 contract address otherwise — do not use the zero address. Amounts are smallest-unit integer strings; use connect_drop_balance decimals (native ETH = 18, USDC usually 6). Returns 201 when submitted or 202 when recipients still processing — retry with the same idempotencyKey.', dropInputSchema, SPENDS_FUNDS, async ({ ignoreFailedRecipients, ...body }) => client.request({
+    server.tool('connect_drop', 'Execute a Smart Send from the API key owner Connect embedded wallet. EVM: batch native or ERC-20 (need native gas plus the token). Solana (chainId 1399811149): SOL or SPL from the Solana embedded wallet. Lookup social recipients and pay solWalletAddress, never ethWalletAddress. Omit tokenContract or set it to null for the native token; pass an ERC-20 contract or SPL mint otherwise — do not use the zero address. Amounts are smallest-unit integer strings (ETH 18 decimals, SOL 9, USDC usually 6). Packs up to 20 SOL or 10 SPL recipients per transaction. ' +
+        'Solana native (tokenContract null): no ATA. Sending to a new or empty wallet requires amount ≥ 890880 lamports (rent-exempt minimum for a system account); that SOL stays with the recipient. Below that the tx fails. Sender also pays a ~5000-lamport fee. ' +
+        'Solana SPL: tokens sit in Associated Token Accounts (ATA), not on the wallet pubkey. Recipients need not already hold the token — the API prepends CreateIdempotent. The sender (not the recipient) pays ~2039280 lamports (~0.002039 SOL) rent per newly created dest ATA, plus tx fees, on top of the token amount (which can be as small as 1 unit). A 400 "Insufficient funds" on SPL is often missing SOL for ATA rent, not missing USDC. Token-2022 is not supported; USDC mint is EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. ' +
+        'Always call connect_drop_balance first. Returns 201 when submitted or 202 when recipients still processing — retry with the same idempotencyKey.', dropInputSchema, SPENDS_FUNDS, async ({ ignoreFailedRecipients, ...body }) => client.request({
         method: 'POST',
         path: '/drop',
         body,
@@ -68,7 +71,9 @@ export function registerTools(server, client) {
             ? { 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, READ_ONLY, async ({ chainId }) => client.request({
+    server.tool('connect_drop_balance', 'Get native and token balances for the API key owner Smart Send embedded wallet on a chain. Always call before connect_drop. Zero balances are omitted, so a missing token means balance 0. ' +
+        'EVM: confirm native gas plus the ERC-20 being sent. ' +
+        'Solana (chainId 1399811149): SOL in this response is spendable lamports on the wallet pubkey (rent locked in existing token accounts is not included). Native SOL drop to a new/empty recipient: amount itself must be ≥ 890880 lamports and sender SOL must cover amount + ~5000 lamports fee. SPL drop: token balance ≥ total amount, and SOL ≥ tx fee + ~2039280 lamports (~0.002039 SOL) per recipient that may need a new Associated Token Account — even when sending USDC. Insufficient SOL for ATA rent fails before the token transfer.', dropBalanceInputSchema, READ_ONLY, async ({ chainId }) => client.request({
         method: 'GET',
         path: '/drop/balance',
         requireApiKey: true,

package/package.json

@@ -1,28 +1,30 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.5.8",
-  "description": "Identity and reputation for multiplayer agents: resolve social handles to wallet addresses, check reputation from public history, and send tokens from any MCP client.",
+  "version": "0.6.0",
+  "description": "MCP server for agent identity and reputation: resolve social handles to wallet addresses, score onchain reputation, and send USDC from any MCP client.",
   "keywords": [
     "mcp",
     "mcp-server",
     "model-context-protocol",
-    "ai",
-    "agent",
-    "web3-agent",
-    "agent-payments",
-    "multiplayer-agents",
+    "reputation",
+    "onchain-reputation",
     "identity",
     "identity-resolution",
-    "reputation",
-    "payments",
     "wallet",
+    "wallet-lookup",
+    "agent",
+    "ai",
+    "agent-payments",
+    "payments",
     "usdc",
-    "farcaster",
+    "crypto",
+    "web3-agent",
+    "multiplayer-agents",
     "x402",
     "ethereum",
     "solana",
     "base",
-    "crypto",
+    "farcaster",
     "claude",
     "cursor",
     "claude-desktop"
@@ -53,8 +55,8 @@
     "./http": "./dist/http.js"
   },
   "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build && chmod +x dist/index.js dist/index-http.js",
+    "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",