@aipermission/mcp 0.2.53 → 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
@@ -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

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

@@ -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 { 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 = "";
@@ -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 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 },
     );
   },
 );
@@ -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.connectorAction, 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 jsonToolResult(
+      () =>
+        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.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",

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.54",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.53",
+      "version": "0.2.54",
       "transport": {
         "type": "stdio"
       }