@usethrottle/mcp 0.1.1 → 0.2.1

package/dist/lib.d.cts

@@ -0,0 +1,219 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ActionDefinition } from '@core/action-catalog';
+
+interface AuthCtx {
+    apiKey: string;
+    apiBaseUrl: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, unknown>;
+    /**
+     * Sent as `Idempotency-Key`. Writes must pass one: an agent that retries is the
+     * normal case, and the API dedupes on
+     * `(workspace, application, environment, key, method, path)`.
+     */
+    idempotencyKey?: string;
+    /**
+     * Sent as `X-Throttle-Application-Id` on this one request only — see
+     * `PerCallOptions`.
+     */
+    applicationId?: string;
+}
+interface PerCallOptions {
+    /**
+     * Overrides which application a single `get`/`list` call reads from (the
+     * `oauth_token` auth branch validates this against the grant's own
+     * workspace membership; see `resolveOAuthApplication`). Scoped to this one
+     * request — never stored on the client instance — so concurrent calls with
+     * different application ids cannot bleed into each other.
+     */
+    applicationId?: string;
+}
+interface Pagination {
+    cursor: string | null;
+    hasMore: boolean;
+}
+interface ListResult<T> {
+    data: T[];
+    pagination: Pagination | null;
+}
+type Fetcher = typeof fetch;
+declare class ThrottleClient {
+    private auth;
+    private readonly fetchImpl;
+    constructor(auth: AuthCtx, fetchImpl?: Fetcher);
+    /**
+     * Swap the credential every later request is sent with. The hosted remote
+     * server builds one client per MCP session at `initialize`, but an OAuth
+     * access token lives one hour and the MCP client refreshes it underneath
+     * the session — each request then arrives with a newer bearer than the one
+     * the session was opened with. Without this, the session keeps calling the
+     * REST API with the token it was born with and every tool fails with a 401
+     * the moment that first token expires, even though the caller is still
+     * perfectly authenticated.
+     */
+    setApiKey(apiKey: string): void;
+    private requestJson;
+    /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
+    get<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<T>;
+    list<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<ListResult<T>>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * `describe_endpoint` and `validate_payload`, answered from the OpenAPI contract
+ * bundled at build time. No network, no API quota.
+ *
+ * Why this exists: Throttle's public API is strict camelCase and rejects the
+ * retired snake_case aliases — and those aliases are exactly what a model writing
+ * commerce code will guess, because that is what the rest of the internet's
+ * examples look like. Naming the replacement turns a 400-debug loop into one call.
+ */
+interface ContractField {
+    name: string;
+    type?: string;
+    required: boolean;
+    description?: string;
+    enum?: string[];
+}
+interface ContractOperation {
+    method: string;
+    /** OpenAPI-style path, e.g. `/api/v1/customers/{customerId}/addresses/{id}`. */
+    path: string;
+    summary?: string;
+    description?: string;
+    pathParams: string[];
+    queryParams: ContractField[];
+    bodyFields: ContractField[] | null;
+}
+interface ContractIndex {
+    generatedAt: string;
+    operations: ContractOperation[];
+}
+
+/**
+ * `search_docs`, answered from an index of the docs pages in `apps/web`,
+ * bundled at build time.
+ *
+ * Scoring mirrors the CLI's proven approach: title hits beat heading hits, which
+ * beat body hits, and an exact phrase beats scattered terms. Deliberately simple —
+ * the agent gets a title, a canonical docs.usethrottle.dev URL and an excerpt, then
+ * fetches the page itself if its client can.
+ */
+interface DocsEntry {
+    title: string;
+    route: string;
+    headings: string[];
+    text: string;
+}
+interface DocsIndex {
+    generatedAt: string;
+    entries: DocsEntry[];
+}
+
+interface Identity {
+    type: string;
+    scopes: string[];
+    workspace: {
+        id: string;
+        name: string | null;
+        slug: string | null;
+    } | null;
+    application: {
+        id: string;
+        name: string | null;
+        slug: string | null;
+    } | null;
+    environment: {
+        id: string;
+        slug: string;
+        kind: string;
+        providerEnvironment: 'sandbox' | 'production';
+    };
+    apiKey: {
+        id: string;
+        name: string;
+        keyPrefix: string;
+    } | null;
+}
+interface HandlerContext {
+    client: ThrottleClient;
+    identity: Identity;
+    contract: ContractIndex;
+    docs: DocsIndex;
+}
+
+declare const VERSION: string;
+interface RegistrationPolicy {
+    identity: Identity;
+    allowWrites: boolean;
+    allowLiveWrites: boolean;
+    /**
+     * Whether sandbox-only writes (`seed_test_data`) register without
+     * `allowWrites`. Defaults to true — the documented CLI behaviour, where
+     * seeding a non-production environment needs no flag. The hosted remote
+     * server passes false: it is published as strictly read-only, and a
+     * directory reviewer connecting with a non-production credential must not
+     * find a tool that creates customers and orders.
+     */
+    allowSandboxWrites?: boolean;
+    /**
+     * Whether `credentialScoped` actions (`api_get`) register. Defaults to true
+     * for the CLI. The hosted server passes false: on an OAuth surface every
+     * tool declares the scopes it asks consent for, and a tool that reads any
+     * path cannot.
+     */
+    allowCredentialScoped?: boolean;
+}
+/**
+ * Which tools this session gets. Pure and exported so the policy is testable
+ * without standing up a transport.
+ *
+ * Four independent gates, in order of how expensive it is to get them wrong:
+ *
+ * 1. **Implemented.** `0.1.0` ships the read/sandbox half; the catalog describes
+ *    the money writes before this package implements them.
+ * 2. **Scope.** Delegated to the catalog's `canRunAction`, which uses the API's own
+ *    `hasScope`. A tool the credential cannot execute is not registered at all,
+ *    rather than failing at call time — the model never sees an affordance it
+ *    cannot use.
+ * 3. **Intent.** Holding a write scope means the credential *may* write; it does
+ *    not mean the operator intended this session to. That is `--allow-writes`.
+ * 4. **Blast radius.** Against a production credential, writes need
+ *    `--allow-live-writes` on top. Sandbox-only actions invert the rule: they are
+ *    free in a non-production environment and forbidden in production regardless
+ *    of flags.
+ */
+declare function registerableActions(policy: RegistrationPolicy): ActionDefinition[];
+/**
+ * The server's `instructions`, which most clients put in front of the model before
+ * it picks a tool. Leads with the environment because the single most damaging
+ * mistake an agent can make here is not knowing whether it is looking at live data.
+ */
+declare function buildInstructions(identity: Identity, actions: ActionDefinition[], policy: {
+    allowWrites: boolean;
+    allowLiveWrites: boolean;
+}): string;
+interface CreateServerOptions extends RegistrationPolicy {
+    client: ThrottleClient;
+    contract: ContractIndex;
+    docs: DocsIndex;
+    /**
+     * The `WWW-Authenticate` challenge value the hosting transport advertises
+     * (RFC 9728 `Bearer resource_metadata="..."`). When set, a tool call that
+     * fails because the REST API rejected the credential (HTTP 401 — an expired
+     * or revoked OAuth access token) carries it back as
+     * `_meta["mcp/www_authenticate"]`, which is what ChatGPT and other remote
+     * clients key their re-authorization UI on. The stdio CLI leaves it unset:
+     * its operator-provided key has no re-auth flow to trigger.
+     */
+    authChallenge?: string;
+}
+declare function createServer(options: CreateServerOptions): McpServer;
+
+declare function loadDocsIndex(): DocsIndex;
+declare function loadContractIndex(): ContractIndex;
+
+export { type ContractIndex, type CreateServerOptions, type DocsIndex, type HandlerContext, type Identity, type RegistrationPolicy, ThrottleClient, VERSION, buildInstructions, createServer, loadContractIndex, loadDocsIndex, registerableActions };

package/dist/lib.d.ts

@@ -0,0 +1,219 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ActionDefinition } from '@core/action-catalog';
+
+interface AuthCtx {
+    apiKey: string;
+    apiBaseUrl: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, unknown>;
+    /**
+     * Sent as `Idempotency-Key`. Writes must pass one: an agent that retries is the
+     * normal case, and the API dedupes on
+     * `(workspace, application, environment, key, method, path)`.
+     */
+    idempotencyKey?: string;
+    /**
+     * Sent as `X-Throttle-Application-Id` on this one request only — see
+     * `PerCallOptions`.
+     */
+    applicationId?: string;
+}
+interface PerCallOptions {
+    /**
+     * Overrides which application a single `get`/`list` call reads from (the
+     * `oauth_token` auth branch validates this against the grant's own
+     * workspace membership; see `resolveOAuthApplication`). Scoped to this one
+     * request — never stored on the client instance — so concurrent calls with
+     * different application ids cannot bleed into each other.
+     */
+    applicationId?: string;
+}
+interface Pagination {
+    cursor: string | null;
+    hasMore: boolean;
+}
+interface ListResult<T> {
+    data: T[];
+    pagination: Pagination | null;
+}
+type Fetcher = typeof fetch;
+declare class ThrottleClient {
+    private auth;
+    private readonly fetchImpl;
+    constructor(auth: AuthCtx, fetchImpl?: Fetcher);
+    /**
+     * Swap the credential every later request is sent with. The hosted remote
+     * server builds one client per MCP session at `initialize`, but an OAuth
+     * access token lives one hour and the MCP client refreshes it underneath
+     * the session — each request then arrives with a newer bearer than the one
+     * the session was opened with. Without this, the session keeps calling the
+     * REST API with the token it was born with and every tool fails with a 401
+     * the moment that first token expires, even though the caller is still
+     * perfectly authenticated.
+     */
+    setApiKey(apiKey: string): void;
+    private requestJson;
+    /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
+    get<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<T>;
+    list<T>(path: string, query?: Record<string, unknown>, options?: PerCallOptions): Promise<ListResult<T>>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * `describe_endpoint` and `validate_payload`, answered from the OpenAPI contract
+ * bundled at build time. No network, no API quota.
+ *
+ * Why this exists: Throttle's public API is strict camelCase and rejects the
+ * retired snake_case aliases — and those aliases are exactly what a model writing
+ * commerce code will guess, because that is what the rest of the internet's
+ * examples look like. Naming the replacement turns a 400-debug loop into one call.
+ */
+interface ContractField {
+    name: string;
+    type?: string;
+    required: boolean;
+    description?: string;
+    enum?: string[];
+}
+interface ContractOperation {
+    method: string;
+    /** OpenAPI-style path, e.g. `/api/v1/customers/{customerId}/addresses/{id}`. */
+    path: string;
+    summary?: string;
+    description?: string;
+    pathParams: string[];
+    queryParams: ContractField[];
+    bodyFields: ContractField[] | null;
+}
+interface ContractIndex {
+    generatedAt: string;
+    operations: ContractOperation[];
+}
+
+/**
+ * `search_docs`, answered from an index of the docs pages in `apps/web`,
+ * bundled at build time.
+ *
+ * Scoring mirrors the CLI's proven approach: title hits beat heading hits, which
+ * beat body hits, and an exact phrase beats scattered terms. Deliberately simple —
+ * the agent gets a title, a canonical docs.usethrottle.dev URL and an excerpt, then
+ * fetches the page itself if its client can.
+ */
+interface DocsEntry {
+    title: string;
+    route: string;
+    headings: string[];
+    text: string;
+}
+interface DocsIndex {
+    generatedAt: string;
+    entries: DocsEntry[];
+}
+
+interface Identity {
+    type: string;
+    scopes: string[];
+    workspace: {
+        id: string;
+        name: string | null;
+        slug: string | null;
+    } | null;
+    application: {
+        id: string;
+        name: string | null;
+        slug: string | null;
+    } | null;
+    environment: {
+        id: string;
+        slug: string;
+        kind: string;
+        providerEnvironment: 'sandbox' | 'production';
+    };
+    apiKey: {
+        id: string;
+        name: string;
+        keyPrefix: string;
+    } | null;
+}
+interface HandlerContext {
+    client: ThrottleClient;
+    identity: Identity;
+    contract: ContractIndex;
+    docs: DocsIndex;
+}
+
+declare const VERSION: string;
+interface RegistrationPolicy {
+    identity: Identity;
+    allowWrites: boolean;
+    allowLiveWrites: boolean;
+    /**
+     * Whether sandbox-only writes (`seed_test_data`) register without
+     * `allowWrites`. Defaults to true — the documented CLI behaviour, where
+     * seeding a non-production environment needs no flag. The hosted remote
+     * server passes false: it is published as strictly read-only, and a
+     * directory reviewer connecting with a non-production credential must not
+     * find a tool that creates customers and orders.
+     */
+    allowSandboxWrites?: boolean;
+    /**
+     * Whether `credentialScoped` actions (`api_get`) register. Defaults to true
+     * for the CLI. The hosted server passes false: on an OAuth surface every
+     * tool declares the scopes it asks consent for, and a tool that reads any
+     * path cannot.
+     */
+    allowCredentialScoped?: boolean;
+}
+/**
+ * Which tools this session gets. Pure and exported so the policy is testable
+ * without standing up a transport.
+ *
+ * Four independent gates, in order of how expensive it is to get them wrong:
+ *
+ * 1. **Implemented.** `0.1.0` ships the read/sandbox half; the catalog describes
+ *    the money writes before this package implements them.
+ * 2. **Scope.** Delegated to the catalog's `canRunAction`, which uses the API's own
+ *    `hasScope`. A tool the credential cannot execute is not registered at all,
+ *    rather than failing at call time — the model never sees an affordance it
+ *    cannot use.
+ * 3. **Intent.** Holding a write scope means the credential *may* write; it does
+ *    not mean the operator intended this session to. That is `--allow-writes`.
+ * 4. **Blast radius.** Against a production credential, writes need
+ *    `--allow-live-writes` on top. Sandbox-only actions invert the rule: they are
+ *    free in a non-production environment and forbidden in production regardless
+ *    of flags.
+ */
+declare function registerableActions(policy: RegistrationPolicy): ActionDefinition[];
+/**
+ * The server's `instructions`, which most clients put in front of the model before
+ * it picks a tool. Leads with the environment because the single most damaging
+ * mistake an agent can make here is not knowing whether it is looking at live data.
+ */
+declare function buildInstructions(identity: Identity, actions: ActionDefinition[], policy: {
+    allowWrites: boolean;
+    allowLiveWrites: boolean;
+}): string;
+interface CreateServerOptions extends RegistrationPolicy {
+    client: ThrottleClient;
+    contract: ContractIndex;
+    docs: DocsIndex;
+    /**
+     * The `WWW-Authenticate` challenge value the hosting transport advertises
+     * (RFC 9728 `Bearer resource_metadata="..."`). When set, a tool call that
+     * fails because the REST API rejected the credential (HTTP 401 — an expired
+     * or revoked OAuth access token) carries it back as
+     * `_meta["mcp/www_authenticate"]`, which is what ChatGPT and other remote
+     * clients key their re-authorization UI on. The stdio CLI leaves it unset:
+     * its operator-provided key has no re-auth flow to trigger.
+     */
+    authChallenge?: string;
+}
+declare function createServer(options: CreateServerOptions): McpServer;
+
+declare function loadDocsIndex(): DocsIndex;
+declare function loadContractIndex(): ContractIndex;
+
+export { type ContractIndex, type CreateServerOptions, type DocsIndex, type HandlerContext, type Identity, type RegistrationPolicy, ThrottleClient, VERSION, buildInstructions, createServer, loadContractIndex, loadDocsIndex, registerableActions };