@datadive-tools/mcp 0.10.0 → 0.12.0

package/dist/lib.d.ts

@@ -60,6 +60,29 @@ declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
  * is a one-file change (plus appending to `allTools` in tools/index.ts).
  */
 
+/**
+ * Tool annotations with `readOnlyHint` promoted to required.
+ *
+ * The MCP spec leaves every hint optional, but the in-product connector
+ * directories (Claude's Connectors Directory, ChatGPT's apps directory) reject a
+ * server whose tools do not declare read-vs-write behaviour, and a client cannot
+ * render an approval prompt without it. Making it required here means tool #N+1
+ * cannot silently regress the listing — the compiler catches it.
+ *
+ * Write tools (`readOnlyHint: false`) must additionally declare:
+ *
+ * - `destructiveHint` — per spec only meaningful on writes; Claude always prompts on it.
+ * - `openWorldHint` — OpenAI's plugin review requires it on every write tool: `true` if
+ *   the tool changes publicly visible internet state, `false` for a closed system like a
+ *   customer's own DataDive account. Missing or wrong values are a named rejection cause.
+ */
+type RequiredToolAnnotations = ToolAnnotations & ({
+    readOnlyHint: true;
+} | {
+    readOnlyHint: false;
+    destructiveHint: boolean;
+    openWorldHint: boolean;
+});
 interface HandlerContext {
     config: Config;
 }
@@ -76,10 +99,10 @@ interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
     /** 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.
+     * MCP behavior hints so clients can flag token-spending write tools in their
+     * approval UI. `readOnlyHint` is mandatory; write tools also set `destructiveHint`.
      */
-    annotations?: ToolAnnotations;
+    annotations: RequiredToolAnnotations;
     /** Returns the data payload to be JSON-stringified in the tool response. */
     handler: (args: z.infer<z.ZodObject<S>>, ctx: HandlerContext) => Promise<unknown>;
 }
@@ -94,7 +117,7 @@ interface AnyTool {
     title: string;
     description: string;
     inputSchema: z.ZodRawShape;
-    annotations?: ToolAnnotations;
+    annotations: RequiredToolAnnotations;
     handler: (args: Record<string, unknown>, ctx: HandlerContext) => Promise<unknown>;
 }
 
@@ -134,8 +157,9 @@ declare const allTools: ReadonlyArray<AnyTool>;
  * 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)
+ *   datadive-backend/src/microservices/token/quota-exceeded.error.ts (QUOTA_EXCEEDED body)
  */
-type ApiErrorKind = "auth" | "payment" | "forbidden" | "not_found" | "bad_request" | "rate_limit" | "server" | "network" | "http";
+type ApiErrorKind = "auth" | "payment" | "quota" | "forbidden" | "not_found" | "bad_request" | "rate_limit" | "server" | "network" | "http";
 declare class ApiError extends Error {
     readonly kind: ApiErrorKind;
     readonly status: number;