@agentvalet/mcp-server 0.3.7 → 0.3.10

package/dist/bind.js

@@ -0,0 +1,149 @@
+// First-run invite bind for AgentValet MCP server.
+//
+// Triggered when INVITE_BIND_SECRET is set in env and no agent identity
+// (AGENT_ID + private key) is yet available. We generate an RSA-2048
+// keypair locally, POST the public key + bind_secret to /v1/invites/bind,
+// and persist the returned identity + private key to ~/.agentvalet/.
+//
+// The bind_secret is one-shot, with a 30-minute TTL — the proxy returns
+// 410 on replay. We DO NOT retry, because a 410 either means the secret
+// was already consumed by an earlier run (so the identity should already
+// be on disk) or it expired (the invitee needs a re-issue).
+//
+// Persistence layout (created with permission 0700 on the parent dir):
+//   ~/.agentvalet/agent.key   PEM-encoded private key, mode 0600
+//   ~/.agentvalet/agent.json  { agent_id, owner_id, proxy_url, bound_at }
+import { generateKeyPairSync } from "node:crypto";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const AGENTVALET_DIR = join(homedir(), ".agentvalet");
+const KEY_PATH = join(AGENTVALET_DIR, "agent.key");
+const IDENTITY_PATH = join(AGENTVALET_DIR, "agent.json");
+export function getAgentvaletDir() {
+    return AGENTVALET_DIR;
+}
+export function getKeyPath() {
+    return KEY_PATH;
+}
+export function getIdentityPath() {
+    return IDENTITY_PATH;
+}
+/**
+ * Reads a previously-bound identity from disk, if one exists. Returns
+ * null when the file is absent or unparseable — callers should treat
+ * that as "no identity yet, proceed with bind".
+ */
+export function readBoundIdentity() {
+    if (!existsSync(IDENTITY_PATH))
+        return null;
+    try {
+        const raw = readFileSync(IDENTITY_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.agent_id === "string" &&
+            typeof parsed.owner_id === "string" &&
+            typeof parsed.proxy_url === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the disk-stored private key PEM if present, otherwise null.
+ */
+export function readBoundPrivateKey() {
+    if (!existsSync(KEY_PATH))
+        return null;
+    try {
+        return readFileSync(KEY_PATH, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generates an RSA-2048 keypair, POSTs the public key + bind_secret to
+ * the proxy, and persists both the returned identity and the private
+ * key to ~/.agentvalet/.
+ *
+ * Caller is responsible for deciding when to invoke (e.g. only when
+ * INVITE_BIND_SECRET is set and no identity already exists on disk).
+ */
+export async function attemptInviteBind(opts) {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const url = `${opts.proxyUrl.replace(/\/$/, "")}/v1/invites/bind`;
+    // 15s hard timeout: Claude Desktop kills the transport at ~12-15s of
+    // silence. If the proxy hangs, fail visibly with stderr rather than
+    // letting the host record an unexplained "transport closed".
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 15_000);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                bind_secret: opts.bindSecret,
+                public_key_pem: publicKey,
+            }),
+            signal: ac.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error("Bind request timed out after 15s — proxy unreachable or slow.");
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            if (body.error)
+                detail = body.error;
+        }
+        catch {
+            // ignore
+        }
+        if (res.status === 410) {
+            throw new Error(`Bind secret rejected (${detail}). It was either already used or expired — ask the inviting manager to re-issue.`);
+        }
+        throw new Error(`Invite bind failed: ${detail}`);
+    }
+    const payload = await res.json();
+    if (!payload.agent_id || !payload.owner_id || !payload.proxy_url) {
+        throw new Error("Bind succeeded but response was missing required fields");
+    }
+    const identity = {
+        agent_id: payload.agent_id,
+        owner_id: payload.owner_id,
+        proxy_url: payload.proxy_url,
+        bound_at: new Date().toISOString(),
+    };
+    persistBindArtifacts(identity, privateKey);
+    return { identity, privateKeyPem: privateKey };
+}
+/**
+ * Writes the private key + identity to ~/.agentvalet/. The directory
+ * is created with 0700 if it does not yet exist; the key file is
+ * written with 0600. Identity is non-secret (no token material) but
+ * we keep it inside the same directory for cleanup symmetry.
+ *
+ * Exposed so tests can verify the on-disk layout without making a
+ * real HTTP call.
+ */
+export function persistBindArtifacts(identity, privateKeyPem) {
+    mkdirSync(AGENTVALET_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(KEY_PATH, privateKeyPem, { mode: 0o600 });
+    writeFileSync(IDENTITY_PATH, JSON.stringify(identity, null, 2));
+}

package/dist/config.js

@@ -1,25 +1,105 @@
 import { readPrivateKeyFromEnv } from "./pem.js";
 import { importPKCS8 } from "jose";
+import { attemptInviteBind, readBoundIdentity, readBoundPrivateKey, } from "./bind.js";
+const DEFAULT_PROXY_URL = "https://api.agentvalet.ai";
+/**
+ * Resolves the agent's identity + private key. Three paths:
+ *
+ *   1. Env-based — AGENT_ID + OWNER_ID + PROXY_URL + AGENT_PRIVATE_KEY*
+ *      provided. Legacy path; preserved unchanged.
+ *
+ *   2. Disk identity — env vars are missing but ~/.agentvalet/agent.json
+ *      and ~/.agentvalet/agent.key exist (e.g. from a previous bind).
+ *      Read them and proceed as if env had been set.
+ *
+ *   3. Invite-bind first run — INVITE_BIND_SECRET is set, no identity
+ *      is yet on disk, and no AGENT_ID env. Generate a keypair, POST
+ *      /v1/invites/bind, persist the result, then proceed.
+ *
+ * Order matters: env wins (explicit > implicit), then disk identity,
+ * then invite-bind. The bind path runs at most once per machine —
+ * the secret is consumed after first use.
+ */
+// Treat empty strings AND unresolved MCPB template placeholders (e.g.
+// "${user_config.agent_id}") as "not set". Claude Desktop on some platforms
+// passes the literal placeholder through when a user_config field has no
+// value and no manifest default — that would otherwise false-trigger the
+// env-based Path 1 below and skip the invite-bind handshake.
+function envOrNull(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return null;
+    const t = v.trim();
+    if (t === "")
+        return null;
+    if (t.startsWith("${") && t.endsWith("}"))
+        return null;
+    return t;
+}
 export async function validateConfig() {
+    // Path 1 — env-based (legacy).
+    const envAgentId = envOrNull("AGENT_ID");
+    const envOwnerId = envOrNull("OWNER_ID");
+    const envProxyUrl = envOrNull("PROXY_URL");
+    if (envAgentId && envOwnerId && envProxyUrl) {
+        return buildConfig({
+            agentId: envAgentId,
+            ownerId: envOwnerId,
+            proxyUrl: envProxyUrl,
+        });
+    }
+    // Path 2 — disk identity from a previous bind.
+    const diskIdentity = readBoundIdentity();
+    const diskKey = readBoundPrivateKey();
+    if (diskIdentity && diskKey) {
+        return buildConfig({
+            agentId: envAgentId ?? diskIdentity.agent_id,
+            ownerId: envOwnerId ?? diskIdentity.owner_id,
+            proxyUrl: envProxyUrl ?? diskIdentity.proxy_url,
+        });
+    }
+    // Path 3 — first-run invite bind.
+    const inviteBindSecret = envOrNull("INVITE_BIND_SECRET");
+    if (inviteBindSecret) {
+        const proxyUrl = (envProxyUrl ?? DEFAULT_PROXY_URL).replace(/\/$/, "");
+        process.stderr.write(`[mcp-server] First-run invite bind against ${proxyUrl}…\n`);
+        try {
+            const { identity } = await attemptInviteBind({
+                bindSecret: inviteBindSecret,
+                proxyUrl,
+            });
+            process.stderr.write(`[mcp-server] Bound as ${identity.agent_id} (owner ${identity.owner_id}). Key persisted to ~/.agentvalet/agent.key\n`);
+            return buildConfig({
+                agentId: identity.agent_id,
+                ownerId: identity.owner_id,
+                proxyUrl: identity.proxy_url,
+            });
+        }
+        catch (err) {
+            process.stderr.write(`[mcp-server] Invite bind failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
+    // Nothing usable — fall through to the original missing-env diagnostic.
     const missing = [];
     for (const key of ["AGENT_ID", "OWNER_ID", "PROXY_URL"]) {
         if (!process.env[key])
             missing.push(key);
     }
-    if (missing.length > 0) {
-        process.stderr.write(`[mcp-server] Missing required environment variables: ${missing.join(", ")}\n`);
-        process.exit(1);
-    }
-    const agentId = process.env.AGENT_ID;
-    const ownerId = process.env.OWNER_ID;
-    const proxyUrl = process.env.PROXY_URL.replace(/\/$/, "");
+    process.stderr.write(`[mcp-server] Missing required environment variables: ${missing.join(", ")}\n` +
+        `Either set them, run the invite-bind flow with INVITE_BIND_SECRET, ` +
+        `or restore ~/.agentvalet/agent.{key,json} from a previous bind.\n`);
+    process.exit(1);
+}
+async function buildConfig(args) {
+    const proxyUrl = args.proxyUrl.replace(/\/$/, "");
     let privateKeyPem = null;
     let privateKey = null;
     try {
         privateKeyPem = readPrivateKeyFromEnv();
     }
     catch {
-        // No key provided — tools will return pending-activation response
+        // No key — tools will return pending-activation response.
     }
     if (privateKeyPem !== null) {
         try {
@@ -30,5 +110,5 @@ export async function validateConfig() {
             process.exit(1);
         }
     }
-    return { agentId, ownerId, proxyUrl, privateKeyPem, privateKey };
+    return { agentId: args.agentId, ownerId: args.ownerId, proxyUrl, privateKeyPem, privateKey };
 }

package/dist/index.js

@@ -1,3 +1,19 @@
+// ── BOOT DIAGNOSTICS — must be FIRST executable code ─────────────────────
+// Claude Desktop captures whatever the MCP server writes to stderr before
+// the stdio transport handshake. If startup crashes silently (top-level
+// await rejection, import error, unhandled native crash), Claude Desktop
+// only logs "Server transport closed unexpectedly" with no detail. These
+// handlers guarantee a stack lands in the log no matter what fails next.
+process.stderr.write(`[mcp-server] boot v0.2.x | node=${process.version} | platform=${process.platform} | ` +
+    `env_keys=${Object.keys(process.env).filter((k) => k.startsWith("AGENT_") || k === "OWNER_ID" || k === "PROXY_URL" || k === "INVITE_BIND_SECRET").join(",") || "(none of expected)"}\n`);
+process.on("uncaughtException", (err) => {
+    process.stderr.write(`[mcp-server] FATAL uncaughtException: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});
+process.on("unhandledRejection", (err) => {
+    process.stderr.write(`[mcp-server] FATAL unhandledRejection: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -7,7 +23,16 @@ import { renderInstructions } from "./instructions.js";
 // ---------------------------------------------------------------------------
 // Startup env validation
 // ---------------------------------------------------------------------------
-const { agentId: AGENT_ID, ownerId: OWNER_ID, proxyUrl: PROXY_URL, privateKeyPem: AGENT_PRIVATE_KEY_RAW, privateKey } = await validateConfig();
+let configResult;
+try {
+    configResult = await validateConfig();
+}
+catch (err) {
+    process.stderr.write(`[mcp-server] FATAL validateConfig threw: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+}
+const { agentId: AGENT_ID, ownerId: OWNER_ID, proxyUrl: PROXY_URL, privateKeyPem: AGENT_PRIVATE_KEY_RAW, privateKey } = configResult;
+process.stderr.write(`[mcp-server] config ok | agent=${AGENT_ID} | owner=${OWNER_ID} | proxy=${PROXY_URL} | has_key=${!!privateKey}\n`);
 // ---------------------------------------------------------------------------
 // JWT signing
 // ---------------------------------------------------------------------------
@@ -316,11 +341,20 @@ async function fetchPlatformNamesForInstructions() {
         return undefined;
     }
 }
-const bootPlatformNames = await fetchPlatformNamesForInstructions();
+// NOTE: We intentionally do NOT prefetch platform names at boot. Doing so
+// added a top-level await on the proxy and blocked the `initialize` response
+// to Claude Desktop for several seconds (worse on cold Azure CA), causing
+// host-side timeouts. The LLM learns the catalogue from list_platforms at
+// runtime — boot-time enrichment was nice-to-have, not load-bearing.
 // ---------------------------------------------------------------------------
 // MCP server setup
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "agentvalet", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: renderInstructions(bootPlatformNames) });
+const server = new Server({ name: "agentvalet", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: renderInstructions(undefined) });
+// Fire the platform-names fetch in the background after the server is up so
+// it can't delay initialize. The result isn't surfaced to the host (MCP has
+// no instructions-update message), but the network warmup primes the proxy
+// and surfaces auth failures in the stderr boot diagnostics path.
+void fetchPlatformNamesForInstructions().catch(() => { });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         LIST_PLATFORMS_TOOL,
@@ -479,6 +513,20 @@ async function handleListPlatforms() {
     const body = await response.text();
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
+    // Proxy wraps the payload as { data: { platforms, version }, _meta: {...} }
+    // but outputSchema declares the flat { platforms, version } shape, so the
+    // wrapped envelope fails strict structuredContent validation and the host
+    // surfaces "tool execution failed (no upstream body)". Unwrap .data.
+    const parsed = tryParseJson(body);
+    const inner = parsed && typeof parsed === "object" && parsed !== null && "data" in parsed
+        ? parsed.data
+        : parsed;
+    if (inner && typeof inner === "object") {
+        return {
+            content: [{ type: "text", text: body }],
+            structuredContent: inner,
+        };
+    }
     return jsonContent(body);
 }
 // Translates a fetch() failure into something an end-user can actually act on.

package/dist/pem.js

@@ -1,27 +1,50 @@
 import { readFileSync } from "fs";
+import { readBoundPrivateKey } from "./bind.js";
 /**
  * Reads the RS256 private key from environment variables, supporting four formats:
  * - AGENT_PRIVATE_KEY_B64: base64-encoded PEM
  * - AGENT_PRIVATE_KEY_PATH: path to a PEM file
  * - AGENT_PRIVATE_KEY: raw multi-line PEM or \n-escaped single-line PEM
+ *
+ * Falls back to the disk-persisted invite-bind key at
+ * ~/.agentvalet/agent.key when no env-based source is present. This is
+ * the path written by the invite-flow first-run bind (see bind.ts) —
+ * having pem.ts honour it means subsequent invocations of the
+ * mcp-server don't need any env vars at all.
  */
+// Treat empty + unresolved MCPB placeholders ("${user_config.foo}") as
+// not-set — see config.ts for the same defence on identity envs.
+function readEnv(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return null;
+    const t = v.trim();
+    if (t === "")
+        return null;
+    if (t.startsWith("${") && t.endsWith("}"))
+        return null;
+    return t;
+}
 export function readPrivateKeyFromEnv() {
     // 1. Base64-encoded PEM
-    if (process.env.AGENT_PRIVATE_KEY_B64) {
-        return Buffer.from(process.env.AGENT_PRIVATE_KEY_B64, "base64").toString("utf-8").trim();
+    const b64 = readEnv("AGENT_PRIVATE_KEY_B64");
+    if (b64) {
+        return Buffer.from(b64, "base64").toString("utf-8").trim();
     }
     // 2. Path to PEM file
-    if (process.env.AGENT_PRIVATE_KEY_PATH) {
+    const path = readEnv("AGENT_PRIVATE_KEY_PATH");
+    if (path) {
         try {
-            return readFileSync(process.env.AGENT_PRIVATE_KEY_PATH, "utf-8").trim();
+            return readFileSync(path, "utf-8").trim();
         }
         catch (err) {
             throw new Error(`Cannot read AGENT_PRIVATE_KEY_PATH: ${err instanceof Error ? err.message : err}`);
         }
     }
     // 3. Raw PEM content (multi-line or \n-escaped)
-    if (process.env.AGENT_PRIVATE_KEY) {
-        const raw = process.env.AGENT_PRIVATE_KEY.trim();
+    const rawEnv = readEnv("AGENT_PRIVATE_KEY");
+    if (rawEnv) {
+        const raw = rawEnv;
         // Unescape \n sequences
         const unescaped = raw.replace(/\\n/g, "\n");
         // Wrap bare base64 blob without headers
@@ -30,5 +53,10 @@ export function readPrivateKeyFromEnv() {
         }
         return unescaped;
     }
-    throw new Error("No private key provided. Set AGENT_PRIVATE_KEY, AGENT_PRIVATE_KEY_PATH, or AGENT_PRIVATE_KEY_B64.");
+    // 4. Disk fallback — written by the invite-bind first-run flow.
+    const diskKey = readBoundPrivateKey();
+    if (diskKey)
+        return diskKey;
+    throw new Error("No private key provided. Set AGENT_PRIVATE_KEY, AGENT_PRIVATE_KEY_PATH, or AGENT_PRIVATE_KEY_B64, " +
+        "or run the invite-bind flow with INVITE_BIND_SECRET.");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "0.3.7",
+  "version": "0.3.10",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "type": "module",
   "main": "dist/index.js",