@quidli/connect-mcp 0.5.7 → 0.5.9

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
 
 

package/dist/tools/register.js

@@ -11,37 +11,55 @@ export const CONNECT_MCP_TOOL_NAMES = [
     'connect_drop',
     'connect_drop_balance',
 ];
+/**
+ * Tool annotations. `readOnlyHint` is load-bearing, not decorative: clients
+ * auto-register Connect tools by it rather than by a hand-maintained allowlist,
+ * so an unannotated tool is not offered to a model at all. A tool that can move
+ * funds must never carry READ_ONLY.
+ */
+const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const SPENDS_FUNDS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
 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).', {}, 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).', {}, async () => client.request({ method: 'GET', path: '/chains', 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({
+    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_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',
         body: { recipients },
     }));
-    server.tool('connect_lookup_exposed', 'List platforms a recipient has exposed on Connect, with enriched profile, scores, and wallet addresses. Recipient may be a social account, an exposed wallet (EVM/Solana/smart wallet), or a Connect username. May require x402 payment when the profile owner charges for lookups.', lookupExposedInputSchema, async ({ recipient }) => client.request({
+    server.tool('connect_lookup_exposed', 'List platforms a recipient has exposed on Connect, with enriched profile, scores, and wallet addresses. Recipient may be a social account, an exposed wallet (EVM/Solana/smart wallet), or a Connect username. May require x402 payment when the profile owner charges for lookups.', lookupExposedInputSchema, READ_ONLY, 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 (quidli 0–100, neynar/lens 0–1, ethos 0–2800).', scoresBatchInputSchema, async ({ users, filter }) => client.request({
+    server.tool('connect_scores_batch', 'Batch scores for linked accounts or Connect usernames. Optional filter excludes users below minScore (quidli 0–100, neynar/lens 0–1, ethos 0–2800).', scoresBatchInputSchema, READ_ONLY, 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({
+    server.tool('connect_scores_by_account', 'Scores for a linked social account or wallet.', scoresByAccountInputSchema, READ_ONLY, 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({
+    server.tool('connect_scores_by_username', 'Scores by Connect public username.', scoresByUsernameInputSchema, READ_ONLY, async ({ username }) => client.request({
         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({
+    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.', {}, READ_ONLY, async () => client.request({
         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, async ({ ignoreFailedRecipients, ...body }) => client.request({
+    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({
         method: 'POST',
         path: '/drop',
         body,
@@ -50,7 +68,7 @@ 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, async ({ chainId }) => client.request({
+    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({
         method: 'GET',
         path: '/drop/balance',
         requireApiKey: true,

package/package.json

@@ -1,28 +1,30 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.5.7",
-  "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.5.9",
+  "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",