@datadive-tools/mcp 0.7.0 → 0.9.0

package/dist/lib.d.ts

@@ -0,0 +1,184 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Loads and validates the server's runtime configuration from environment.
+ *
+ * Required:
+ *   DATADIVE_API_KEY        - your DataDive API key (generate at 2.datadive.tools/api-key)
+ *
+ * Optional:
+ *   DATADIVE_API_BASE_URL        - override the API base URL (defaults to https://api.datadive.tools)
+ *   DATADIVE_AUTO_CONFIRM_WRITES - skip the confirm gate on token-spending write tools
+ *                                  (create_niche_dive, create_rank_radar). Truthy =
+ *                                  "1"/"true"/"yes" (case-insensitive). Defaults to false.
+ *
+ * The env-based loader always produces api-key credentials (the local stdio path).
+ * A remote host embedding this package builds a Config directly with bearer
+ * credentials (the OAuth path) — see Credentials.
+ */
+/** OAuth scope covering the read tools. */
+declare const SCOPE_READ = "datadive.read";
+/** OAuth scope covering the token-spending write tools. */
+declare const SCOPE_WRITE = "datadive.write";
+/**
+ * How the HTTP client authenticates against the DataDive /v1 API.
+ *  - "api-key": the local stdio path — sends `x-api-key` (DATADIVE_API_KEY).
+ *  - "bearer":  the remote/OAuth path — sends `Authorization: Bearer <token>`.
+ *               The token is read at request time, so a host may mutate the
+ *               credentials object to rotate a refreshed access token in place.
+ */
+type Credentials = {
+    kind: "api-key";
+    apiKey: string;
+} | {
+    kind: "bearer";
+    token: string;
+};
+interface Config {
+    credentials: Credentials;
+    baseUrl: string;
+    /**
+     * When true, the token-spending write tools proceed without requiring `confirm: true`.
+     * A user-controlled "don't ask me again" opt-out, set via DATADIVE_AUTO_CONFIRM_WRITES.
+     */
+    autoConfirmWrites: boolean;
+    /**
+     * OAuth scopes granted to this session. When set, tool calls are gated:
+     * read tools require SCOPE_READ and write tools SCOPE_WRITE (see server.ts).
+     * Undefined (the stdio/api-key path) means no scope gating.
+     */
+    scopes?: readonly string[];
+}
+declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+
+/**
+ * Shared tool-definition shape consumed by the registry in src/server.ts.
+ *
+ * Each tool file exports a single `ToolDefinition` so adding tool #N+1 in v1.1
+ * is a one-file change (plus appending to `allTools` in tools/index.ts).
+ */
+
+interface HandlerContext {
+    config: Config;
+}
+interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
+    /** Snake_case tool name shown to the LLM (e.g. "list_niches"). */
+    name: string;
+    /** Human-readable title (shown in some MCP UIs). */
+    title: string;
+    /**
+     * Tool description — the primary signal for LLM tool selection.
+     * Convention: lead with "Use this when..." then describe inputs and what's returned.
+     */
+    description: string;
+    /** Zod raw shape (object of Zod field schemas) — passed through to MCP SDK. */
+    inputSchema: S;
+    /**
+     * Optional MCP behavior hints (readOnlyHint, destructiveHint, etc.) so clients can
+     * flag token-spending write tools in their approval UI. Read tools may omit this.
+     */
+    annotations?: ToolAnnotations;
+    /** Returns the data payload to be JSON-stringified in the tool response. */
+    handler: (args: z.infer<z.ZodObject<S>>, ctx: HandlerContext) => Promise<unknown>;
+}
+/**
+ * Type-erased tool used by the registry. The MCP SDK validates `args` against
+ * `inputSchema` before calling `handler`, so `Record<string, unknown>` is sound
+ * at the call site even though each tool's handler internally expects a tighter
+ * inferred shape.
+ */
+interface AnyTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    annotations?: ToolAnnotations;
+    handler: (args: Record<string, unknown>, ctx: HandlerContext) => Promise<unknown>;
+}
+
+/**
+ * Builds the MCP server: registers each tool from the registry with the SDK.
+ *
+ * Error handling: if a tool handler throws (most commonly an ApiError from the
+ * HTTP client), we surface the message back through MCP as a tool-level error
+ * (`isError: true`). The LLM sees the message and can react — e.g. tell the
+ * user to regenerate their API key on a 401.
+ */
+
+/**
+ * Returns the OAuth scope a tool call needs: SCOPE_READ for read-only tools,
+ * SCOPE_WRITE for the token-spending writes. Classification comes from the
+ * `readOnlyHint` annotation, which every tool in the registry carries.
+ */
+declare function requiredScope(tool: Pick<AnyTool, "annotations">): string;
+declare function buildServer(config: Config): McpServer;
+
+/**
+ * Tool registry. The order here is the order tools appear in `tools/list`
+ * over the MCP transport, which biases LLM discovery — keep "discovery" tools
+ * (the ones that return IDs needed by other tools) at the top.
+ */
+
+declare const allTools: ReadonlyArray<AnyTool>;
+
+/**
+ * Error mapping for the DataDive /v1 API.
+ *
+ * The MCP server is a thin HTTP shim — when api.datadive.tools returns an error,
+ * we want the LLM (and ultimately the user) to see a useful, actionable message
+ * rather than "Request failed". `ApiError.fromHttp` turns an HTTP status + body
+ * into one of those messages.
+ *
+ * Source of truth for status semantics:
+ *   datadive-backend/src/external-api/auth/api-key.guard.ts (401/402 logic)
+ *   datadive-backend/src/external-api/external-api-v1.controller.ts (per-route docs)
+ */
+type ApiErrorKind = "auth" | "payment" | "forbidden" | "not_found" | "bad_request" | "rate_limit" | "server" | "network" | "http";
+declare class ApiError extends Error {
+    readonly kind: ApiErrorKind;
+    readonly status: number;
+    readonly body: unknown;
+    constructor(kind: ApiErrorKind, status: number, message: string, body?: unknown);
+    static fromHttp(status: number, body: unknown): ApiError;
+}
+
+/**
+ * HTTP client for the DataDive /v1 API.
+ *
+ * Responsibilities:
+ *   1. Attach auth from config.credentials to every request — `x-api-key` (local
+ *      stdio path) or `Authorization: Bearer` (remote/OAuth path).
+ *   2. Tag the User-Agent with the package version + tool name so backend access
+ *      logs can attribute usage per tool (no separate telemetry endpoint needed).
+ *   3. Map HTTP errors via `ApiError.fromHttp`.
+ *   4. Unwrap the `ResponseDto<T>` envelope (`{ message?, success?, data }`)
+ *      while preserving bare `PaginationResponse<T>` bodies (which need their
+ *      pagination metadata to reach the LLM).
+ *
+ * Envelope detection (verified against datadive-backend):
+ *   - GET /v1/niches            -> NicheList extends PaginationResponse<NicheItem>  (BARE)
+ *   - GET /v1/niches/rank-radars -> ResponseDto<ExternalRankRadarListResponseDto>
+ *                                   where the inner DTO IS itself paginated.
+ *   - All other read endpoints  -> ResponseDto<T>                                  (UNWRAP)
+ *
+ * Heuristic: if the body has `data` AND any pagination key (currentPage, lastPage,
+ * hasNext, hasPrev, pageSize, total), it's a PaginationResponse — return as-is.
+ * Otherwise if the body has `data`, it's a ResponseDto envelope — return body.data.
+ *
+ * Cite: datadive-backend/src/common/pagination/pagination.dto.ts (pagination keys)
+ *       datadive-backend/src/common/dto/response.dto.ts          (envelope shape)
+ */
+
+/**
+ * The running package version, inlined from package.json at build time by
+ * tsup/esbuild (and by vite under vitest). Single source of truth — no manual
+ * bump here, so it can never drift from what's published to npm.
+ *
+ * Written into the User-Agent header, and compared against the backend's
+ * advertised latest version (see noteLatestVersion) to nudge stale installs.
+ */
+declare const PKG_VERSION: string;
+
+export { type AnyTool, ApiError, type Config, type Credentials, PKG_VERSION, SCOPE_READ, SCOPE_WRITE, type ToolDefinition, allTools, buildServer, loadConfig, requiredScope };