stables-mcp-server 2.3.0 → 2.5.0

package/build/oauth/pages.js

@@ -0,0 +1,80 @@
+/**
+ * The two pages the OAuth flow shows in a browser: consent and error.
+ * Everything that came from the client (its name, domain, scopes) is
+ * escaped, since a dynamically registered client chooses those strings.
+ */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+const STYLE = `
+  :root { color-scheme: light; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #f4f3f8;
+    font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, sans-serif; color: #17151f; }
+  main { width: min(440px, calc(100vw - 32px)); background: #fff; border-radius: 16px;
+    padding: 32px 28px; box-shadow: 0 8px 32px rgba(23, 21, 31, 0.08); }
+  h1 { font-size: 22px; margin: 0 0 8px; }
+  p { margin: 0 0 14px; color: #4a4759; }
+  .brand { font-weight: 700; letter-spacing: 0.02em; color: #5b3df5; margin-bottom: 18px; font-size: 14px; text-transform: uppercase; }
+  .warn { background: #fff7e6; border: 1px solid #f5d58b; border-radius: 10px; padding: 10px 12px; color: #6b4b00; }
+  fieldset { border: 1px solid #e3e1ec; border-radius: 12px; padding: 12px 14px; margin: 18px 0; }
+  legend { padding: 0 6px; font-weight: 600; font-size: 14px; }
+  label.env { display: flex; gap: 10px; align-items: flex-start; padding: 8px 0; cursor: pointer; }
+  label.env input { margin-top: 5px; }
+  label.env small { display: block; color: #6c6880; }
+  .actions { display: flex; gap: 10px; margin-top: 8px; }
+  button { flex: 1; padding: 12px 16px; border-radius: 10px; border: 1px solid #d9d6e6; font: inherit; font-weight: 600; cursor: pointer; background: #fff; }
+  button.primary { background: #5b3df5; border-color: #5b3df5; color: #fff; }
+  code { background: #f1f0f7; padding: 1px 6px; border-radius: 6px; font-size: 14px; }
+`;
+function layout(title, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+<div class="brand">Stables</div>
+${body}
+</main>
+</body>
+</html>`;
+}
+export function consentPage(details, handle) {
+    const name = escapeHtml(details.clientName);
+    const origin = details.clientDomain
+        ? `Published by <strong>${escapeHtml(details.clientDomain)}</strong>.`
+        : "This app registered itself, so its name is not verified.";
+    const loopback = details.redirectIsLoopback
+        ? `<p class="warn"><strong>This sends access to an app on your computer.</strong> Continue only if you just started connecting from it.</p>`
+        : "";
+    return layout(`Connect ${details.clientName} to Stables`, `<h1>Connect ${name} to Stables?</h1>
+<p>${origin} Access will be sent to <strong>${escapeHtml(details.redirectHost)}</strong>.</p>
+${loopback}
+<p>You'll sign in with your Stables dashboard account. Allowing creates an API key named after ${name} in the organisation you choose; revoke it any time under Developer → API keys.</p>
+<form method="post">
+  <input type="hidden" name="handle" value="${escapeHtml(handle)}">
+  <fieldset>
+    <legend>Environment</legend>
+    <label class="env"><input type="radio" name="environment" value="sandbox" checked>
+      <span>Sandbox<small>Test data, no real money. Keys start with <code>sti_test_</code>.</small></span></label>
+    <label class="env"><input type="radio" name="environment" value="production">
+      <span>Production<small>Live organisation. The agent can move real money.</small></span></label>
+  </fieldset>
+  <div class="actions">
+    <button type="submit" name="decision" value="deny">Cancel</button>
+    <button type="submit" name="decision" value="approve" class="primary">Allow and sign in</button>
+  </div>
+</form>`);
+}
+export function errorPage(title, message, hint) {
+    return layout(title, `<h1>${escapeHtml(title)}</h1>
+<p>${escapeHtml(message)}</p>
+${hint ? `<p>${escapeHtml(hint)}</p>` : ""}
+<p>Go back to the app that sent you here and try connecting again.</p>`);
+}
+//# sourceMappingURL=pages.js.map

package/build/oauth/pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.js","sourceRoot":"","sources":["../../src/oauth/pages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;CAmBb,CAAC;AAEF,SAAS,MAAM,CAAC,KAAa,EAAE,IAAY;IACzC,OAAO;;;;;;SAMA,UAAU,CAAC,KAAK,CAAC;SACjB,KAAK;;;;;EAKZ,IAAI;;;QAGE,CAAC;AACT,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAA2B,EAAE,MAAc;IACrE,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY;QACjC,CAAC,CAAC,wBAAwB,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,YAAY;QACtE,CAAC,CAAC,0DAA0D,CAAC;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB;QACzC,CAAC,CAAC,0IAA0I;QAC5I,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,MAAM,CACX,WAAW,OAAO,CAAC,UAAU,aAAa,EAC1C,eAAe,IAAI;KAClB,MAAM,mCAAmC,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC;EAC5E,QAAQ;iGACuF,IAAI;;8CAEvD,UAAU,CAAC,MAAM,CAAC;;;;;;;;;;;;QAYxD,CACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,OAAe,EAAE,IAAa;IACrE,OAAO,MAAM,CACX,KAAK,EACL,OAAO,UAAU,CAAC,KAAK,CAAC;KACvB,UAAU,CAAC,OAAO,CAAC;EACtB,IAAI,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;uEAC6B,CACpE,CAAC;AACJ,CAAC"}

package/build/oauth/provider.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The OAuth provider the Worker runs: authorization server and protected
+ * resource in one, as @cloudflare/workers-oauth-provider's OAuthProvider.
+ *
+ * - /mcp is the protected resource. A grant's props carry the Stables API key
+ *   minted at sign-in, and the request is served with it.
+ * - A plain Stables API key sent as a bearer token keeps working through
+ *   resolveExternalToken, so coding agents configured with a key need no
+ *   OAuth.
+ * - /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server,
+ *   /oauth/token and /oauth/register are the provider's; /authorize and
+ *   /callback are ours (handlers.ts).
+ */
+import { OAuthProvider } from "@cloudflare/workers-oauth-provider";
+import { StablesApiClient } from "../lib/stables-client.js";
+import { type OAuthEnv } from "./types.js";
+export declare function resourceFor(origin: string): string;
+export declare function apiClientFor(apiKey: string, env: OAuthEnv): StablesApiClient | null;
+/** One provider per public origin; metadata and token audiences are bound to it. */
+export declare function providerFor(origin: string): OAuthProvider<OAuthEnv>;
+//# sourceMappingURL=provider.d.ts.map

package/build/oauth/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/oauth/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAsB,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAgB,MAAM,0BAA0B,CAAC;AAG1E,OAAO,EAA4C,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI,CAOnF;AAyBD,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAiDnE"}

package/build/oauth/provider.js

@@ -0,0 +1,95 @@
+/**
+ * The OAuth provider the Worker runs: authorization server and protected
+ * resource in one, as @cloudflare/workers-oauth-provider's OAuthProvider.
+ *
+ * - /mcp is the protected resource. A grant's props carry the Stables API key
+ *   minted at sign-in, and the request is served with it.
+ * - A plain Stables API key sent as a bearer token keeps working through
+ *   resolveExternalToken, so coding agents configured with a key need no
+ *   OAuth.
+ * - /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server,
+ *   /oauth/token and /oauth/register are the provider's; /authorize and
+ *   /callback are ours (handlers.ts).
+ */
+import { ExternalTokenError, OAuthProvider } from "@cloudflare/workers-oauth-provider";
+import { SERVER_VERSION } from "../version.js";
+import { serveMcp, withCors, json } from "../http/handler.js";
+import { StablesApiClient, apiUrlForKey } from "../lib/stables-client.js";
+import { environmentForKey } from "./auth0.js";
+import { handleDefault } from "./handlers.js";
+import { SCOPE, SUPPORTED_SCOPES } from "./types.js";
+export function resourceFor(origin) {
+    return `${origin}/mcp`;
+}
+export function apiClientFor(apiKey, env) {
+    const baseUrl = apiUrlForKey(apiKey);
+    if (!baseUrl)
+        return null;
+    return new StablesApiClient(apiKey, baseUrl, {
+        gatewaySigningSecret: env.MCP_GATEWAY_SIGNING_SECRET,
+        userAgent: `stables-mcp-server/${SERVER_VERSION} (hosted)`,
+    });
+}
+async function serveAuthorizedMcp(request, env, props) {
+    const client = props?.apiKey ? apiClientFor(props.apiKey, env) : null;
+    if (!client) {
+        return withCors(json({
+            error: "invalid_grant",
+            message: "This connection carries no usable Stables API key. Disconnect and connect again.",
+        }, 401));
+    }
+    return withCors(await serveMcp(request, client));
+}
+const providers = new Map();
+/** One provider per public origin; metadata and token audiences are bound to it. */
+export function providerFor(origin) {
+    const cached = providers.get(origin);
+    if (cached)
+        return cached;
+    const resource = resourceFor(origin);
+    const provider = new OAuthProvider({
+        apiRoute: "/mcp",
+        apiHandler: {
+            fetch(request, env, ctx) {
+                const props = ctx.props;
+                return serveAuthorizedMcp(request, env, props);
+            },
+        },
+        defaultHandler: {
+            fetch(request, env) {
+                return handleDefault(request, env);
+            },
+        },
+        authorizeEndpoint: "/authorize",
+        tokenEndpoint: "/oauth/token",
+        // DCR stays on for clients without CIMD support; MCP prefers CIMD.
+        clientRegistrationEndpoint: "/oauth/register",
+        clientIdMetadataDocumentEnabled: true,
+        scopesSupported: SUPPORTED_SCOPES,
+        requiredScopes: [SCOPE],
+        resourceMetadata: {
+            resource,
+            authorization_servers: [origin],
+            resource_name: "Stables MCP server",
+        },
+        accessTokenTTL: 60 * 60,
+        refreshTokenTTL: 30 * 24 * 60 * 60,
+        // A Stables API key presented directly. Sandbox keys go to sandbox and
+        // live keys to production, as the stdio server does.
+        resolveExternalToken: async ({ token }) => {
+            if (!token.startsWith("sti_"))
+                return null;
+            if (!apiUrlForKey(token)) {
+                throw new ExternalTokenError("invalid_token", {
+                    description: "Unrecognised API key. Send a sti_test_ (sandbox) or sti_live_ (production) key, or connect with OAuth.",
+                    statusCode: 401,
+                });
+            }
+            const props = { apiKey: token, environment: environmentForKey(token) };
+            return { props, audience: resource };
+        },
+    });
+    providers.set(origin, provider);
+    return provider;
+}
+//# sourceMappingURL=provider.js.map

package/build/oauth/provider.js.map

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

package/build/oauth/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared shapes for the hosted server's OAuth support.
+ *
+ * The Worker is the OAuth authorization server MCP clients talk to (Claude,
+ * ChatGPT, Cursor, ...). Behind it, Auth0 signs the user in exactly as the
+ * dashboard does, and the Worker then mints a Stables API key for the
+ * organisation the user picked. That key lives in the grant's encrypted
+ * props, so every later MCP request is served with it and the Auth0 token
+ * is never kept.
+ */
+import type { OAuthHelpers } from "@cloudflare/workers-oauth-provider";
+/** The one scope the server grants; tool-level scopes can come later. */
+export declare const SCOPE = "stables";
+export declare const SUPPORTED_SCOPES: string[];
+export type StablesEnvironment = "sandbox" | "production";
+/** What a grant carries; handlers read it as ctx.props. */
+export interface GrantProps {
+    apiKey: string;
+    environment: StablesEnvironment;
+    apiKeyId?: string;
+    email?: string;
+    orgId?: string;
+    clientName?: string;
+}
+/** Bindings and settings the OAuth path needs. See wrangler.toml. */
+export interface OAuthEnv {
+    /** KV namespace the provider stores clients, grants and tokens in. */
+    OAUTH_KV?: unknown;
+    /** Injected by the provider for the default handler. */
+    OAUTH_PROVIDER?: OAuthHelpers;
+    /** Canonical public origin; defaults to the request origin. */
+    MCP_PUBLIC_URL?: string;
+    /** Auth0 custom domain, e.g. login.stables.money. */
+    AUTH0_DOMAIN?: string;
+    AUTH0_CLIENT_ID?: string;
+    /** Worker secret. */
+    AUTH0_CLIENT_SECRET?: string;
+    /** Worker secret shared with api-lambda-authoriser; unset = unsigned. */
+    MCP_GATEWAY_SIGNING_SECRET?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/oauth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/oauth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,yEAAyE;AACzE,eAAO,MAAM,KAAK,YAAY,CAAC;AAC/B,eAAO,MAAM,gBAAgB,UAA4B,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,YAAY,CAAC;AAE1D,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qBAAqB;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC"}

package/build/oauth/types.js

@@ -0,0 +1,14 @@
+/**
+ * Shared shapes for the hosted server's OAuth support.
+ *
+ * The Worker is the OAuth authorization server MCP clients talk to (Claude,
+ * ChatGPT, Cursor, ...). Behind it, Auth0 signs the user in exactly as the
+ * dashboard does, and the Worker then mints a Stables API key for the
+ * organisation the user picked. That key lives in the grant's encrypted
+ * props, so every later MCP request is served with it and the Auth0 token
+ * is never kept.
+ */
+/** The one scope the server grants; tool-level scopes can come later. */
+export const SCOPE = "stables";
+export const SUPPORTED_SCOPES = [SCOPE, "offline_access"];
+//# sourceMappingURL=types.js.map

package/build/oauth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/oauth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,yEAAyE;AACzE,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,CAAC;AAC/B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC"}

package/build/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAWhE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAmB1E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAahE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAqB1E"}

package/build/server.js

@@ -14,6 +14,8 @@ import { registerWebhookTools } from "./tools/webhooks.js";
 import { registerSandboxTools } from "./tools/sandbox.js";
 import { registerBalanceTools } from "./tools/balances.js";
 import { registerEntitlementTools } from "./tools/entitlements.js";
+import { registerComplianceTools } from "./tools/compliance.js";
+import { registerDocumentTools } from "./tools/documents.js";
 import { SERVER_VERSION } from "./version.js";
 export const SERVER_NAME = "stables-mcp-server";
 export { SERVER_VERSION };
@@ -31,6 +33,8 @@ export function createStablesMcpServer(client) {
     registerWebhookTools(server, client);
     registerBalanceTools(server, client);
     registerEntitlementTools(server, client);
+    registerComplianceTools(server, client);
+    registerDocumentTools(server, client);
     registerSandboxTools(server, client);
     return server;
 }

package/build/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,MAAM,UAAU,sBAAsB,CAAC,MAAwB;IAC7D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,sGAAsG;KACzG,CAAC,CAAC;IAEH,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,MAAM,UAAU,sBAAsB,CAAC,MAAwB;IAC7D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,sGAAsG;KACzG,CAAC,CAAC;IAEH,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/build/tools/compliance.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compliance Tools for Stables MCP Server
+ *
+ * Mirrors the Compliance requests (RFIs) reference on docs.stables.money. An RFI
+ * is what Stables compliance needs before it releases a held payment or a held
+ * verification level. Each requirement on it says how to answer: `evidence`
+ * with submit_rfi_evidence, `kyc_level` / `kyc_capability` with a verification
+ * link (get_verification_link), and `manual_review` needs nothing.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StablesApiClient } from "../lib/stables-client.js";
+export declare function registerComplianceTools(server: McpServer, client: StablesApiClient): void;
+//# sourceMappingURL=compliance.d.ts.map

package/build/tools/compliance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compliance.d.ts","sourceRoot":"","sources":["../../src/tools/compliance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAwC,MAAM,0BAA0B,CAAC;AA6DlG,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,QA6IlF"}

package/build/tools/compliance.js

@@ -0,0 +1,170 @@
+/**
+ * Compliance Tools for Stables MCP Server
+ *
+ * Mirrors the Compliance requests (RFIs) reference on docs.stables.money. An RFI
+ * is what Stables compliance needs before it releases a held payment or a held
+ * verification level. Each requirement on it says how to answer: `evidence`
+ * with submit_rfi_evidence, `kyc_level` / `kyc_capability` with a verification
+ * link (get_verification_link), and `manual_review` needs nothing.
+ */
+import { z } from "zod";
+import { StablesApiError } from "../lib/stables-client.js";
+const RFI_STATUSES = ["open", "submitted", "satisfied", "expired", "waived", "rejected"];
+const RFI_TYPES = ["verification", "transaction", "manual"];
+function formatError(error) {
+    if (error instanceof StablesApiError)
+        return `${error.message} (HTTP ${error.statusCode})`;
+    return error instanceof Error ? error.message : "Unknown error";
+}
+function text(value, isError = false) {
+    return { content: [{ type: "text", text: value }], ...(isError && { isError }) };
+}
+/** What the integrator should do next for one requirement. */
+function nextStep(rfi, r) {
+    if (r.status === "satisfied" || r.status === "waived")
+        return "nothing to do";
+    if (r.status === "submitted")
+        return "submitted, waiting for Stables compliance";
+    switch (r.type) {
+        case "evidence":
+            return `answer with get_rfi_evidence_form, then submit_rfi_evidence (customerId ${rfi.customer_id}, rfiId ${rfi.rfi_id}, requirementId ${r.requirement_id})`;
+        case "kyc_level":
+        case "kyc_capability":
+            return r.action?.verification_type
+                ? `send the customer a verification link: get_verification_link with verificationType '${r.action.verification_type}'`
+                : "the customer must complete verification";
+        case "manual_review":
+            return "Stables compliance is reviewing, nothing to submit";
+        default:
+            return "see the RFI in the dashboard";
+    }
+}
+function describeRequirement(rfi, r) {
+    const what = r.required_level ?? r.required_capability ?? r.label ?? r.required_evidence ?? r.type;
+    const sentBack = r.rejection_reason ? ` (sent back: ${r.rejection_reason})` : "";
+    return `  - ${r.type} ${what}: ${r.status}${sentBack}. Next: ${nextStep(rfi, r)}`;
+}
+function describeRfi(rfi) {
+    const about = rfi.subject === "payment"
+        ? `payment ${rfi.transfer_id ?? rfi.transaction_reference_id ?? "(unknown)"}${rfi.transaction_type ? ` (${rfi.transaction_type})` : ""}`
+        : `customer ${rfi.customer_id}`;
+    const reasons = (rfi.reasons ?? []).map((r) => r.description).join("; ");
+    const lines = [
+        `RFI ${rfi.rfi_id}: ${rfi.type}, ${rfi.status}, about ${about}`,
+        reasons ? `  Why: ${reasons}` : "",
+        rfi.message ? `  Message: ${rfi.message}` : "",
+        rfi.rejection_reason ? `  Rejected: ${rfi.rejection_reason}` : "",
+        ...(rfi.requirements ?? []).map((r) => describeRequirement(rfi, r)),
+    ];
+    return lines.filter(Boolean).join("\n");
+}
+function describeList(rfis, empty) {
+    if (rfis.length === 0)
+        return empty;
+    return rfis.map(describeRfi).join("\n\n");
+}
+export function registerComplianceTools(server, client) {
+    server.tool("list_rfis", "List the organisation's compliance requests for information (RFIs), newest first: what Stables compliance needs before it releases a held payment or verification. Open and submitted ones by default. Check this when a transfer or deposit is held, or subscribe to the rfi.* webhooks.", {
+        status: z
+            .array(z.enum(RFI_STATUSES))
+            .optional()
+            .describe("Only these statuses (default: open and submitted)"),
+        type: z.array(z.enum(RFI_TYPES)).optional().describe("Only these RFI types"),
+        customerId: z.string().optional().describe("Only this customer's RFIs"),
+        transactionReferenceId: z
+            .string()
+            .optional()
+            .describe("Only RFIs about this transfer or deposit"),
+        limit: z.number().int().min(1).max(100).optional().describe("Results per page"),
+        cursor: z.string().optional().describe("next_cursor from the previous page"),
+    }, async (params) => {
+        try {
+            const { rfis, next_cursor } = await client.listRfis(params);
+            const more = next_cursor ? `\n\nMore results: pass cursor "${next_cursor}".` : "";
+            return text(describeList(rfis ?? [], "No RFIs match.") + more);
+        }
+        catch (error) {
+            return text(`Failed to list RFIs: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("list_customer_rfis", "List one customer's compliance requests for information (RFIs), with what each requirement needs next.", {
+        customerId: z.string().describe("The customer ID"),
+        status: z.enum(RFI_STATUSES).optional().describe("Only this status"),
+    }, async ({ customerId, status }) => {
+        try {
+            const { rfis } = await client.listCustomerRfis(customerId, status);
+            return text(describeList(rfis ?? [], `Customer ${customerId} has no RFIs.`));
+        }
+        catch (error) {
+            return text(`Failed to list the customer's RFIs: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("get_rfi", "Get one compliance request for information (RFI): why it was raised, its requirements and how to answer each.", {
+        rfiId: z.string().describe("The RFI ID"),
+    }, async ({ rfiId }) => {
+        try {
+            return text(describeRfi(await client.getRfi(rfiId)));
+        }
+        catch (error) {
+            return text(`Failed to get RFI: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("get_rfi_evidence_form", "Get the form an `evidence` requirement on an RFI asks for (for example the source of funds behind one held payment), with the current submission if one was sent. Build the submit_rfi_evidence answers from its fields and documents.", {
+        customerId: z.string().describe("The customer ID"),
+        rfiId: z.string().describe("The RFI ID"),
+        requirementId: z.string().describe("The requirement ID (type 'evidence')"),
+    }, async ({ customerId, rfiId, requirementId }) => {
+        try {
+            const evidence = await client.getRfiEvidence(customerId, rfiId, requirementId);
+            const form = evidence.form ?? {};
+            const fields = (form.fields ?? []).map((f) => `  - ${f.key} (${f.type}${f.required ? ", required" : ""}): ${f.label}${f.description ? `. ${f.description}` : ""}`);
+            const documents = (form.documents ?? []).map((d) => `  - ${d.wire_field} (files as base64 data URLs${d.required ? ", required" : ""}): ${d.label}${d.description ? `. ${d.description}` : ""}`);
+            const lines = [
+                `Evidence requirement ${evidence.requirement_id} (${evidence.required_evidence}): ${evidence.status}`,
+                evidence.rejection_reason ? `Sent back: ${evidence.rejection_reason}` : "",
+                evidence.answerable
+                    ? "It can be answered now."
+                    : "It cannot be answered now (already approved or the RFI is resolved).",
+                form.title ? `\n${form.title}${form.description ? `: ${form.description}` : ""}` : "",
+                fields.length ? `\nFields:\n${fields.join("\n")}` : "",
+                documents.length ? `\nDocuments:\n${documents.join("\n")}` : "",
+                evidence.submission ? "\nA submission is already on file; a new one replaces it." : "",
+            ];
+            return text(lines.filter(Boolean).join("\n"));
+        }
+        catch (error) {
+            return text(`Failed to get the evidence form: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("submit_rfi_evidence", "Submit the answers and documents an `evidence` requirement asks for, in one request, keyed as get_rfi_evidence_form lists them. Files are base64 data URLs ('data:application/pdf;base64,...'). The requirement moves to 'submitted' for Stables compliance to review; approving it releases the held payment once nothing else is outstanding. Confirm the content with a human before sending: it goes to compliance as the customer's answer.", {
+        customerId: z.string().describe("The customer ID"),
+        rfiId: z.string().describe("The RFI ID"),
+        requirementId: z.string().describe("The requirement ID (type 'evidence')"),
+        answers: z
+            .record(z.unknown())
+            .describe("Answers keyed by the form's field keys and document wire_field names, e.g. { funds_origin, funds_origin_explanation, supporting_documents: ['data:application/pdf;base64,...'] }"),
+    }, async ({ customerId, rfiId, requirementId, answers }) => {
+        try {
+            const { rfi } = await client.submitRfiEvidence(customerId, rfiId, requirementId, answers);
+            return text(`Evidence submitted.\n\n${describeRfi(rfi)}`);
+        }
+        catch (error) {
+            return text(`Failed to submit evidence: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("get_kyc_capabilities", "List the verification capabilities a customer holds (for example proof_of_address), the level that granted each, and when. A `kyc_capability` requirement on an RFI is satisfied once the customer holds that capability.", {
+        customerId: z.string().describe("The customer ID"),
+    }, async ({ customerId }) => {
+        try {
+            const { capabilities } = await client.getKycCapabilities(customerId);
+            if (!capabilities?.length)
+                return text(`Customer ${customerId} holds no capabilities yet.`);
+            const lines = capabilities.map((c) => `- ${c.capability}: ${c.status} (from ${c.kyc_level}, granted ${c.granted_at})`);
+            return text(`Capabilities held by ${customerId}:\n${lines.join("\n")}`);
+        }
+        catch (error) {
+            return text(`Failed to get KYC capabilities: ${formatError(error)}`, true);
+        }
+    });
+}
+//# sourceMappingURL=compliance.js.map

package/build/tools/compliance.js.map

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

package/build/tools/documents.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Document Tools for Stables MCP Server
+ *
+ * Mirrors the Transfer Documents and Deposit Documents references on
+ * docs.stables.money: attach an invoice, contract or other supporting document
+ * to a transfer or to a payment route deposit, for example when Stables
+ * compliance asks for one, then list, download or remove it.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StablesApiClient } from "../lib/stables-client.js";
+export declare function registerDocumentTools(server: McpServer, client: StablesApiClient): void;
+//# sourceMappingURL=documents.d.ts.map

package/build/tools/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/tools/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAwC,MAAM,0BAA0B,CAAC;AAsBlG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,QAyFhF"}

package/build/tools/documents.js

@@ -0,0 +1,94 @@
+/**
+ * Document Tools for Stables MCP Server
+ *
+ * Mirrors the Transfer Documents and Deposit Documents references on
+ * docs.stables.money: attach an invoice, contract or other supporting document
+ * to a transfer or to a payment route deposit, for example when Stables
+ * compliance asks for one, then list, download or remove it.
+ */
+import { z } from "zod";
+import { StablesApiError } from "../lib/stables-client.js";
+const OWNER = z
+    .enum(["transfer", "deposit"])
+    .describe("What the document belongs to: a transfer, or a deposit on a payment route");
+const TRANSACTION_ID = z
+    .string()
+    .describe("The transfer ID, or the deposit ID from get_virtual_account_history");
+function formatError(error) {
+    if (error instanceof StablesApiError)
+        return `${error.message} (HTTP ${error.statusCode})`;
+    return error instanceof Error ? error.message : "Unknown error";
+}
+function text(value, isError = false) {
+    return { content: [{ type: "text", text: value }], ...(isError && { isError }) };
+}
+function describeDocument(d) {
+    return `- ${d.document_id}: ${d.file_name} (${d.type}, ${d.content_type}, ${d.size_bytes} bytes, added ${d.created_at})`;
+}
+export function registerDocumentTools(server, client) {
+    server.tool("add_document", "Attach a supporting document (invoice, contract or other) to a transfer or a payment route deposit, for example when Stables compliance asks for one. The file goes as a base64 data URL ('data:application/pdf;base64,...').", {
+        on: OWNER,
+        transactionId: TRANSACTION_ID,
+        fileName: z.string().describe("File name shown to Stables, e.g. 'invoice-2041.pdf'"),
+        base64Url: z.string().describe("The file as a data URL: 'data:<mime>;base64,<data>'"),
+        type: z
+            .enum(["invoice", "contract", "other"])
+            .optional()
+            .describe("What the document is (default other)"),
+    }, async ({ on, transactionId, fileName, base64Url, type }) => {
+        try {
+            const { document } = await client.addDocument(on, transactionId, {
+                file_name: fileName,
+                base64_url: base64Url,
+                ...(type && { type }),
+            });
+            return text(`Document attached to ${on} ${transactionId}:\n${describeDocument(document)}`);
+        }
+        catch (error) {
+            return text(`Failed to attach the document: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("list_documents", "List the documents attached to a transfer or a payment route deposit, newest first.", {
+        on: OWNER,
+        transactionId: TRANSACTION_ID,
+    }, async ({ on, transactionId }) => {
+        try {
+            const { documents } = await client.listDocuments(on, transactionId);
+            if (!documents?.length)
+                return text(`No documents on ${on} ${transactionId}.`);
+            return text(`Documents on ${on} ${transactionId}:\n${documents.map(describeDocument).join("\n")}`);
+        }
+        catch (error) {
+            return text(`Failed to list documents: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("get_document_download_url", "Get a short-lived link to download a document attached to a transfer or a payment route deposit.", {
+        on: OWNER,
+        transactionId: TRANSACTION_ID,
+        documentId: z.string().describe("The document ID from list_documents"),
+    }, async ({ on, transactionId, documentId }) => {
+        try {
+            const link = await client.getDocumentDownloadUrl(on, transactionId, documentId);
+            return text(`Download ${link.file_name} (${link.content_type}), valid for ${link.expires_in} seconds:\n${link.url}`);
+        }
+        catch (error) {
+            return text(`Failed to get the download link: ${formatError(error)}`, true);
+        }
+    });
+    server.tool("delete_document", "Remove a document from a transfer or a payment route deposit. This cannot be undone, so confirm with a human first.", {
+        on: OWNER,
+        transactionId: TRANSACTION_ID,
+        documentId: z.string().describe("The document ID from list_documents"),
+    }, async ({ on, transactionId, documentId }) => {
+        try {
+            const { deleted } = await client.deleteDocument(on, transactionId, documentId);
+            return text(deleted
+                ? `Document ${documentId} removed from ${on} ${transactionId}.`
+                : `Document ${documentId} was not removed.`);
+        }
+        catch (error) {
+            return text(`Failed to remove the document: ${formatError(error)}`, true);
+        }
+    });
+}
+//# sourceMappingURL=documents.js.map