@apideck/mcp-connect 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@apideck/mcp-connect` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-20
+
+Initial release. Extracted as a standalone, framework-agnostic package from the
+in-repo MCP-Connect core.
+
+### Added
+
+- **Toolset engine** (`toolset.ts`): `buildToolset`, `loadMcpToolset`,
+  `dispatchToolCall`, `safeToolName`, `normalizeSchema`,
+  `renderMcpSystemPromptHint`, and the recoverable `McpConfigError`. Loads
+  connected MCP servers, namespaces tools as `slug__tool` (charset-safe, ≤64
+  chars with a stable hash suffix to avoid truncation collisions), and routes
+  inbound tool calls back to the right server.
+- **Persistence seam** (`connection-store.ts`): the `ConnectionStore` interface
+  plus `Identity` and `StoredConnection` types. Tenancy and the
+  workspace-vs-per-user visibility rule are the host's responsibility.
+- **In-memory reference store** (`connection-store-memory.ts`):
+  `InMemoryConnectionStore` — a zero-dependency implementation that enforces the
+  full visibility contract, so the package runs standalone.
+- **MCP transport client** (`client.ts`): `mcpListTools`, `mcpCallTool`, and
+  `McpRpcError`. Thin shim over `@modelcontextprotocol/sdk` that tries Streamable
+  HTTP first and falls back to legacy HTTP+SSE, with an end-to-end request
+  timeout.
+- **OAuth provider plugin registry** (`oauth-provider.ts`):
+  `registerOAuthProvider`, `getOAuthProvider`, `registeredOAuthProviderSlugs`,
+  and the `OAuthProvider` / `OAuthTokenResult` types. Connect flows resolve
+  providers by slug instead of branching on vendor literals.
+- **AES-256-GCM token encryption** (`crypto.ts`, new in this package):
+  `encryptToken`, `decryptToken`, `generateKey`, `deriveKeyFromPassphrase`, and
+  `safeEqual`. Authenticated encryption-at-rest under an injected KEK — the
+  recommended default. Detects tampering and wrong keys on decrypt.
+- **Legacy obfuscation** (`obfuscate.ts`): `obfuscateToken` /
+  `deobfuscateToken` (HMAC-XOR). Preserved for back-compat only and explicitly
+  documented as **not** encryption.
+- **Neutral types** (`types.ts`): `ToolDef`, `ToolInputSchema`,
+  `ServerCatalogEntry`.
+- **Runnable example** (`examples/quickstart.ts`): stands up a throwaway
+  localhost MCP server and exercises encrypt → store → load → namespace →
+  dispatch with zero external dependencies.
+- Docs: `README.md` (quickstart, `ConnectionStore` contract, provider-plugin
+  authoring guide, honest token-storage security section), `ARCHITECTURE.md`,
+  `CONTRIBUTING.md`, MIT `LICENSE`.
+
+[0.1.0]: https://github.com/apideck-libraries/mcp-connect/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apideck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# @apideck/mcp-connect
+
+Framework-agnostic core for **connecting, namespacing, and dispatching
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) tools** — with
+pluggable persistence, OAuth providers, and token encryption.
+
+It is the reusable heart of a "connect your own MCP servers" feature: given a
+set of connected MCP servers, it loads their tools, namespaces them so their
+names never collide, exposes them as neutral tool definitions you can hand to
+any LLM, and routes inbound tool calls back to the right server. It has **no
+database, no web framework, and no LLM-vendor dependency** — everything
+app-specific is injected through small seams.
+
+```
+connected servers ──► load + namespace tools ──► neutral ToolDef[] ──► your LLM
+        ▲                                                                  │
+        │                                                          tool call by name
+   ConnectionStore                                                        │
+   (you implement)  ◄──── dispatch routes it back to the right server ◄───┘
+```
+
+## Install
+
+```bash
+npm install @apideck/mcp-connect
+# peer runtime dep is bundled: @modelcontextprotocol/sdk
+```
+
+Requires Node.js >= 20. ESM only (`"type": "module"`).
+
+## Quickstart
+
+A complete, runnable version of this (with a throwaway localhost MCP server so
+the dispatch is real) lives in [`examples/quickstart.ts`](./examples/quickstart.ts)
+— run it with `npm run example`.
+
+```ts
+import {
+  InMemoryConnectionStore,
+  loadMcpToolset,
+  dispatchToolCall,
+  renderMcpSystemPromptHint,
+  encryptToken,
+  decryptToken,
+  generateKey,
+  type Identity,
+} from "@apideck/mcp-connect";
+
+// 1. Resolve a 32-byte key-encryption key (KEK). In production this comes from
+//    your secret manager; never hard-code it.
+const kek = generateKey();
+
+// 2. Persist a connection. The store only ever sees the ENCRYPTED token.
+const store = new InMemoryConnectionStore();
+store.addConnection({
+  tenantId: "acme-inc",
+  serverSlug: "front",
+  serverName: "Front",
+  mcpEndpoint: "https://mcp.frontapp.com/mcp",
+  accessTokenObfuscated: encryptToken("the-oauth-access-token", kek),
+  scope: "workspace",
+  toolCatalog: { tools: [/* fetched at connect time via mcpListTools */] },
+});
+
+// 3. Load + namespace the tools for a given identity. The core decrypts via the
+//    injected function — the store never does crypto.
+const identity: Identity = { tenantId: "acme-inc", ownerId: "user-1" };
+const toolset = await loadMcpToolset(store, identity, (enc) => decryptToken(enc, kek));
+
+// 4. Hand toolset.toolDefs to your LLM, and optionally add a prompt hint.
+const systemHint = renderMcpSystemPromptHint(toolset);
+
+// 5. When the model calls a tool, route it back:
+const result = await dispatchToolCall(
+  toolset,
+  "front__search",           // namespaced name the model called
+  { query: "acme.com" },      // tool input
+  { resolveHeaders: () => ({}) },
+);
+// result.text is ready to drop into a tool_result block.
+```
+
+## Concepts
+
+### Tool namespacing
+
+MCP servers don't namespace their tool names, so two servers could both expose a
+`search` tool. `mcp-connect` prefixes every tool with its server slug and a
+double underscore: `front__search`. Names are sanitized to `[A-Za-z0-9_-]{1,64}`
+(the Anthropic constraint, a safe lowest common denominator) and, when a name
+would exceed 64 chars, truncated with a stable hash suffix so distinct tools
+never collide. That same `slug__tool` convention is what lets `dispatchToolCall`
+route an inbound call back to the right server with no extra round trip.
+
+### The `ConnectionStore` seam
+
+Persistence is injected. The core only ever calls:
+
+```ts
+interface ConnectionStore {
+  listConnections(identity: Identity): Promise<StoredConnection[]>;
+}
+
+interface Identity {
+  tenantId: string;   // opaque routing key
+  ownerId: string;    // the signed-in user (scopes per-user connections)
+}
+```
+
+Your implementation must honour the **visibility contract**:
+
+- a connection is only visible within its own `tenantId`;
+- `workspace`-scope connections are visible to every user in the tenant;
+- `per_user`-scope connections are visible only to their `userId` owner.
+
+`InMemoryConnectionStore` ships in the box (great for tests, prototypes, and the
+example) and demonstrates exactly that contract. For production, implement the
+interface against your own datastore (SQL, KV, an ORM, …). `StoredConnection`
+carries no `tenantId` field because tenant scoping is the store's job, not the
+core's — your store filters by tenant before returning rows.
+
+`StoredConnection` fields:
+
+| field | meaning |
+| --- | --- |
+| `connectionId` | your primary key |
+| `accessTokenObfuscated` | the token **as persisted** (obfuscated or encrypted — the core decrypts via the injected function) |
+| `toolCatalog` | cached `{ tools: [...] }` fetched at connect time |
+| `scope` | `"workspace"` or `"per_user"` |
+| `userId` | owner for per-user connections, else `null` |
+| `serverId` / `serverSlug` / `serverName` / `mcpEndpoint` | the joined server metadata |
+
+## Provider-plugin authoring guide (OAuth)
+
+OAuth-backed servers connect through a small **provider plugin**. Instead of
+branching on vendor slugs in your connect routes, you register an `OAuthProvider`
+and resolve it by slug. Adding a new provider is a registration in your code —
+never an edit to this package.
+
+```ts
+import { registerOAuthProvider, getOAuthProvider, type OAuthProvider } from "@apideck/mcp-connect";
+
+const frontProvider: OAuthProvider = {
+  slug: "front",
+
+  // Is the host config present? (Read your own env/secrets here — the core never does.)
+  isConfigured: () => Boolean(process.env.FRONT_CLIENT_ID && process.env.FRONT_CLIENT_SECRET),
+  notConfiguredMessage: "Set FRONT_CLIENT_ID and FRONT_CLIENT_SECRET.",
+
+  // Where the vendor should redirect back to. Derive from the request origin
+  // (optionally honouring an env override).
+  deriveRedirectUri: (origin) => `${origin}/api/integrations/front/oauth/callback`,
+
+  // The vendor authorize URL you redirect the user to.
+  buildAuthorizeUrl: ({ redirectUri, state, scope }) => {
+    const u = new URL("https://app.frontapp.com/oauth/authorize");
+    u.searchParams.set("client_id", process.env.FRONT_CLIENT_ID!);
+    u.searchParams.set("redirect_uri", redirectUri);
+    u.searchParams.set("response_type", "code");
+    u.searchParams.set("state", state);
+    return u.toString();
+  },
+
+  // Exchange the authorization code for tokens, returned in the neutral shape.
+  exchangeCode: async ({ code, redirectUri }) => {
+    const res = await fetch("https://app.frontapp.com/oauth/token", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: process.env.FRONT_CLIENT_ID,
+        client_secret: process.env.FRONT_CLIENT_SECRET,
+      }),
+    });
+    const json = await res.json();
+    return {
+      accessToken: json.access_token,
+      refreshToken: json.refresh_token ?? null,
+      tokenType: json.token_type ?? "Bearer",
+      expiresInSeconds: json.expires_in ?? null,
+    };
+  },
+
+  // Optional: refresh support.
+  refresh: async ({ refreshToken }) => { /* ... */ },
+};
+
+registerOAuthProvider(frontProvider);
+```
+
+Your connect route then does the vendor-agnostic thing:
+
+```ts
+const provider = getOAuthProvider(slug);
+if (!provider) return respond(501, "Unknown provider");
+if (!provider.isConfigured()) return respond(400, provider.notConfiguredMessage);
+const redirectUri = provider.deriveRedirectUri(requestOrigin);
+redirect(provider.buildAuthorizeUrl({ redirectUri, state, scope }));
+// ...callback: const tokens = await provider.exchangeCode({ code, redirectUri });
+//    encrypt tokens.accessToken, fetch the tool catalog, store.addConnection(...)
+```
+
+Registration is idempotent (last registration for a slug wins), so hot-reload
+and repeated imports are safe.
+
+## Security: token storage
+
+Access tokens are secrets. This package gives you **two** token-at-rest options.
+Choose deliberately:
+
+### `crypto.ts` — AES-256-GCM (recommended)
+
+Real authenticated encryption. `encryptToken` / `decryptToken` provide
+confidentiality **and** tamper-detection: any modification to the ciphertext
+(or the wrong key) makes `decryptToken` throw rather than return garbage.
+
+```ts
+import { encryptToken, decryptToken, generateKey, deriveKeyFromPassphrase } from "@apideck/mcp-connect";
+
+const kek = generateKey();                         // 32-byte key → your secret manager
+const envelope = encryptToken("secret-token", kek); // "v1.<iv>.<tag>.<ciphertext>"
+const plain = decryptToken(envelope, kek);
+```
+
+- The key (a **KEK**, key-encryption key) is injected as a 32-byte `Buffer`. The
+  package never reads env — your host resolves the key (KMS, secret manager, env
+  var) and passes it in, so **key rotation is entirely under your control**.
+- `deriveKeyFromPassphrase(passphrase, salt)` derives a KEK via scrypt for simple
+  single-operator setups. Store and reuse the salt. Prefer `generateKey()` + a
+  secret manager for production.
+- **Use this as your default.**
+
+### `obfuscate.ts` — HMAC-XOR obfuscation (NOT encryption)
+
+`obfuscateToken` / `deobfuscateToken` implement an HMAC-SHA256 keystream XOR.
+
+> **This is obfuscation, not encryption. It is NOT secure and must never be
+> described as encryption-at-rest.** It only stops tokens from appearing in
+> plaintext to a casual `cat`, log dump, or generic secrets scanner. It provides
+> **no integrity guarantee** and should not be relied on to protect against an
+> attacker who reads your database.
+
+It is kept **only** for back-compat with data written by earlier versions and
+for environments that explicitly accept its (non-)guarantees. New integrations
+should use AES-256-GCM.
+
+Both modules share the same shape (`(value, key) → string` and back), so the
+core's injected `deobfuscate` function works with either — you decide which by
+choosing which decrypt function you pass to `loadMcpToolset` / `buildToolset`.
+
+## API surface
+
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the module boundary and the full
+export list. In short:
+
+- **Persistence:** `ConnectionStore`, `Identity`, `StoredConnection`, `InMemoryConnectionStore`
+- **Toolset:** `buildToolset`, `loadMcpToolset`, `dispatchToolCall`, `safeToolName`, `normalizeSchema`, `renderMcpSystemPromptHint`, `McpConfigError`
+- **Transport:** `mcpListTools`, `mcpCallTool`, `McpRpcError`
+- **OAuth plugins:** `registerOAuthProvider`, `getOAuthProvider`, `registeredOAuthProviderSlugs`, `OAuthProvider`
+- **Token protection:** `encryptToken`, `decryptToken`, `generateKey`, `deriveKeyFromPassphrase`, `safeEqual` (AES-GCM); `obfuscateToken`, `deobfuscateToken` (legacy)
+
+## Development
+
+```bash
+npm install
+npm run build       # tsc → dist/ with .d.ts declarations
+npm test            # vitest
+npm run typecheck   # tsc --noEmit (includes examples/)
+npm run lint        # eslint
+npm run example     # runs examples/quickstart.ts end-to-end
+```
+
+## License
+
+MIT © Apideck. See [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    /** JSON Schema for the tool's input. */
+    inputSchema?: Record<string, unknown>;
+}
+export interface McpListToolsResponse {
+    tools: McpToolDefinition[];
+}
+export interface McpCallToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpClientOptions {
+    endpoint: string;
+    accessToken: string;
+    /** Optional additional headers (e.g. for API-key style auth that
+     *  uses a non-standard header). */
+    extraHeaders?: Record<string, string>;
+    /** Soft timeout per RPC. Defaults to 30s. */
+    timeoutMs?: number;
+}
+declare class McpRpcError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+export declare function mcpListTools(opts: McpClientOptions): Promise<McpListToolsResponse>;
+export declare function mcpCallTool(opts: McpClientOptions, name: string, args?: Record<string, unknown>): Promise<McpCallToolResult>;
+export { McpRpcError };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB;uCACmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,cAAM,WAAY,SAAQ,KAAK;aACgB,IAAI,EAAE,MAAM;gBAA7C,OAAO,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAI1D;AAiGD,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAWxF;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAQ5B;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Apideck
+/**
+ * MCP client wrapper.
+ *
+ * Thin shim over @modelcontextprotocol/sdk so the rest of the app
+ * keeps speaking our small surface (mcpListTools / mcpCallTool) and
+ * doesn't see the SDK details. The SDK handles both transports
+ * transparently:
+ *   - Legacy HTTP+SSE: GET <endpoint>/sse, server pushes a session-
+ *     scoped POST URL via an `endpoint` event, client POSTs JSON-RPC
+ *     there. (Front uses this.)
+ *   - Streamable HTTP: single URL, POST gets the JSON-RPC response
+ *     immediately or via a short-lived SSE stream.
+ * We try Streamable HTTP first; if the server speaks the legacy
+ * transport it'll reject and we fall back.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+// SSEClientTransport is the legacy HTTP+SSE transport. The SDK marks
+// it deprecated but still ships it because servers like Front haven't
+// migrated to Streamable HTTP yet. Keep until that's no longer true.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+class McpRpcError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "McpRpcError";
+    }
+}
+/**
+ * Build the auth + Accept headers every MCP request needs. The SDK
+ * accepts a `requestInit` that's spread into each fetch.
+ */
+function buildHeaders(opts) {
+    return {
+        Authorization: `Bearer ${opts.accessToken}`,
+        ...(opts.extraHeaders ?? {}),
+    };
+}
+/**
+ * Connect using Streamable HTTP first, fall back to legacy SSE if the
+ * server doesn't speak the new transport. Returns a connected Client
+ * instance the caller is responsible for closing.
+ */
+async function connect(opts) {
+    const client = new Client({ name: "@apideck/mcp-connect", version: "0.1.0" }, { capabilities: {} });
+    const url = new URL(opts.endpoint);
+    const headers = buildHeaders(opts);
+    // Try the newer transport first. If the server rejects with 4xx
+    // (typically 404 or 405), fall back to legacy SSE on the same URL.
+    try {
+        const transport = new StreamableHTTPClientTransport(url, {
+            requestInit: { headers },
+        });
+        await client.connect(transport);
+        return client;
+    }
+    catch (err) {
+        // Any non-success on Streamable HTTP → try legacy SSE. The SDK
+        // will throw various error shapes here (typed Error, status codes)
+        // so we just bail to the fallback rather than inspecting too hard.
+        // The SDK attaches `requestInit.headers` to BOTH the initial SSE
+        // GET and the follow-up POST requests (see SSEClientTransport
+        // _commonHeaders). We don't need to override eventSourceInit.fetch.
+        const sseTransport = new SSEClientTransport(url, {
+            requestInit: { headers },
+        });
+        try {
+            await client.connect(sseTransport);
+            return client;
+        }
+        catch (sseErr) {
+            const msg = sseErr instanceof Error ? sseErr.message : String(sseErr);
+            // Surface BOTH errors so callers see what we tried. The route
+            // pattern-matches McpRpcError to choose the user-facing message.
+            const status = /401|unauthor/i.test(msg) ? 401 :
+                /403|forbidden/i.test(msg) ? 403 :
+                    /5\d\d/.test(msg) ? 502 :
+                        -32603;
+            // Re-throw the original error so its prototype/name is preserved
+            // (e.g. AbortError / TimeoutError) wrapped as McpRpcError.
+            throw new McpRpcError(`${err instanceof Error ? err.message : String(err)} | sse fallback: ${msg}`, status);
+        }
+    }
+}
+async function withClient(opts, fn) {
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    // The race covers BOTH connect() and the inner call. Earlier
+    // versions only raced fn(client), which left a window where a
+    // hung SDK handshake (Streamable HTTP probe + SSE fallback) could
+    // block the request indefinitely before the timeout was armed.
+    // We share one timer between the two phases so the total budget
+    // is enforced end-to-end, not per phase.
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(Object.assign(new Error("MCP request timed out"), { name: "TimeoutError" })), timeoutMs);
+    });
+    let client;
+    try {
+        client = await Promise.race([connect(opts), timeoutPromise]);
+    }
+    catch (err) {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        throw err;
+    }
+    try {
+        return await Promise.race([fn(client), timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        // Best-effort close; we don't care about errors during teardown.
+        void client.close().catch(() => undefined);
+    }
+}
+export async function mcpListTools(opts) {
+    return withClient(opts, async (client) => {
+        const res = await client.listTools();
+        return {
+            tools: res.tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        };
+    });
+}
+export async function mcpCallTool(opts, name, args = {}) {
+    return withClient(opts, async (client) => {
+        const res = await client.callTool({ name, arguments: args });
+        return {
+            content: (res.content ?? []),
+            isError: res.isError === true,
+        };
+    });
+}
+export { McpRpcError };
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/connection-store-memory.d.ts

@@ -0,0 +1,34 @@
+import type { ConnectionStore, Identity, StoredConnection } from "./connection-store.js";
+/** Input for {@link InMemoryConnectionStore.addConnection}. Only the essentials
+ *  are required; ids default to random UUIDs and scope defaults to per_user. */
+export interface AddConnectionInput {
+    tenantId: string;
+    serverSlug: string;
+    serverName: string;
+    mcpEndpoint: string;
+    /** Token as persisted — obfuscate (obfuscate.ts) or encrypt (crypto.ts)
+     *  before passing it in. The store never sees plaintext by convention. */
+    accessTokenObfuscated: string;
+    /** Cached tool catalog, shaped `{ tools: [...] }`. Defaults to no tools. */
+    toolCatalog?: unknown;
+    scope?: "workspace" | "per_user";
+    /** Required when scope is per_user; ignored (forced null) for workspace. */
+    userId?: string | null;
+    connectionId?: string;
+    serverId?: string;
+}
+export declare class InMemoryConnectionStore implements ConnectionStore {
+    private records;
+    /** Register/save a connection (the "connect" step in a real flow, after the
+     *  OAuth exchange + catalog fetch). Returns the stored row. */
+    addConnection(input: AddConnectionInput): StoredConnection;
+    /** Remove a connection by id. Returns true if a row was removed. */
+    removeConnection(connectionId: string): boolean;
+    /** Drop every connection (test/reset helper). */
+    clear(): void;
+    /** ConnectionStore contract: rows visible to `identity`, enforcing the tenant
+     *  + scope visibility rule. */
+    listConnections(identity: Identity): Promise<StoredConnection[]>;
+    private strip;
+}
+//# sourceMappingURL=connection-store-memory.d.ts.map

package/dist/connection-store-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-store-memory.d.ts","sourceRoot":"","sources":["../src/connection-store-memory.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAOzF;gFACgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;8EAC0E;IAC1E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,OAAO,CAAsB;IAErC;mEAC+D;IAC/D,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB;IAqB1D,oEAAoE;IACpE,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAM/C,iDAAiD;IACjD,KAAK,IAAI,IAAI;IAIb;mCAC+B;IACzB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAOtE,OAAO,CAAC,KAAK;CAMd"}

package/dist/connection-store-memory.js

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Apideck
+/**
+ * InMemoryConnectionStore — a zero-dependency reference implementation of the
+ * `ConnectionStore` seam.
+ *
+ * It lets the package run standalone (examples, tests, prototypes) with no
+ * database. It is NOT persistent — everything lives in a process-local array
+ * and is lost on restart. Production hosts implement `ConnectionStore` against
+ * their own datastore (SQL, KV, an ORM, …); this class shows the exact
+ * visibility contract they must honour.
+ *
+ * Visibility rule (the same one a real store must enforce):
+ *   - a connection is only visible within its own `tenantId`;
+ *   - `workspace`-scope connections are visible to every user in the tenant;
+ *   - `per_user`-scope connections are visible only to their `userId` owner.
+ *
+ * The store is pure persistence: it stores the token exactly as given
+ * (`accessTokenObfuscated`, already obfuscated or encrypted by the caller) and
+ * never performs crypto itself.
+ */
+import { randomUUID } from "node:crypto";
+export class InMemoryConnectionStore {
+    records = [];
+    /** Register/save a connection (the "connect" step in a real flow, after the
+     *  OAuth exchange + catalog fetch). Returns the stored row. */
+    addConnection(input) {
+        const scope = input.scope ?? "per_user";
+        if (scope === "per_user" && !input.userId) {
+            throw new Error("per_user connections require a userId");
+        }
+        const record = {
+            tenantId: input.tenantId,
+            connectionId: input.connectionId ?? randomUUID(),
+            accessTokenObfuscated: input.accessTokenObfuscated,
+            toolCatalog: input.toolCatalog ?? { tools: [] },
+            scope,
+            userId: scope === "workspace" ? null : (input.userId ?? null),
+            serverId: input.serverId ?? randomUUID(),
+            serverSlug: input.serverSlug,
+            serverName: input.serverName,
+            mcpEndpoint: input.mcpEndpoint,
+        };
+        this.records.push(record);
+        return this.strip(record);
+    }
+    /** Remove a connection by id. Returns true if a row was removed. */
+    removeConnection(connectionId) {
+        const before = this.records.length;
+        this.records = this.records.filter((r) => r.connectionId !== connectionId);
+        return this.records.length < before;
+    }
+    /** Drop every connection (test/reset helper). */
+    clear() {
+        this.records = [];
+    }
+    /** ConnectionStore contract: rows visible to `identity`, enforcing the tenant
+     *  + scope visibility rule. */
+    async listConnections(identity) {
+        return this.records
+            .filter((r) => r.tenantId === identity.tenantId)
+            .filter((r) => r.scope === "workspace" || r.userId === identity.ownerId)
+            .map((r) => this.strip(r));
+    }
+    strip(record) {
+        // Hand back the neutral StoredConnection shape (drop the internal tenantId).
+        const { tenantId: _tenantId, ...rest } = record;
+        void _tenantId;
+        return rest;
+    }
+}
+//# sourceMappingURL=connection-store-memory.js.map

package/dist/connection-store-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-store-memory.js","sourceRoot":"","sources":["../src/connection-store-memory.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,6BAA6B;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2BzC,MAAM,OAAO,uBAAuB;IAC1B,OAAO,GAAmB,EAAE,CAAC;IAErC;mEAC+D;IAC/D,aAAa,CAAC,KAAyB;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC;QACxC,IAAI,KAAK,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,MAAM,GAAiB;YAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,UAAU,EAAE;YAChD,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;YAClD,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;YAC/C,KAAK;YACL,MAAM,EAAE,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC;YAC7D,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,UAAU,EAAE;YACxC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,oEAAoE;IACpE,gBAAgB,CAAC,YAAoB;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,YAAY,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IACtC,CAAC;IAED,iDAAiD;IACjD,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;mCAC+B;IAC/B,KAAK,CAAC,eAAe,CAAC,QAAkB;QACtC,OAAO,IAAI,CAAC,OAAO;aAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC;aAC/C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC;aACvE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAEO,KAAK,CAAC,MAAoB;QAChC,6EAA6E;QAC7E,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAChD,KAAK,SAAS,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}