@usethrottle/mcp 0.1.0 → 0.2.0

package/dist/lib.d.ts

@@ -0,0 +1,165 @@
+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;
+}
+interface Pagination {
+    cursor: string | null;
+    hasMore: boolean;
+}
+interface ListResult<T> {
+    data: T[];
+    pagination: Pagination | null;
+}
+type Fetcher = typeof fetch;
+declare class ThrottleClient {
+    private readonly auth;
+    private readonly fetchImpl;
+    constructor(auth: AuthCtx, fetchImpl?: Fetcher);
+    private requestJson;
+    /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
+    get<T>(path: string, query?: Record<string, unknown>): Promise<T>;
+    list<T>(path: string, query?: Record<string, unknown>): Promise<ListResult<T>>;
+    post<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 `apps/docs` 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;
+}
+/**
+ * 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;
+}
+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 };