askell-mcp 0.1.2 → 0.3.0

package/src/tools/call.ts

@@ -1,6 +1,7 @@
 import {
   acceptedContent,
   inputRequired,
+  inputResponse,
   type CallToolResult,
   type InputRequiredResult,
   type McpServer,
@@ -9,35 +10,59 @@ import * as z from 'zod';
 
 import { AskellClient, type AskellRequest } from '../client/askell-client.ts';
 import { normalizeApiPath } from '../client/paths.ts';
-import { isMutatingMethod } from '../client/response-formatter.ts';
 import type { AppConfig } from '../config.ts';
 import { operationRegistry } from '../openapi/registry.ts';
+import {
+  clientSupportsFormElicitation,
+  decideMutationGate,
+  readClientCapabilities,
+} from './mutation-gate.ts';
 
 const confirmationSchema = z.object({
   confirm: z.boolean().meta({ title: 'Confirm mutating Askell API request' }),
 });
 
-const callInputSchema = z.object({
-  method: z
-    .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])
-    .describe('HTTP method'),
+const sharedCallFields = {
   path: z
     .string()
     .describe('API path relative to apiBaseUrl, e.g. /v2/subscription-contracts/'),
   query: z
-    .record(z.string(), z.unknown())
+    .record(z.string(), z.json())
     .optional()
     .describe('Query string parameters'),
-  body: z.unknown().optional().describe('JSON request body'),
+  body: z.json().optional().describe('JSON request body'),
   apiKeyKind: z
     .enum(['secret', 'public'])
     .default('secret')
     .describe('Which configured API key to use'),
+};
+
+const callInputSchema = z.object({
+  method: z.enum(['GET', 'HEAD']).describe('HTTP method (read-only)'),
+  ...sharedCallFields,
 });
 
-function buildApprovalMessage(input: z.infer<typeof callInputSchema>): string {
+const mutateInputSchema = z.object({
+  method: z
+    .enum(['POST', 'PUT', 'PATCH', 'DELETE'])
+    .describe('HTTP method (mutating)'),
+  ...sharedCallFields,
+});
+
+type CallInput = z.infer<typeof callInputSchema>;
+type MutateInput = z.infer<typeof mutateInputSchema>;
+
+type ToolCtx = {
+  mcpReq: {
+    signal: AbortSignal;
+    envelope?: unknown;
+    inputResponses?: Record<string, unknown>;
+  };
+};
+
+function buildApprovalMessage(input: MutateInput): string {
   const lines = [
-    `Approve this Askell API request?`,
+    'Approve this Askell API request?',
     '',
     `${input.method} ${input.path}`,
     `apiKeyKind: ${input.apiKeyKind}`,
@@ -54,7 +79,89 @@ function buildApprovalMessage(input: z.infer<typeof callInputSchema>): string {
   return lines.join('\n');
 }
 
-export function registerCallTool(
+async function executeAskellRequest(
+  client: AskellClient,
+  input: CallInput | MutateInput,
+  signal: AbortSignal,
+): Promise<CallToolResult> {
+  const path = normalizeApiPath(input.path);
+  const known = operationRegistry
+    .find({
+      method: input.method,
+      pathPrefix: path,
+    })
+    .find((operation) => operation.path === path);
+
+  const request: AskellRequest = {
+    method: input.method,
+    path,
+    query: input.query,
+    body: input.body,
+    apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
+    signal,
+  };
+
+  try {
+    const response = await client.request(request);
+    return {
+      content: [{ type: 'text', text: response.text }],
+      isError: !response.ok,
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : 'Unknown Askell API error';
+    return {
+      content: [{ type: 'text', text: message }],
+      isError: true,
+    };
+  }
+}
+
+function mutationConfirmation(
+  config: AppConfig,
+  input: MutateInput,
+  ctx: ToolCtx,
+): CallToolResult | InputRequiredResult | undefined {
+  const declined = inputResponse(ctx.mcpReq.inputResponses, 'confirm');
+  if (
+    declined.kind === 'elicit' &&
+    (declined.action === 'decline' || declined.action === 'cancel')
+  ) {
+    return {
+      content: [{ type: 'text', text: 'Mutation cancelled by operator.' }],
+      isError: true,
+    };
+  }
+
+  const confirmed = acceptedContent(
+    ctx.mcpReq.inputResponses,
+    'confirm',
+    confirmationSchema,
+  );
+
+  const decision = decideMutationGate({
+    gate: config.mutationGate,
+    alreadyConfirmed: confirmed?.confirm === true,
+    supportsFormElicitation: clientSupportsFormElicitation(
+      readClientCapabilities(ctx.mcpReq.envelope),
+    ),
+  });
+
+  if (decision.action === 'execute') {
+    return undefined;
+  }
+
+  return inputRequired({
+    inputRequests: {
+      confirm: inputRequired.elicit({
+        message: buildApprovalMessage(input),
+        requestedSchema: confirmationSchema,
+      }),
+    },
+  });
+}
+
+export function registerCallTools(
   server: McpServer,
   client: AskellClient,
   config: AppConfig,
@@ -62,10 +169,29 @@ export function registerCallTool(
   server.registerTool(
     'askell_call',
     {
-      title: 'Call Askell API',
+      title: 'Call Askell API (read)',
       description:
-        'Execute any Askell API endpoint (v1 or v2). Mutating requests require operator approval when requireMutationApproval is enabled. Use askell_list_operations and askell_describe_operation first to discover paths and parameters.',
+        'Read-only Askell API call (GET, HEAD) for any v1/v2 path. For POST/PUT/PATCH/DELETE use askell_mutate. Discover paths with askell_list_operations and askell_describe_operation first.',
       inputSchema: callInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, ctx): Promise<CallToolResult> => {
+      return executeAskellRequest(client, input, ctx.mcpReq.signal);
+    },
+  );
+
+  server.registerTool(
+    'askell_mutate',
+    {
+      title: 'Mutate Askell API',
+      description:
+        'Mutating Askell API call (POST, PUT, PATCH, DELETE). Clients that declared form elicitation get a confirmation form; others rely on the client tool-approval UI. Use askell_call for GET. Discover paths with askell_list_operations and askell_describe_operation first.',
+      inputSchema: mutateInputSchema,
       annotations: {
         readOnlyHint: false,
         destructiveHint: true,
@@ -74,56 +200,11 @@ export function registerCallTool(
       },
     },
     async (input, ctx): Promise<CallToolResult | InputRequiredResult> => {
-      const mutating = isMutatingMethod(input.method);
-
-      if (config.requireMutationApproval && mutating) {
-        const confirmed = acceptedContent(
-          ctx.mcpReq.inputResponses,
-          'confirm',
-          confirmationSchema,
-        );
-
-        if (confirmed?.confirm !== true) {
-          return inputRequired({
-            inputRequests: {
-              confirm: inputRequired.elicit({
-                message: buildApprovalMessage(input),
-                requestedSchema: confirmationSchema,
-              }),
-            },
-          });
-        }
-      }
-
-      const path = normalizeApiPath(input.path);
-      const known = operationRegistry.find({
-        method: input.method,
-        pathPrefix: path,
-      }).find((operation) => operation.path === path);
-
-      const request: AskellRequest = {
-        method: input.method,
-        path,
-        query: input.query,
-        body: input.body,
-        apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
-        signal: ctx.mcpReq.signal,
-      };
-
-      try {
-        const response = await client.request(request);
-        return {
-          content: [{ type: 'text', text: response.text }],
-          isError: !response.ok,
-        };
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'Unknown Askell API error';
-        return {
-          content: [{ type: 'text', text: message }],
-          isError: true,
-        };
+      const gated = mutationConfirmation(config, input, ctx);
+      if (gated) {
+        return gated;
       }
+      return executeAskellRequest(client, input, ctx.mcpReq.signal);
     },
   );
 }

package/src/tools/discovery.ts

@@ -77,11 +77,11 @@ const openApiParameterSchema = z.object({
   in: z.enum(['query', 'path', 'header', 'cookie']).optional(),
   required: z.boolean().optional(),
   description: z.string().optional(),
-  schema: z.unknown().optional(),
+  schema: z.json().optional(),
   $ref: z.string().optional(),
 });
 
-const operationDetailSchema = z.object({
+export const operationDetailSchema = z.object({
   id: z.string(),
   apiVersion: apiVersionSchema,
   method: httpMethodSchema,
@@ -95,7 +95,7 @@ const operationDetailSchema = z.object({
       required: z.boolean().optional(),
       description: z.string().optional(),
       contentTypes: z.array(z.string()),
-      schema: z.unknown().optional(),
+      schema: z.json().optional(),
     })
     .optional(),
   apiKeyKind: apiKeyKindSchema,
@@ -171,9 +171,13 @@ export function registerDiscoveryTools(server: McpServer): void {
         };
       }
 
+      // Strip OpenAPI extras (style/explode/…) so structuredContent matches
+      // the output JSON Schema (additionalProperties: false).
+      const payload = operationDetailSchema.parse(operation);
+
       return {
-        content: [{ type: 'text', text: JSON.stringify(operation, null, 2) }],
-        structuredContent: operation,
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
       };
     },
   );

package/src/tools/mutation-gate.ts

@@ -0,0 +1,74 @@
+import {
+  CLIENT_CAPABILITIES_META_KEY,
+  type ClientCapabilities,
+} from '@modelcontextprotocol/server';
+
+import type { MutationGate } from '../config.ts';
+
+export type MutationGateDecision = { action: 'execute' } | { action: 'elicit' };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Per-request client capabilities (protocol 2026-07-28).
+ *
+ * Source of truth is `ctx.mcpReq.envelope[CLIENT_CAPABILITIES_META_KEY]` —
+ * reserved `io.modelcontextprotocol/*` keys are lifted out of `_meta` before
+ * the handler runs. Do not use deprecated `Server.getClientCapabilities()`:
+ * on 2026 stdio (`serveStdio` factory) it is always undefined (no `initialize`).
+ *
+ * 2025-era clients do not send this envelope; `undefined` here means "this
+ * request did not declare elicitation", so `auto` falls through to the
+ * client's own tool-allow UI.
+ *
+ * @see https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md
+ */
+export function readClientCapabilities(
+  envelope: unknown,
+): ClientCapabilities | undefined {
+  if (!isRecord(envelope)) {
+    return undefined;
+  }
+  const value = envelope[CLIENT_CAPABILITIES_META_KEY];
+  return isRecord(value) ? (value as ClientCapabilities) : undefined;
+}
+
+/** Form-mode elicitation: `elicitation: {}` (pre-mode) or `elicitation.form`. URL-only is not form. */
+export function clientSupportsFormElicitation(
+  capabilities: ClientCapabilities | undefined,
+): boolean {
+  const elicitation = capabilities?.elicitation;
+  if (elicitation == null) {
+    return false;
+  }
+  if (elicitation.form != null) {
+    return true;
+  }
+  const keys = Object.keys(elicitation);
+  if (elicitation.url != null && keys.every((key) => key === 'url')) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * auto  — elicit only if this request's envelope declared form elicitation.
+ * elicit — always return inputRequired; the SDK era-gates the wire
+ *          (2026 envelope / 2025 initialize via the legacy shim).
+ * off   — never elicit.
+ */
+export function decideMutationGate(options: {
+  gate: MutationGate;
+  alreadyConfirmed: boolean;
+  supportsFormElicitation: boolean;
+}): MutationGateDecision {
+  if (options.alreadyConfirmed || options.gate === 'off') {
+    return { action: 'execute' };
+  }
+  if (options.gate === 'elicit' || options.supportsFormElicitation) {
+    return { action: 'elicit' };
+  }
+  return { action: 'execute' };
+}