@layers/amba-mcp 0.1.1 → 1.0.0

package/dist/api-client.d.ts

@@ -0,0 +1,66 @@
+export interface ApiClientOptions {
+    baseUrl?: string;
+    /**
+     * Optional override for token resolution. When provided, the client uses
+     * this in place of `loadCredentials()` (the CLI's `~/.amba/credentials.json`
+     * flow) — this is what the hosted MCP server uses to forward the developer's
+     * Bearer token from the inbound HTTP request to the downstream API call.
+     *
+     * The provider is invoked once per request, so callers can rotate or refresh
+     * tokens transparently. Sync values should be wrapped in `() => Promise.resolve(token)`.
+     */
+    getToken?: () => Promise<string>;
+}
+export declare class ApiClient {
+    private baseUrl;
+    private apiRoot;
+    private tokenProvider?;
+    constructor(options?: ApiClientOptions);
+    /**
+     * Returns the configured admin-prefixed base URL (e.g.
+     * `https://api.amba.dev/admin`). Auth tools (`amba_developer_signup`,
+     * `amba_developer_login`, `amba_developer_refresh`) need a sibling root
+     * because the public `/auth/developer/*` endpoints are NOT under `/admin`.
+     */
+    getBaseUrl(): string;
+    /**
+     * Returns the API root with the trailing `/admin` segment stripped —
+     * computed once at construction so tools targeting sibling routes
+     * (`/auth/developer/*`) get a stable root regardless of trailing-slash
+     * normalisation. The constructor enforces the `/admin` suffix invariant.
+     */
+    getApiRoot(): string;
+    /**
+     * Resolve the current developer Bearer token, going through the configured
+     * tokenProvider (or `~/.amba/credentials.json` for the CLI fallback).
+     *
+     * Returns `null` if no provider is configured AND no credentials file exists
+     * — useful for tools like `amba_developer_signup` that may run with no
+     * inbound Bearer at all. All other code paths should treat a thrown error
+     * as a hard auth failure (e.g. expired token).
+     */
+    resolveTokenOrNull(): Promise<string | null>;
+    private getToken;
+    private request;
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    /**
+     * GET that returns the raw response body as a string and only reads up to
+     * `maxBytes` bytes. Used by export tools that hit CSV/NDJSON streaming
+     * endpoints — JSON parsing isn't applicable, and we cap at 10k rows worth
+     * of bytes so a multi-million-row export can't blow the MCP context window.
+     *
+     * Errors are still parsed via the JSON envelope where possible to keep the
+     * thrown message human-readable (matches the regular request() behavior).
+     */
+    getRaw(path: string, query?: Record<string, string>, options?: {
+        maxBytes?: number;
+    }): Promise<{
+        body: string;
+        truncated: boolean;
+        contentType: string | null;
+    }>;
+}

package/dist/auth.d.ts

@@ -0,0 +1,7 @@
+export interface Credentials {
+    access_token: string;
+    refresh_token: string;
+    expires_at: string;
+}
+export declare function loadCredentials(): Promise<Credentials>;
+export declare function isTokenExpired(credentials: Credentials): boolean;

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Library entry for `@layers/amba-mcp`.
+ *
+ * Reusable MCP tool registry consumed by `mcp.amba.dev`. It registers
+ * 100+ MCP tools — every Amba admin operation, basically — against an
+ * injected `McpServer` and `ApiClient`. It does NOT bootstrap a transport.
+ *
+ * The hosted server mounts the registry behind the official MCP
+ * **Streamable HTTP** transport so AI agents (Claude Desktop, Cursor,
+ * Windsurf, …) can connect by URL +
+ * `Authorization: Bearer <developer-access-token>`.
+ *
+ * Tool-group files in `./tools/*` only depend on `McpServer` + `ApiClient`.
+ * They MUST stay free of transport coupling so the registry can run inside
+ * any MCP transport, including future ones (SSE, WebSockets, …).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ApiClient } from './api-client.js';
+/**
+ * Register every Amba MCP tool group against the given server, using the
+ * given API client. A single `McpServer` instance should only have this
+ * called against it once.
+ */
+export declare function registerAllTools(server: McpServer, apiClient: ApiClient): void;
+/**
+ * Convenience factory used by the hosted MCP server to build a per-request
+ * `ApiClient` whose Bearer token comes from the inbound HTTP `Authorization`
+ * header. Equivalent to `new ApiClient({ baseUrl, getToken: async () => token })`.
+ *
+ * If `token` is omitted the client falls back to `~/.amba/credentials.json`
+ * — that path is only useful for tests or local-dev scripts; production
+ * hosted-MCP traffic always passes an explicit token.
+ */
+export declare function createApiClient(options: {
+    baseUrl?: string;
+    token?: string;
+}): ApiClient;
+export { ApiClient } from './api-client.js';
+export type { ApiClientOptions } from './api-client.js';