@aipermission/mcp 0.2.53 → 0.2.55

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,7 +86,7 @@ does this automatically.
 ## Tools
 
 `AIPERMISSION_HTTP_TIMEOUT_MS` sets the gateway request deadline (default:
-60000 milliseconds; maximum: 600000). The value must be a positive base-10
+95000 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
@@ -100,10 +100,12 @@ 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
@@ -226,8 +228,11 @@ disclose secrets. Never automatically retry `submission_unknown`.
 
 Connector responses can include `approval_pending` or `running`. Poll
 `get_connector_action_request(request_id)` until the request reaches a terminal
-status. `outcome_unknown` is terminal and means the gateway could not prove the
-remote outcome after interruption; inspect target state or ask the operator
+status. Failed action calls carry the MCP `isError` flag; reading a recorded
+failed request is a successful read and does not. A `stopped` call response is a
+gateway control result, not a recorded request. `outcome_unknown` is terminal
+and means the gateway could not prove the remote outcome after interruption;
+inspect target state or ask the operator
 before retrying. Gateway API errors with that status retain their request id,
 assistant hint, and bounded retry delay in the MCP error envelope. MCP tool
 responses never include file contents, gateway

package/dist/config.js

@@ -1,4 +1,4 @@
-const defaultHTTPTimeoutMs = 60_000;
+const defaultHTTPTimeoutMs = 95_000;
 const maxHTTPTimeoutMs = 10 * 60_000;
 
 export function parseHTTPTimeout(value) {

package/dist/generated-connector-contract.js

@@ -0,0 +1,27 @@
+// Code generated by backend/cmd/openapi. DO NOT EDIT.
+
+export const connectorActionStatuses = Object.freeze([
+  "completed",
+  "failed",
+  "canceled",
+  "running",
+  "approval_pending",
+  "blocked",
+  "stale",
+  "declined",
+  "error",
+  "outcome_unknown",
+]);
+
+export const connectorRetryClasses = Object.freeze(["read_only", "idempotent", "conditional", "non_idempotent"]);
+
+export const executionRules = Object.freeze(["always_run", "approval_required", "blocked"]);
+
+export const connectorActionResponseRequiredFields = Object.freeze([
+  "status",
+  "request_id",
+  "target_ref",
+  "connector_kind",
+  "action_name",
+  "retry_policy",
+]);

package/dist/init.js

@@ -609,29 +609,40 @@ function removeTOMLServer(source, name) {
 }
 
 function scanTOMLHeader(line, state) {
-  if (state.multiline) {
-    if (hasMultilineDelimiter(line, state.multiline)) state.multiline = "";
-    return null;
-  }
   const trimmed = line.trimStart();
-  if (trimmed.startsWith("[")) {
+  if (!state.multiline && trimmed.startsWith("[")) {
     try {
       return findMarkerPath(parseTOML(`${line}\n__aipermission_header_marker = true\n`));
     } catch {
-      return null;
+      // A string can start with a bracket; scan it before the next line.
     }
   }
-  for (const delimiter of ['"""', "'''"]) {
-    if (!hasMultilineDelimiter(line, delimiter)) continue;
-    if ((line.split(delimiter).length - 1) % 2 === 1) state.multiline = delimiter;
-    break;
-  }
+  scanTOMLStrings(line, state);
   return null;
 }
 
-function hasMultilineDelimiter(line, delimiter) {
-  const comment = line.indexOf("#");
-  return (comment < 0 ? line : line.slice(0, comment)).includes(delimiter);
+function scanTOMLStrings(line, state) {
+  let quote = state.multiline;
+  for (let index = 0; index < line.length; index += 1) {
+    const character = line[index];
+    if (!quote && character === "#") break;
+    if (quote.startsWith('"') && character === "\\") {
+      index += 1;
+      continue;
+    }
+    if (quote) {
+      if (line.startsWith(quote, index)) {
+        index += quote.length - 1;
+        quote = "";
+      }
+      continue;
+    }
+    if (character !== '"' && character !== "'") continue;
+    const triple = character.repeat(3);
+    quote = line.startsWith(triple, index) ? triple : character;
+    index += quote.length - 1;
+  }
+  state.multiline = quote.length === 3 ? quote : "";
 }
 
 function findMarkerPath(value, pathParts = []) {

package/dist/response-contracts.js

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { connectorActionStatuses, connectorRetryClasses } from "./generated-connector-contract.js";
+
+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.enum([...connectorRetryClasses]),
+    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 connectorActionRequestSchema = z
+  .object({
+    status: z.enum([...connectorActionStatuses]),
+    request_id: positiveID,
+    target_ref: z.string(),
+    target_name: z.string().optional(),
+    connector_kind: z.string(),
+    profile_label: z.string().optional(),
+    action_name: z.string(),
+    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,
+    retry_after_seconds: nonNegativeInteger.max(3600).optional(),
+    assistant_hint: z.string().optional(),
+    output_withheld: z.boolean().optional(),
+    replayed: z.boolean().optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.output_withheld) {
+      if (value.input !== undefined || value.output !== undefined || value.display_text !== undefined || value.error !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "withheld action output must not contain request or result content" });
+      }
+    } else if (!value.target_ref || !value.connector_kind || !value.action_name) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "action response identity is required" });
+    }
+  });
+const connectorActionStoppedSchema = z.object({ status: z.literal("stopped"), error: z.string().min(1) }).strict();
+const connectorActionCallSchema = z.union([connectorActionRequestSchema, connectorActionStoppedSchema]);
+
+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,
+  connectorActionCall: connectorActionCallSchema,
+  connectorActionRequest: connectorActionRequestSchema,
+  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,45 @@ export function errorResult(error) {
   };
 }
 
-export async function jsonToolResult(callback) {
+export async function jsonToolResult(callback, project, mutationContext = null, isFailure = () => false) {
+  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 {
+    const projected = project(value);
+    const result = textResult(projected);
+    return isFailure(projected) ? { ...result, isError: true } : result;
+  } catch (error) {
+    return errorResult(mutationContext ? projectionOutcomeUnknown(error, mutationContext) : error);
+  }
+}
+
+export function jsonActionToolResult(callback, project, mutationContext) {
+  return jsonToolResult(
+    callback,
+    project,
+    mutationContext,
+    (value) => !["completed", "approval_pending", "running"].includes(value.status),
+  );
+}
+
+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

@@ -16,7 +16,9 @@ import { gatewayAPIError } from "./api-error.js";
 import { parseHTTPTimeout } from "./config.js";
 import { idempotencyKeySchema } from "./idempotency-key.js";
 import { normalizeLocalAPIURL } from "./local-url.js";
-import { jsonToolResult } from "./results.js";
+import { projectGatewaySuccess, responseContracts } from "./response-contracts.js";
+import { jsonActionToolResult, 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 = "";
@@ -41,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),
+    );
   },
 );
 
@@ -52,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),
+    );
   },
 );
 
@@ -66,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),
+    );
   },
 );
 
@@ -84,15 +98,23 @@ server.tool(
     reason: z.string().optional().describe("Why this connector action is needed."),
     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 jsonActionToolResult(
+      () =>
+        apiPost(
+          "/api/mcp/connector-actions/call",
+          {
+            target_ref,
+            action_name,
+            input: input || {},
+            reason: reason || "",
+            idempotency_key,
+          },
+          { signal },
+        ),
+      (value) => projectGatewaySuccess(responseContracts.connectorActionCall, value),
+      { idempotencyKey: idempotency_key },
     );
   },
 );
@@ -103,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.connectorActionRequest, value),
+    );
   },
 );
 
@@ -112,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),
+    );
   },
 );
 
@@ -126,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 jsonActionToolResult(
+      () =>
+        apiPost(
+          "/api/mcp/vault-actions/call",
+          {
+            project_ref,
+            action_name,
+            input,
+            reason,
+            idempotency_key,
+          },
+          { signal },
+        ),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      { idempotencyKey: idempotency_key },
     );
   },
 );
@@ -143,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),
+    );
   },
 );
 
@@ -152,18 +194,28 @@ 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`, {}, { requestID: request_id }));
+  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, context = {}) {
@@ -199,9 +251,20 @@ async function apiRequest(path, options, idempotencyKey, context = {}) {
   }
   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);
@@ -212,9 +275,12 @@ async function apiRequest(path, options, idempotencyKey, context = {}) {
     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 });
@@ -233,6 +299,7 @@ async function apiRequest(path, options, idempotencyKey, context = {}) {
     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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.53",
+  "version": "0.2.55",
   "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",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "smol-toml": "1.8.0",
-    "yaml": "2.9.0",
+    "yaml": "2.9.1",
     "zod": "3.25.76"
   },
   "devDependencies": {

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.53",
+  "description": "Local-only MCP bridge for the AIPermission gateway.",
+  "version": "0.2.55",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.53",
+      "version": "0.2.55",
       "transport": {
         "type": "stdio"
       }