@zvndev/circular-mcp 0.1.1 → 0.1.3

package/README.md

@@ -84,9 +84,25 @@ pulling at the same moment can pick another candidate if a reservation loses.
 
 ## Authentication
 
-Identical to the CLI. Provide a **team API key** (`circ_tk_…`) plus the
-workspace and team ids, via environment variables (MCP clients inject these
-through the server's `env` block):
+Identical to the CLI. The normal path is managed browser sign-in:
+
+```bash
+npx -y @zvndev/circular-cli login --runtime codex
+```
+
+That command opens Circular, asks the signed-in human to approve a named agent,
+then stores the managed connection locally in `~/.circular/connections.json`.
+No API key has to be copied into an agent prompt or MCP config.
+
+For long-running MCP processes, pin the connection id returned by `login`:
+
+```
+CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login
+```
+
+Owners/admins can still provide an explicit **team API key** (`circ_tk_…`) for
+ongoing workspace agents or legacy automation. MCP clients inject these through
+the server's `env` block:
 
 ```
 CIRCULAR_API_KEY=circ_tk_xxx
@@ -95,7 +111,9 @@ CIRCULAR_TEAM_ID=team_xxx
 CIRCULAR_BASE_URL=https://gocircular.dev   # optional; default
 ```
 
-`~/.circular/config.json` also works as a fallback.
+`~/.circular/config.json` also works as a fallback for explicit keys. An
+explicit key always wins over managed login; a Desktop-bound agent identity does
+not borrow a managed or global fallback credential.
 
 ### Minting a team API key
 
@@ -113,9 +131,7 @@ below with `node /ABS/PATH/mcp/bin/circular-mcp.mjs`.
 
 ```bash
 claude mcp add circular \
-  -e CIRCULAR_API_KEY=circ_tk_xxx \
-  -e CIRCULAR_WORKSPACE_ID=ws_xxx \
-  -e CIRCULAR_TEAM_ID=team_xxx \
+  -e CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login \
   -- npx -y @zvndev/circular-mcp
 ```
 
@@ -131,9 +147,7 @@ Via the CLI:
 
 ```bash
 codex mcp add circular \
-  --env CIRCULAR_API_KEY=circ_tk_xxx \
-  --env CIRCULAR_WORKSPACE_ID=ws_xxx \
-  --env CIRCULAR_TEAM_ID=team_xxx \
+  --env CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login \
   -- npx -y @zvndev/circular-mcp
 ```
 
@@ -146,6 +160,12 @@ args = ["-y", "@zvndev/circular-mcp"]
 env = { CIRCULAR_API_KEY = "circ_tk_xxx", CIRCULAR_WORKSPACE_ID = "ws_xxx", CIRCULAR_TEAM_ID = "team_xxx" }
 ```
 
+For a managed connection, use:
+
+```toml
+env = { CIRCULAR_CONNECTION_ID = "key_or_connection_id_from_login" }
+```
+
 Verify with `codex mcp list` / `codex mcp get circular`.
 
 ### Cursor

package/bin/circular-mcp.mjs

@@ -10,10 +10,10 @@
  * Transport: MCP stdio (newline-delimited JSON-RPC 2.0). Protocol messages go on
  * stdin/stdout; everything human-facing goes to stderr.
  *
- * Auth is identical to the CLI: CIRCULAR_API_KEY (a team key, circ_tk_…),
- * CIRCULAR_WORKSPACE_ID, CIRCULAR_TEAM_ID (and optional CIRCULAR_BASE_URL), or
- * ~/.circular/config.json. MCP clients typically inject these via the server's
- * env block (e.g. `claude mcp add ... -e CIRCULAR_API_KEY=…`).
+ * Auth is identical to the CLI: a managed browser login from
+ * ~/.circular/connections.json, optionally pinned with CIRCULAR_CONNECTION_ID,
+ * or an explicit CIRCULAR_API_KEY plus workspace/team ids for legacy/service
+ * agents.
  */
 import { loadConfig } from "../lib/vendor/config.mjs";
 import { dispatch, SERVER_INFO } from "../lib/server.mjs";

package/lib/server.mjs

@@ -21,7 +21,7 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([
   "2024-11-05",
 ]);
 
-export const SERVER_INFO = { name: "circular-mcp", version: "0.1.1" };
+export const SERVER_INFO = { name: "circular-mcp", version: "0.1.3" };
 
 /**
  * The briefing every client sees on connect. This is the only onboarding an

package/lib/vendor/client.mjs

@@ -1,28 +1,12 @@
-/**
- * VENDORED from cli/lib/client.mjs. Do not edit here.
- *
- * The MCP server is published as a standalone package and advertises itself as
- * dependency-free, which is the whole point of `npx -y @zvndev/circular-mcp`:
- * nothing to resolve, nothing to install. It used to import this straight out
- * of `../../cli/lib`, a path that exists in the repo and in no published
- * tarball, so `npm publish` would have produced a package that crashed on its
- * first import.
- *
- * Everything below this header is a byte-for-byte copy of the CLI's file, and
- * test/package.test.mjs fails if the two ever drift.
- */
-
-/**
- * Thin HTTP client for the Circular Agent API. Authenticates with the team API
- * key via the Authorization: Bearer header. Returns parsed JSON; throws an
- * ApiError (with status + body) on non-2xx so the CLI can print + exit non-zero.
- */
 /**
  * Thin HTTP client for the Circular Agent API. Authenticates with the team API
  * key via the Authorization: Bearer header. Returns parsed JSON; throws an
  * ApiError (with status + body) on non-2xx so the CLI can print + exit non-zero.
  */
 import { readConfigFile } from "./config.mjs";
+import { readConnectionsFile, selectConnection } from "./connections.mjs";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+
 export class ApiError extends Error {
   constructor(message, status, body) {
     super(message);
@@ -33,12 +17,18 @@ export class ApiError extends Error {
 }
 
 export function teamBase(config) {
-  if (!config.apiKey) throw new Error("Missing API key. Set CIRCULAR_API_KEY.");
+  if (!config.apiKey) throw new Error("Not signed in. Run `circular login` or set CIRCULAR_API_KEY.");
   if (!config.workspaceId) throw new Error("Missing workspace. Set CIRCULAR_WORKSPACE_ID or --workspace.");
   if (!config.teamId) throw new Error("Missing team. Set CIRCULAR_TEAM_ID or --team.");
   return `${config.baseUrl}/api/workspaces/${config.workspaceId}/teams/${config.teamId}`;
 }
 
+export function workspaceBase(config) {
+  if (!config.apiKey) throw new Error("Not signed in. Run `circular login` or set CIRCULAR_API_KEY.");
+  if (!config.workspaceId) throw new Error("Missing workspace. Set CIRCULAR_WORKSPACE_ID or --workspace.");
+  return `${config.baseUrl}/api/workspaces/${config.workspaceId}`;
+}
+
 /**
  * The key on disk, if it is not the one that was just refused.
  *
@@ -68,14 +58,45 @@ function rotatedKey(usedKey, readFile = readConfigFile) {
 }
 
 async function send(config, method, url, body) {
-  return fetch(url, {
-    method,
-    headers: {
-      Authorization: `Bearer ${config.apiKey}`,
-      ...(body ? { "Content-Type": "application/json" } : {}),
-    },
-    ...(body ? { body: JSON.stringify(body) } : {}),
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+  try {
+    return await fetch(url, {
+      method,
+      redirect: "manual",
+      signal: controller.signal,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function refreshManagedConnection(config, readStore = readConnectionsFile) {
+  if (!config.managedConnectionId) return config;
+  const store = readStore();
+  const connection = selectConnection(store, config.managedConnectionId);
+  if (!connection) {
+    throw new Error(`Circular connection ${config.managedConnectionId} is not saved locally. The MCP process is pinned to this connection and will not fall back to another account.`);
+  }
+  if (stripTrailingSlash(connection.baseUrl) !== stripTrailingSlash(config.baseUrl)) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned API origin.`);
+  }
+  if (connection.workspaceId !== config.workspaceId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned workspace.`);
+  }
+  if (config.agentParticipantId && connection.agentParticipantId !== config.agentParticipantId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned agent identity.`);
+  }
+  if (config.authorizingUserId && connection.authorizingUserId !== config.authorizingUserId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned authorizing user.`);
+  }
+  config.apiKey = connection.token;
+  return config;
 }
 
 /**
@@ -89,7 +110,9 @@ export async function apiRequest(
   path,
   { query, body } = {},
   readFile = readConfigFile,
+  readConnectionStore = readConnectionsFile,
 ) {
+  refreshManagedConnection(config, readConnectionStore);
   const url = new URL(`${teamBase(config)}${path}`);
   if (query) {
     for (const [key, value] of Object.entries(query)) {
@@ -99,11 +122,69 @@ export async function apiRequest(
 
   let response = await send(config, method, url, body);
 
-  // One retry, and only when the file genuinely holds a different key. The
-  // config object is mutated so the rest of the session uses the live key too:
+  // Legacy unbound sessions get one retry when the file holds a different key.
+  // Bound sessions cannot prove that a global key represents the same agent
+  // and human, so they must reconnect instead of silently changing identity.
+  // The config object is mutated so the session uses the live key afterward:
   // recovering one request and leaving the next twenty to fail would be worse
   // than not recovering at all, because the failure would look intermittent.
-  if (response.status === 401) {
+  if (response.status === 401 && !config.agentParticipantId && !config.managedConnectionId) {
+    const rotated = rotatedKey(config.apiKey, readFile);
+    if (rotated) {
+      config.apiKey = rotated;
+      response = await send(config, method, url, body);
+    }
+  }
+
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = text;
+  }
+
+  if (!response.ok) {
+    if (response.status === 401 && config.agentParticipantId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This agent session credential expired or was revoked. Reconnect the session in Circular to authorize the same agent again; the global account key was not used.`,
+        response.status,
+        parsed,
+      );
+    }
+    if (response.status === 401 && config.managedConnectionId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This managed Circular connection expired or was revoked. Run \`circular login\` again and update CIRCULAR_CONNECTION_ID to the new connection id; no fallback API key was used.`,
+        response.status,
+        parsed,
+      );
+    }
+    const detail =
+      parsed && typeof parsed === "object" && parsed.error ? parsed.error : response.statusText;
+    throw new ApiError(`${method} ${path} failed (${response.status}): ${detail}`, response.status, parsed);
+  }
+
+  return parsed;
+}
+
+export async function workspaceRequest(
+  config,
+  method,
+  path,
+  { query, body } = {},
+  readFile = readConfigFile,
+  readConnectionStore = readConnectionsFile,
+) {
+  refreshManagedConnection(config, readConnectionStore);
+  const url = new URL(`${workspaceBase(config)}${path}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+  }
+
+  let response = await send(config, method, url, body);
+  if (response.status === 401 && !config.agentParticipantId && !config.managedConnectionId) {
     const rotated = rotatedKey(config.apiKey, readFile);
     if (rotated) {
       config.apiKey = rotated;
@@ -120,6 +201,20 @@ export async function apiRequest(
   }
 
   if (!response.ok) {
+    if (response.status === 401 && config.agentParticipantId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This agent session credential expired or was revoked. Reconnect the session in Circular to authorize the same agent again; the global account key was not used.`,
+        response.status,
+        parsed,
+      );
+    }
+    if (response.status === 401 && config.managedConnectionId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This managed Circular connection expired or was revoked. Run \`circular login\` again and update CIRCULAR_CONNECTION_ID to the new connection id; no fallback API key was used.`,
+        response.status,
+        parsed,
+      );
+    }
     const detail =
       parsed && typeof parsed === "object" && parsed.error ? parsed.error : response.statusText;
     throw new ApiError(`${method} ${path} failed (${response.status}): ${detail}`, response.status, parsed);
@@ -127,3 +222,7 @@ export async function apiRequest(
 
   return parsed;
 }
+
+function stripTrailingSlash(url) {
+  return typeof url === "string" ? url.replace(/\/+$/, "") : url;
+}

package/lib/vendor/config.mjs

@@ -1,17 +1,3 @@
-/**
- * VENDORED from cli/lib/config.mjs. Do not edit here.
- *
- * The MCP server is published as a standalone package and advertises itself as
- * dependency-free, which is the whole point of `npx -y @zvndev/circular-mcp`:
- * nothing to resolve, nothing to install. It used to import this straight out
- * of `../../cli/lib`, a path that exists in the repo and in no published
- * tarball, so `npm publish` would have produced a package that crashed on its
- * first import.
- *
- * Everything below this header is a byte-for-byte copy of the CLI's file, and
- * test/package.test.mjs fails if the two ever drift.
- */
-
 /**
  * Config resolution for the Circular CLI.
  *
@@ -22,6 +8,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { findConnection, hasConnectionId, readConnectionsFile, tryReadConnectionsFile } from "./connections.mjs";
 
 export const DEFAULT_BASE_URL = "https://gocircular.dev";
 
@@ -41,26 +28,95 @@ export function readConfigFile(path = configFilePath()) {
  * Merge flags, env, and file into the effective config. `flags` are the parsed
  * CLI flags; `env` defaults to process.env; `file` is the parsed config file.
  */
-export function resolveConfig(flags = {}, env = process.env, file = {}) {
+export function resolveConfig(flags = {}, env = process.env, file = {}, connectionStore = {}) {
+  const agentParticipantId = env.CIRCULAR_AGENT_PARTICIPANT_ID?.trim();
+  const authorizingUserId = env.CIRCULAR_AUTHORIZING_USER_ID?.trim();
   const pick = (flagKey, envKey, fileKey, fallback) => {
     if (flags[flagKey] !== undefined && flags[flagKey] !== true) return flags[flagKey];
     if (env[envKey]) return env[envKey];
-    if (file[fileKey]) return file[fileKey];
+    if (file[fileKey] && !(agentParticipantId && fileKey === "apiKey")) return file[fileKey];
     return fallback;
   };
 
+  const explicitRuntimeApiKey = flags["api-key"] !== undefined && flags["api-key"] !== true
+    ? flags["api-key"]
+    : env.CIRCULAR_API_KEY || undefined;
+  const legacyFileApiKey = !agentParticipantId ? file.apiKey : undefined;
+  const requestedBaseUrlOverride = flags["base-url"] !== undefined && flags["base-url"] !== true
+    ? flags["base-url"]
+    : env.CIRCULAR_BASE_URL || undefined;
+  const requestedWorkspaceOverride = flags.workspace !== undefined && flags.workspace !== true
+    ? flags.workspace
+    : env.CIRCULAR_WORKSPACE_ID || undefined;
+  const requestedTeamOverride = flags.team !== undefined && flags.team !== true
+    ? flags.team
+    : env.CIRCULAR_TEAM_ID || undefined;
+  const requestedBaseUrl = stripTrailingSlash(
+    pick("base-url", "CIRCULAR_BASE_URL", "baseUrl", undefined)
+  );
+  const requestedWorkspaceId = pick("workspace", "CIRCULAR_WORKSPACE_ID", "workspaceId", undefined);
+  const requestedTeamId = pick("team", "CIRCULAR_TEAM_ID", "teamId", undefined);
+  const connectionId = flags.connection !== undefined && flags.connection !== true
+    ? flags.connection
+    : env.CIRCULAR_CONNECTION_ID || file.connectionId || undefined;
+  const managedConnection = !explicitRuntimeApiKey && !agentParticipantId
+    ? findConnection(connectionStore, {
+      id: connectionId,
+      baseUrl: stripTrailingSlash(requestedBaseUrlOverride),
+      workspaceId: requestedWorkspaceOverride,
+    })
+    : null;
+
+  const hasManagedConnectionFilter = Boolean(requestedBaseUrlOverride || requestedWorkspaceOverride);
+  const hasSavedConnections = Array.isArray(connectionStore?.connections) && connectionStore.connections.length > 0;
+  if ((connectionId || (hasManagedConnectionFilter && hasSavedConnections)) && !managedConnection && !explicitRuntimeApiKey && !agentParticipantId) {
+    if (!connectionId) {
+      throw new Error("No saved Circular connection matches the requested origin/workspace/team. Run circular status or circular login.");
+    }
+    const reason = hasConnectionId(connectionStore, connectionId)
+      ? "but it does not match the requested origin/workspace/team"
+      : "and it is not saved locally";
+    throw new Error(`Circular connection ${connectionId} was requested ${reason}. Run circular status or circular login.`);
+  }
+
+  if (managedConnection) {
+    return {
+      apiKey: managedConnection.token,
+      baseUrl: stripTrailingSlash(managedConnection.baseUrl),
+      workspaceId: managedConnection.workspaceId,
+      teamId: requestedTeamOverride ?? managedConnection.teamId,
+      managedConnectionId: managedConnection.id,
+      ...(managedConnection.agentParticipantId ? { agentParticipantId: managedConnection.agentParticipantId } : {}),
+      ...(managedConnection.authorizingUserId ? { authorizingUserId: managedConnection.authorizingUserId } : {}),
+    };
+  }
+
   return {
-    apiKey: pick("api-key", "CIRCULAR_API_KEY", "apiKey", undefined),
+    // A bound session cannot borrow the operator's global credential, including
+    // when its delegated key is missing rather than rejected by the server.
+    apiKey: explicitRuntimeApiKey ?? legacyFileApiKey,
     baseUrl: stripTrailingSlash(
       pick("base-url", "CIRCULAR_BASE_URL", "baseUrl", DEFAULT_BASE_URL)
     ),
-    workspaceId: pick("workspace", "CIRCULAR_WORKSPACE_ID", "workspaceId", undefined),
-    teamId: pick("team", "CIRCULAR_TEAM_ID", "teamId", undefined),
+    workspaceId: requestedWorkspaceId,
+    teamId: requestedTeamId,
+    ...(agentParticipantId ? { agentParticipantId, ...(authorizingUserId ? { authorizingUserId } : {}) } : {}),
   };
 }
 
-export function loadConfig(flags = {}) {
-  return resolveConfig(flags, process.env, readConfigFile());
+export function loadConfig(flags = {}, options = {}) {
+  const file = readConfigFile();
+  if (options.allowMissingManagedConnection) {
+    return resolveConfig(flags, process.env, file, { version: 1, currentConnectionId: null, connections: [] });
+  }
+  const hasExplicitRuntimeApiKey = flags["api-key"] !== undefined && flags["api-key"] !== true
+    ? true
+    : Boolean(process.env.CIRCULAR_API_KEY);
+  const hasBoundDesktopIdentity = Boolean(process.env.CIRCULAR_AGENT_PARTICIPANT_ID?.trim());
+  const connectionStore = hasExplicitRuntimeApiKey || hasBoundDesktopIdentity
+    ? tryReadConnectionsFile()
+    : readConnectionsFile();
+  return resolveConfig(flags, process.env, file, connectionStore);
 }
 
 function stripTrailingSlash(url) {

package/lib/vendor/connections.mjs

@@ -0,0 +1,149 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export function connectionsFilePath() {
+  if (process.env.CIRCULAR_CONNECTIONS_FILE) return process.env.CIRCULAR_CONNECTIONS_FILE;
+  return join(homedir(), ".circular", "connections.json");
+}
+
+export function isTrustedCircularOrigin(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "https:") return true;
+    return url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function readConnectionsFile(path = connectionsFilePath()) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return normalizeStore({});
+    }
+    throw new Error(`Could not read Circular connections file at ${path}. Fix or move the corrupt file before writing a new managed connection.`);
+  }
+  assertValidStore(parsed, path);
+  return normalizeStore(parsed);
+}
+
+export function tryReadConnectionsFile(path = connectionsFilePath()) {
+  try {
+    return readConnectionsFile(path);
+  } catch {
+    return normalizeStore({});
+  }
+}
+
+export function writeConnectionsFile(store, path = connectionsFilePath()) {
+  assertValidStore(store, path);
+  const normalized = normalizeStore(store);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best effort on non-POSIX filesystems.
+  }
+  return normalized;
+}
+
+export function normalizeStore(store) {
+  const connections = Array.isArray(store?.connections)
+    ? store.connections.filter(isConnection)
+    : [];
+  const currentConnectionId = typeof store?.currentConnectionId === "string"
+    && connections.some((connection) => connection.id === store.currentConnectionId)
+    ? store.currentConnectionId
+    : null;
+  return { version: 1, currentConnectionId, connections };
+}
+
+export function selectConnection(store, id) {
+  const normalized = normalizeStore(store);
+  const connectionId = id || normalized.currentConnectionId;
+  if (!connectionId) return null;
+  return normalized.connections.find((connection) => connection.id === connectionId) ?? null;
+}
+
+export function findConnection(store, { id, baseUrl, workspaceId, teamId } = {}) {
+  const normalized = normalizeStore(store);
+  const candidates = id
+    ? normalized.connections.filter((connection) => connection.id === id)
+    : normalized.connections.filter((connection) => connection.id === normalized.currentConnectionId);
+  return candidates.find((connection) =>
+    (!baseUrl || stripTrailingSlash(connection.baseUrl) === stripTrailingSlash(baseUrl)) &&
+    (!workspaceId || connection.workspaceId === workspaceId) &&
+    (!teamId || connection.teamId === teamId)
+  ) ?? null;
+}
+
+export function hasConnectionId(store, id) {
+  return normalizeStore(store).connections.some((connection) => connection.id === id);
+}
+
+export function upsertConnection(store, connection) {
+  if (!isConnection(connection)) throw new Error("Invalid Circular connection");
+  const normalized = normalizeStore(store);
+  const connections = [
+    connection,
+    ...normalized.connections.filter((entry) => entry.id !== connection.id),
+  ];
+  return { version: 1, currentConnectionId: connection.id, connections };
+}
+
+export function removeConnection(store, id) {
+  const normalized = normalizeStore(store);
+  const connections = normalized.connections.filter((entry) => entry.id !== id);
+  return {
+    version: 1,
+    currentConnectionId: normalized.currentConnectionId === id ? null : normalized.currentConnectionId,
+    connections,
+  };
+}
+
+export function publicConnectionRecord(connection) {
+  if (!connection) return null;
+  const { token: _token, ...safe } = connection;
+  return safe;
+}
+
+function stripTrailingSlash(url) {
+  return typeof url === "string" ? url.replace(/\/+$/, "") : url;
+}
+
+function assertValidStore(store, path) {
+  if (!store || typeof store !== "object" || Array.isArray(store)) {
+    throw new Error(`Invalid Circular connections file at ${path}. Expected a versioned connection store.`);
+  }
+  if (store.version !== 1 || !Array.isArray(store.connections)) {
+    throw new Error(`Invalid Circular connections file at ${path}. Expected version 1 with a connections array.`);
+  }
+  if (!(store.currentConnectionId === null || store.currentConnectionId === undefined || typeof store.currentConnectionId === "string")) {
+    throw new Error(`Invalid Circular connections file at ${path}. currentConnectionId must be a string or null.`);
+  }
+  const invalid = store.connections.find((connection) => !isConnection(connection));
+  if (invalid) {
+    throw new Error(`Invalid Circular connections file at ${path}. Connection entries must include id, name, trusted baseUrl, token, workspaceId and teamId.`);
+  }
+}
+
+function isConnection(value) {
+  return Boolean(
+    value &&
+      typeof value.id === "string" &&
+      typeof value.name === "string" &&
+      typeof value.baseUrl === "string" &&
+      isTrustedCircularOrigin(value.baseUrl) &&
+      typeof value.token === "string" &&
+      typeof value.workspaceId === "string" &&
+      typeof value.teamId === "string",
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/circular-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Dependency-free stdio MCP server for the Circular Agent API — plan work into Circular as tracked tasks and subtasks.",
   "keywords": [
     "circular",