@aipermission/mcp 0.2.52 → 0.2.54

package/README.md

@@ -1,6 +1,6 @@
 # @aipermission/mcp
 
-Local-first MCP bridge for the AIPermission connector gateway.
+Local-only MCP bridge for the AIPermission connector gateway.
 
 AIPermission lets AI coding assistants use scoped connector actions through a
 local gateway without receiving SSH private keys, database passwords, API
@@ -86,8 +86,10 @@ does this automatically.
 ## Tools
 
 `AIPERMISSION_HTTP_TIMEOUT_MS` sets the gateway request deadline (default:
-60000 milliseconds). It covers both response headers and the complete response
-body, including streamed bodies. A timeout does not prove that a submitted
+60000 milliseconds; maximum: 600000). The value must be a positive base-10
+integer; invalid configuration stops the bridge instead of silently changing
+the deadline. It covers both response headers and the complete response body,
+including streamed bodies. A timeout does not prove that a submitted
 operation failed; do not retry mutations with a new idempotency key blindly.
 If a POST response is lost or incomplete, the bridge returns
 `status: outcome_unknown` and `code: gateway_transport_outcome_unknown`.
@@ -98,10 +100,18 @@ Local input-validation failures do not imply that execution occurred.
 Malformed or incomplete JSON responses are not treated as success. Invalid
 local headers are rejected before dispatch without echoing the API token;
 transport errors never echo raw response fragments or header values.
-Connector-action capacity errors retain HTTP `429`, the gateway error code,
-and `Retry-After`. Respect that delay; immediate retry loops cannot bypass the
-gateway's per-workspace/token rate, persisted-running concurrency, input, or
-atomic projected-storage limits.
+Connector-action capacity errors cross the HTTP transport as MCP error results:
+the gateway error code is retained and `Retry-After` becomes bounded
+`retry_after_seconds` metadata. The numeric HTTP `429` itself is not part of the
+MCP tool result. Respect the returned delay; immediate retry loops cannot bypass
+the gateway's per-workspace/token rate, persisted-running concurrency, input,
+or atomic projected-storage limits.
+
+The normal `npm test` command requires a full Git clone so its test-manifest
+ratchet can compare against trusted history. A GitHub source archive has no
+history; use `npm run test:source-archive` there to run the complete current
+behavior suite and current-manifest checks. That archive command intentionally
+does not claim to verify the historical anti-regression ratchet.
 
 - `list_connector_targets`
 - `get_connector_help`

package/dist/api-error.js

@@ -1,13 +1,20 @@
 const safeResultStatuses = new Set(["failed", "blocked", "stale", "declined", "canceled", "error", "outcome_unknown"]);
 
-export function gatewayAPIError(data, httpStatus) {
+export function gatewayAPIError(data, httpStatus, retryAfterHeader = null) {
   const error = new Error(data?.error || `AIPermission API request failed with ${httpStatus}`);
   if (typeof data?.code === "string" && data.code.length <= 128) error.code = data.code;
   if (safeResultStatuses.has(data?.status)) error.resultStatus = data.status;
   if (Number.isSafeInteger(data?.request_id) && data.request_id > 0) error.requestID = data.request_id;
   if (typeof data?.assistant_hint === "string" && data.assistant_hint.length <= 2048) error.assistantHint = data.assistant_hint;
-  if (Number.isSafeInteger(data?.retry_after_seconds) && data.retry_after_seconds >= 0 && data.retry_after_seconds <= 3600) {
-    error.retryAfterSeconds = data.retry_after_seconds;
-  }
+  const retryAfterSeconds = safeRetryAfterSeconds(data?.retry_after_seconds, retryAfterHeader);
+  if (retryAfterSeconds !== null) error.retryAfterSeconds = retryAfterSeconds;
   return error;
 }
+
+function safeRetryAfterSeconds(bodyValue, headerValue) {
+  if (Number.isSafeInteger(bodyValue) && bodyValue >= 0 && bodyValue <= 3600) return bodyValue;
+  const raw = typeof headerValue === "string" ? headerValue.trim() : "";
+  if (!/^\d{1,4}$/.test(raw)) return null;
+  const value = Number(raw);
+  return value <= 3600 ? value : null;
+}

package/dist/config.js

@@ -0,0 +1,15 @@
+const defaultHTTPTimeoutMs = 60_000;
+const maxHTTPTimeoutMs = 10 * 60_000;
+
+export function parseHTTPTimeout(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return defaultHTTPTimeoutMs;
+  if (!/^[1-9]\d*$/.test(raw)) {
+    throw new Error("AIPERMISSION_HTTP_TIMEOUT_MS must be a positive integer in milliseconds.");
+  }
+  const timeout = Number(raw);
+  if (!Number.isSafeInteger(timeout) || timeout > maxHTTPTimeoutMs) {
+    throw new Error(`AIPERMISSION_HTTP_TIMEOUT_MS must not exceed ${maxHTTPTimeoutMs} milliseconds.`);
+  }
+  return timeout;
+}

package/dist/idempotency-key.js

@@ -0,0 +1,8 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+
+export const idempotencyKeySchema = z
+  .string()
+  .min(1)
+  .refine((value) => Buffer.byteLength(value, "utf8") <= 128, "Idempotency key must not exceed 128 UTF-8 bytes.")
+  .describe("Caller-stable key used to prevent duplicate action requests.");

package/dist/response-contracts.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+
+const positiveID = z.number().int().positive();
+const nonNegativeInteger = z.number().int().nonnegative();
+const forbiddenMetadataField = /(?:^|_)(?:credential|password|passphrase|private_key|secret|token|api_key|access_key)(?:$|_)/;
+
+function normalizeMetadataKey(key) {
+  return key
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .toLowerCase();
+}
+
+function rejectSecretMetadataKeys(value, context) {
+  const pending = [value];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (Array.isArray(current)) {
+      pending.push(...current);
+      continue;
+    }
+    if (!current || typeof current !== "object") continue;
+    for (const [key, item] of Object.entries(current)) {
+      const normalized = normalizeMetadataKey(key);
+      if (forbiddenMetadataField.test(normalized)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "connector metadata contains a forbidden secret field" });
+        return;
+      }
+      pending.push(item);
+    }
+  }
+}
+
+const connectorMetadataSchema = z.record(z.unknown()).superRefine(rejectSecretMetadataKeys);
+
+const actionGrantSchema = z
+  .object({
+    name: z.string(),
+    execution_rule: z.string(),
+    expires_at: z.string().optional(),
+  })
+  .strict();
+
+const connectorTargetSchema = z
+  .object({
+    target_ref: z.string(),
+    project_id: positiveID,
+    project_name: z.string(),
+    project_slug: z.string(),
+    target_id: positiveID,
+    target_name: z.string(),
+    connector_kind: z.string(),
+    profile_id: positiveID,
+    profile_label: z.string(),
+    profile_kind: z.string(),
+    metadata: connectorMetadataSchema.optional(),
+    actions: z.array(actionGrantSchema),
+    hints: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const connectorHelpSchema = z
+  .object({
+    title: z.string(),
+    summary: z.string(),
+    usage: z.array(z.string()).optional(),
+    warnings: z.array(z.string()).optional(),
+    connector: z.string(),
+    connector_id: z.string(),
+  })
+  .strict();
+
+const fieldOptionSchema = z.object({ value: z.string(), label: z.string() }).strict();
+const fieldSchema = z
+  .object({
+    name: z.string(),
+    label: z.string(),
+    type: z.string(),
+    required: z.boolean().optional(),
+    preserve_whitespace: z.boolean().optional(),
+    secret: z.boolean().optional(),
+    description: z.string().optional(),
+    default: z.unknown().optional(),
+    options: z.array(fieldOptionSchema).optional(),
+  })
+  .strict();
+const inputSchema = z.object({ fields: z.array(fieldSchema) }).strict();
+const outputHintSchema = z
+  .object({
+    format: z.string().optional(),
+    sensitive_fields: z.array(z.string()).optional(),
+    temporary_capability_fields: z.array(z.string()).optional(),
+    max_rows: nonNegativeInteger.optional(),
+    max_bytes: nonNegativeInteger.optional(),
+  })
+  .strict();
+const retryPolicySchema = z
+  .object({
+    class: z.string(),
+    precondition_fields: z.array(z.string()).optional(),
+    guidance: z.string(),
+  })
+  .strict();
+const actionDefinitionSchema = z
+  .object({
+    name: z.string(),
+    label: z.string(),
+    description: z.string(),
+    category: z.string().optional(),
+    risk: z.string(),
+    input_schema: inputSchema,
+    sensitive_input_fields: z.array(z.string()).optional(),
+    output_hint: outputHintSchema.optional(),
+    retry_policy: retryPolicySchema,
+    max_input_bytes: positiveID,
+  })
+  .strict();
+
+const connectorActionsSchema = z.object({ items: z.array(actionDefinitionSchema) }).strict();
+
+const connectorActionResponseSchema = z
+  .object({
+    status: z.string(),
+    request_id: positiveID.optional(),
+    target_ref: z.string().optional(),
+    target_name: z.string().optional(),
+    connector_kind: z.string().optional(),
+    profile_label: z.string().optional(),
+    action_name: z.string().optional(),
+    input: z.record(z.unknown()).optional(),
+    // Connector-owned output is intentionally opaque. The gateway credential
+    // boundary redacts values; this schema owns only the shared MCP envelope.
+    output: z.unknown().optional(),
+    display_text: z.string().optional(),
+    error: z.string().optional(),
+    retry_policy: retryPolicySchema.optional(),
+    retry_after_seconds: nonNegativeInteger.optional(),
+    assistant_hint: z.string().optional(),
+    output_withheld: z.boolean().optional(),
+    replayed: z.boolean().optional(),
+  })
+  .strict();
+
+const vaultItemSchema = z
+  .object({
+    vault_ref: z.string(),
+    item_id: positiveID,
+    project_ref: z.string(),
+    source_project_id: positiveID,
+    name: z.string(),
+    secret_type: z.string(),
+    status: z.string(),
+    expires_at: z.string().optional(),
+    value_version: positiveID,
+    metadata_revision: positiveID,
+  })
+  .strict();
+const vaultItemsSchema = z
+  .object({
+    items: z.array(vaultItemSchema),
+    count: nonNegativeInteger,
+    truncated: z.boolean(),
+    secret_values_returned: z.literal(false),
+  })
+  .strict();
+
+const usageNoteSchema = z.object({ location: z.string(), notes: z.string().optional() }).strict();
+const vaultGenerateInputSchema = z
+  .object({
+    name: z.string(),
+    secret_type: z.string().optional(),
+    generator_kind: z.string(),
+    provider: z.string().optional(),
+    environment: z.string().optional(),
+    description: z.string().optional(),
+    expires_at: z.string().optional(),
+    expiry_warning_days: nonNegativeInteger.optional(),
+    tags: z.array(z.string()).optional(),
+    usage_notes: z.array(usageNoteSchema).optional(),
+    shared_project_ids: z.array(positiveID).optional(),
+  })
+  .strict();
+const vaultSessionItemSchema = z
+  .object({
+    item_id: positiveID,
+    source_project_id: positiveID,
+    replace_existing: z.boolean().optional(),
+  })
+  .strict();
+const vaultSessionInputSchema = z
+  .object({
+    target_ref: z.string(),
+    items: z.array(vaultSessionItemSchema),
+  })
+  .strict();
+
+const generatedVaultItemSchema = z
+  .object({
+    vault_ref: z.string(),
+    item_id: positiveID,
+    project_id: positiveID,
+    name: z.string(),
+    secret_type: z.string(),
+    status: z.string(),
+    expires_at: z.string(),
+    value_version: positiveID,
+    metadata_revision: positiveID,
+  })
+  .strict();
+const generatedVaultOutputSchema = z
+  .object({
+    item: generatedVaultItemSchema,
+    secret_returned: z.literal(false),
+  })
+  .strict();
+const vaultSessionOutputSchema = z
+  .object({
+    session_id: positiveID,
+    session_generation: positiveID,
+    runtime_id: positiveID,
+    status: z.string(),
+    environment_names: z.array(z.string()),
+    expires_at: z.string(),
+  })
+  .strict();
+
+const vaultActionResponseSchema = z
+  .object({
+    status: z.string(),
+    request_id: positiveID.optional(),
+    project_ref: z.string().optional(),
+    action_name: z.string().optional(),
+    input: z.union([vaultGenerateInputSchema, vaultSessionInputSchema]).optional(),
+    reason: z.string().optional(),
+    created_at: z.string().optional(),
+    expires_at: z.string().optional(),
+    secret_values_returned: z.literal(false).optional(),
+    output: z.union([generatedVaultOutputSchema, vaultSessionOutputSchema]).optional(),
+    output_withheld: z.boolean().optional(),
+    retry_after_seconds: nonNegativeInteger.optional(),
+    assistant_hint: z.string().optional(),
+    error: z.string().optional(),
+  })
+  .strict();
+
+export const responseContracts = Object.freeze({
+  connectorTargets: z.array(connectorTargetSchema),
+  connectorHelp: connectorHelpSchema,
+  connectorActions: connectorActionsSchema,
+  connectorAction: connectorActionResponseSchema,
+  vaultItems: vaultItemsSchema,
+  vaultAction: vaultActionResponseSchema,
+});
+
+export function projectGatewaySuccess(schema, value) {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    const error = new Error("Gateway success response failed MCP contract validation.");
+    error.code = "gateway_response_contract_invalid";
+    throw error;
+  }
+  return result.data;
+}

package/dist/results.js

@@ -45,10 +45,34 @@ export function errorResult(error) {
   };
 }
 
-export async function jsonToolResult(callback) {
+export async function jsonToolResult(callback, project, mutationContext = null) {
+  if (typeof project !== "function") {
+    return errorResult(new Error("MCP tool result projector is required."));
+  }
+  let value;
   try {
-    return textResult(await callback());
+    value = await callback();
   } catch (error) {
     return errorResult(error);
   }
+  try {
+    return textResult(project(value));
+  } catch (error) {
+    return errorResult(mutationContext ? projectionOutcomeUnknown(error, mutationContext) : error);
+  }
+}
+
+function projectionOutcomeUnknown(cause, context) {
+  const error = new Error(
+    "The gateway accepted the mutation, but its response failed MCP contract validation. The operation may have completed.",
+    { cause },
+  );
+  error.resultStatus = "outcome_unknown";
+  error.code = "gateway_response_contract_outcome_unknown";
+  if (typeof context.idempotencyKey === "string") error.idempotencyKey = context.idempotencyKey;
+  if (Number.isSafeInteger(context.requestID) && context.requestID > 0) error.requestID = context.requestID;
+  error.assistantHint = context.idempotencyKey
+    ? "Reconcile the original request using the same idempotency key and unchanged input. Never retry with a new key blindly."
+    : "Inspect the original request status before repeating the operation.";
+  return error;
 }

package/dist/server.js

@@ -13,8 +13,12 @@ import { z } from "zod";
 import { callVaultActionSchema, listVaultItemsSchema, vaultActionRequestSchema } from "./vault-tools.js";
 import { MCP_SERVER_INSTRUCTIONS } from "./instructions.js";
 import { gatewayAPIError } from "./api-error.js";
+import { parseHTTPTimeout } from "./config.js";
+import { idempotencyKeySchema } from "./idempotency-key.js";
 import { normalizeLocalAPIURL } from "./local-url.js";
+import { projectGatewaySuccess, responseContracts } from "./response-contracts.js";
 import { jsonToolResult } from "./results.js";
+import { externalActionAnnotations, localMutationAnnotations, localReadAnnotations } from "./tool-annotations.js";
 
 const packageMetadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 let apiUrl = "";
@@ -25,7 +29,7 @@ try {
   apiURLConfigurationError = new Error("Invalid local gateway URL configuration; update AIPERMISSION_API_URL.", { cause: error });
 }
 const apiToken = process.env.AIPERMISSION_API_TOKEN || "";
-const apiTimeoutMs = Number.parseInt(process.env.AIPERMISSION_HTTP_TIMEOUT_MS || "60000", 10);
+const apiTimeoutMs = parseHTTPTimeout(process.env.AIPERMISSION_HTTP_TIMEOUT_MS);
 
 const server = new McpServer(
   {
@@ -39,8 +43,12 @@ server.tool(
   "list_connector_targets",
   "List connector targets this AIPermission token can access. Credentials and secrets are never returned.",
   {},
-  async () => {
-    return jsonToolResult(() => apiGet("/api/mcp/connector-targets"));
+  localReadAnnotations,
+  async (_args, { signal }) => {
+    return jsonToolResult(
+      () => apiGet("/api/mcp/connector-targets", { signal }),
+      (value) => projectGatewaySuccess(responseContracts.connectorTargets, value),
+    );
   },
 );
 
@@ -50,11 +58,15 @@ server.tool(
   {
     target_ref: z.string().min(1).describe("Target ref from list_connector_targets in connector:target_id:profile_id format."),
   },
-  async ({ target_ref }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams({ target_ref });
-      return apiGet(`/api/mcp/connector-help?${params.toString()}`);
-    });
+  localReadAnnotations,
+  async ({ target_ref }, { signal }) => {
+    return jsonToolResult(
+      () => {
+        const params = new URLSearchParams({ target_ref });
+        return apiGet(`/api/mcp/connector-help?${params.toString()}`, { signal });
+      },
+      (value) => projectGatewaySuccess(responseContracts.connectorHelp, value),
+    );
   },
 );
 
@@ -64,11 +76,15 @@ server.tool(
   {
     target_ref: z.string().min(1).describe("Target ref from list_connector_targets in connector:target_id:profile_id format."),
   },
-  async ({ target_ref }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams({ target_ref });
-      return apiGet(`/api/mcp/connector-actions?${params.toString()}`);
-    });
+  localReadAnnotations,
+  async ({ target_ref }, { signal }) => {
+    return jsonToolResult(
+      () => {
+        const params = new URLSearchParams({ target_ref });
+        return apiGet(`/api/mcp/connector-actions?${params.toString()}`, { signal });
+      },
+      (value) => projectGatewaySuccess(responseContracts.connectorActions, value),
+    );
   },
 );
 
@@ -80,21 +96,25 @@ server.tool(
     action_name: z.string().min(1).describe("Action name from get_connector_actions."),
     input: z.record(z.unknown()).optional().describe("Connector-specific action input."),
     reason: z.string().optional().describe("Why this connector action is needed."),
-    idempotency_key: z
-      .string()
-      .min(1)
-      .max(128)
-      .describe("Caller-stable key that makes retries return the original request without running twice."),
+    idempotency_key: idempotencyKeySchema,
   },
-  async ({ target_ref, action_name, input, reason, idempotency_key }) => {
-    return jsonToolResult(() =>
-      apiPost("/api/mcp/connector-actions/call", {
-        target_ref,
-        action_name,
-        input: input || {},
-        reason: reason || "",
-        idempotency_key,
-      }),
+  externalActionAnnotations,
+  async ({ target_ref, action_name, input, reason, idempotency_key }, { signal }) => {
+    return jsonToolResult(
+      () =>
+        apiPost(
+          "/api/mcp/connector-actions/call",
+          {
+            target_ref,
+            action_name,
+            input: input || {},
+            reason: reason || "",
+            idempotency_key,
+          },
+          { signal },
+        ),
+      (value) => projectGatewaySuccess(responseContracts.connectorAction, value),
+      { idempotencyKey: idempotency_key },
     );
   },
 );
@@ -105,8 +125,12 @@ server.tool(
   {
     request_id: z.number().int().positive().describe("Request id returned by call_connector_action."),
   },
-  async ({ request_id }) => {
-    return jsonToolResult(() => apiGet(`/api/mcp/connector-action-requests/${request_id}`));
+  localReadAnnotations,
+  async ({ request_id }, { signal }) => {
+    return jsonToolResult(
+      () => apiGet(`/api/mcp/connector-action-requests/${request_id}`, { signal }),
+      (value) => projectGatewaySuccess(responseContracts.connectorAction, value),
+    );
   },
 );
 
@@ -114,13 +138,17 @@ server.tool(
   "list_vault_items",
   "List secret names and bounded non-secret Vault metadata for projects this token can read. Secret values are never returned.",
   listVaultItemsSchema,
-  async ({ project_ref }) => {
-    return jsonToolResult(() => {
-      const params = new URLSearchParams();
-      if (project_ref) params.set("project_ref", project_ref);
-      const query = params.toString();
-      return apiGet(`/api/mcp/vault-items${query ? `?${query}` : ""}`);
-    });
+  localReadAnnotations,
+  async ({ project_ref }, { signal }) => {
+    return jsonToolResult(
+      () => {
+        const params = new URLSearchParams();
+        if (project_ref) params.set("project_ref", project_ref);
+        const query = params.toString();
+        return apiGet(`/api/mcp/vault-items${query ? `?${query}` : ""}`, { signal });
+      },
+      (value) => projectGatewaySuccess(responseContracts.vaultItems, value),
+    );
   },
 );
 
@@ -128,15 +156,23 @@ server.tool(
   "call_vault_action",
   "Run a Vault action under the configured project capability. Prompt waits for local approval; Always executes immediately through the same tracked request path. generate_item input accepts name, secret_type, generator_kind, provider, environment, description, expires_at, expiry_warning_days, tags (string array), usage_notes (array of {location, notes}), and shared_project_ids (integer array). restart_session_with_environment input requires target_ref and items with item_id, source_project_id, and optional replace_existing. Never include raw secret values.",
   callVaultActionSchema,
-  async ({ project_ref, action_name, input, reason, idempotency_key }) => {
-    return jsonToolResult(() =>
-      apiPost("/api/mcp/vault-actions/call", {
-        project_ref,
-        action_name,
-        input,
-        reason,
-        idempotency_key,
-      }),
+  externalActionAnnotations,
+  async ({ project_ref, action_name, input, reason, idempotency_key }, { signal }) => {
+    return jsonToolResult(
+      () =>
+        apiPost(
+          "/api/mcp/vault-actions/call",
+          {
+            project_ref,
+            action_name,
+            input,
+            reason,
+            idempotency_key,
+          },
+          { signal },
+        ),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      { idempotencyKey: idempotency_key },
     );
   },
 );
@@ -145,8 +181,12 @@ server.tool(
   "get_vault_action_request",
   "Read one Vault action request after call_vault_action returns approval_pending. Responses never include secret values.",
   vaultActionRequestSchema,
-  async ({ request_id }) => {
-    return jsonToolResult(() => apiGet(`/api/mcp/vault-action-requests/${request_id}`));
+  localReadAnnotations,
+  async ({ request_id }, { signal }) => {
+    return jsonToolResult(
+      () => apiGet(`/api/mcp/vault-action-requests/${request_id}`, { signal }),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+    );
   },
 );
 
@@ -154,21 +194,31 @@ server.tool(
   "cancel_vault_action_request",
   "Cancel one approval_pending Vault action request owned by this token. Running or terminal requests cannot be canceled.",
   vaultActionRequestSchema,
-  async ({ request_id }) => {
-    return jsonToolResult(() => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}));
+  localMutationAnnotations,
+  async ({ request_id }, { signal }) => {
+    return jsonToolResult(
+      () => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}, { requestID: request_id, signal }),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      { requestID: request_id },
+    );
   },
 );
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
 
-async function apiGet(path) {
-  return apiRequest(path, {
-    method: "GET",
-  });
+async function apiGet(path, context = {}) {
+  return apiRequest(
+    path,
+    {
+      method: "GET",
+    },
+    undefined,
+    context,
+  );
 }
 
-async function apiPost(path, body) {
+async function apiPost(path, body, context = {}) {
   return apiRequest(
     path,
     {
@@ -179,10 +229,11 @@ async function apiPost(path, body) {
       body: JSON.stringify(body),
     },
     body?.idempotency_key,
+    context,
   );
 }
 
-async function apiRequest(path, options, idempotencyKey) {
+async function apiRequest(path, options, idempotencyKey, context = {}) {
   if (apiURLConfigurationError) {
     throw apiURLConfigurationError;
   }
@@ -198,24 +249,38 @@ async function apiRequest(path, options, idempotencyKey) {
   } catch {
     throw new Error("Invalid local gateway request configuration; check the API URL and token.");
   }
-  const timeout = Number.isFinite(apiTimeoutMs) && apiTimeoutMs > 0 ? apiTimeoutMs : 60000;
+  const timeout = apiTimeoutMs;
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeout);
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeout);
+  const cancelRequest = () => controller.abort();
+  context.signal?.addEventListener("abort", cancelRequest, { once: true });
   let bodyReceived = false;
+  let dispatchStarted = false;
   try {
+    if (context.signal?.aborted) {
+      throw new Error("MCP request was canceled.");
+    }
+    dispatchStarted = true;
     const response = await fetch(request, { signal: controller.signal });
     const text = await response.text();
     const data = response.status === 204 ? null : parseResponseBody(text);
     bodyReceived = true;
     if (!response.ok) {
-      throw gatewayAPIError(data, response.status);
+      throw gatewayAPIError(data, response.status, response.headers.get("Retry-After"));
     }
     return data;
   } catch (error) {
     let failure = bodyReceived ? error : new Error("Gateway response unavailable or invalid.", { cause: error });
-    if (controller.signal.aborted) {
+    if (timedOut) {
       failure = new Error(`AIPermission API request timed out after ${timeout}ms`, { cause: error });
+    } else if (context.signal?.aborted) {
+      failure = new Error("MCP request was canceled.", { cause: error });
     }
+    if (!dispatchStarted) throw failure;
     const definitelyNotDispatched = !bodyReceived && isDefinitePredispatchTransportError(error);
     if (definitelyNotDispatched) {
       throw new Error("AIPermission gateway connection failed before request dispatch.", { cause: error });
@@ -225,6 +290,7 @@ async function apiRequest(path, options, idempotencyKey) {
       uncertain.resultStatus = "outcome_unknown";
       uncertain.code = "gateway_transport_outcome_unknown";
       uncertain.idempotencyKey = idempotencyKey;
+      if (Number.isSafeInteger(context.requestID) && context.requestID > 0) uncertain.requestID = context.requestID;
       uncertain.assistantHint = idempotencyKey
         ? "The gateway response was lost; execution may have occurred. Reconcile the original request using the same idempotency key and unchanged input. Never retry with a new key blindly."
         : "The gateway response was lost; execution may have occurred. Inspect the original request status before repeating the operation.";
@@ -233,6 +299,7 @@ async function apiRequest(path, options, idempotencyKey) {
     throw failure;
   } finally {
     clearTimeout(timer);
+    context.signal?.removeEventListener("abort", cancelRequest);
   }
 }
 

package/dist/tool-annotations.js

@@ -0,0 +1,20 @@
+export const localReadAnnotations = Object.freeze({
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+});
+
+export const externalActionAnnotations = Object.freeze({
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true,
+});
+
+export const localMutationAnnotations = Object.freeze({
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false,
+});

package/dist/vault-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { idempotencyKeySchema } from "./idempotency-key.js";
 
 export const listVaultItemsSchema = {
   project_ref: z.string().min(1).optional().describe("Optional project id or slug. Omit to list every readable project."),
@@ -9,7 +10,7 @@ export const callVaultActionSchema = {
   action_name: z.enum(["generate_item", "restart_session_with_environment"]),
   input: z.record(z.unknown()).describe("Action input. Never include raw secret values."),
   reason: z.string().min(1).describe("Why this Vault action is needed."),
-  idempotency_key: z.string().min(1).max(128).describe("Caller-stable key used to prevent duplicate action requests."),
+  idempotency_key: idempotencyKeySchema,
 };
 
 export const vaultActionRequestSchema = {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.52",
+  "version": "0.2.54",
   "mcpName": "io.github.aipermission/aipermission-mcp",
-  "description": "Local-first MCP bridge for the aipermission gateway.",
+  "description": "Local-only MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",
   "type": "module",
   "homepage": "https://github.com/aipermission/aipermission/tree/main/packages/mcp#readme",
@@ -33,6 +33,7 @@
     "lint": "eslint src test scripts",
     "prepack": "npm run build",
     "test": "npm run build && node scripts/run-tests.js",
+    "test:source-archive": "npm run build && node scripts/run-tests.js --current-only",
     "test:windows-acl": "node scripts/run-windows-acl-tests.js",
     "start": "node dist/cli.js",
     "dev": "node src/cli.js"

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.aipermission/aipermission-mcp",
   "title": "AIPermission",
-  "description": "Local-first MCP bridge for the AIPermission gateway.",
-  "version": "0.2.52",
+  "description": "Local-only MCP bridge for the AIPermission gateway.",
+  "version": "0.2.54",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.52",
+      "version": "0.2.54",
       "transport": {
         "type": "stdio"
       }