askell-mcp 0.3.1 → 0.4.1

package/README.md

@@ -19,16 +19,27 @@ In the Askell dashboard, copy your **private (secret)** API key. Optionally also
 
 ### 2. Add to your MCP client
 
+Prefer **two server entries** if you have both production and sandbox keys. Tool names are the same on both; the client distinguishes them by the `mcp.json` key (`askell-prod` vs `askell-sandbox`). Set `ASKELL_ENV` — the server picks the host. Each instance's instructions include the environment it is talking to.
+
 **With Bun** (`bunx`):
 
 ```json
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
+      "command": "bunx",
+      "args": ["-y", "askell-mcp@latest"],
+      "env": {
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
+      }
+    },
+    "askell-sandbox": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp"],
+      "args": ["-y", "askell-mcp@latest"],
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
+        "ASKELL_ENV": "sandbox",
+        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key"
       }
     }
   }
@@ -40,10 +51,11 @@ In the Askell dashboard, copy your **private (secret)** API key. Optionally also
 ```json
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
       "command": "/absolute/path/to/askell-mcp-linux-x64",
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
       }
     }
   }
@@ -60,12 +72,18 @@ Restart the client after saving.
 | ---------------------------------- | -------- | ----------------------- | ----------------------------------------------- |
 | `ASKELL_PRIVATE_API_KEY`           | yes\*    | —                       | Secret API key (_or_ `ASKELL_SECRET_API_KEY`)   |
 | `ASKELL_PUBLIC_API_KEY`            | no       | —                       | Public key for a few checkout/payment endpoints |
-| `ASKELL_API_URL`                   | no       | `https://askell.is/api` | API base URL (_or_ `ASKELL_API_BASE_URL`)       |
+| `ASKELL_ENV`                       | no       | `production`            | `production` \| `sandbox` — selects the official API host |
+| `ASKELL_API_URL`                   | no       | —                       | Custom/local API base only (_or_ `ASKELL_API_BASE_URL`). Do not set together with `ASKELL_ENV` unless it matches |
 | `ASKELL_RESPONSE_MAX_BYTES`        | no       | `64000`                 | Max response size returned to the model         |
 | `ASKELL_MUTATION_GATE`             | no       | `auto`                  | `auto` / `elicit` / `off` — see below           |
 | `ASKELL_REQUIRE_MUTATION_APPROVAL` | no       | —                       | Deprecated alias: `true`→`elicit`, `false`→`off` |
 
-Askell has **no separate sandbox host** — production and test traffic use the same URL. Use the **Áskell Test Gateway** acquirer in your dashboard for safe payment testing. See [Askell getting started](https://docs.askell.is/en/getting_started/index.html).
+`ASKELL_ENV` picks a stable host (same v1/v2 surface):
+
+- **production** — `https://askell.is/api`
+- **sandbox** — `https://sandbox.askell.is/api` (isolated tenant; keys from that dashboard)
+
+Point a second MCP server entry at sandbox (`ASKELL_ENV=sandbox`) rather than switching env on one process. Keys do not work across hosts. **Áskell Test Gateway** is a payment acquirer (fake cards) on either host — not the same as the sandbox API. Official prose at [docs.askell.is](https://docs.askell.is/en/getting_started/index.html) still documents Test Gateway and may omit the sandbox host.
 
 `ASKELL_MUTATION_GATE`:
 

package/mcp.json.example

@@ -1,11 +1,21 @@
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp"],
+      "args": ["-y", "askell-mcp@latest"],
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key",
-        "ASKELL_PUBLIC_API_KEY": "your_public_api_key_optional"
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
+        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
+      }
+    },
+    "askell-sandbox": {
+      "command": "bunx",
+      "args": ["-y", "askell-mcp@latest"],
+      "env": {
+        "ASKELL_ENV": "sandbox",
+        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key",
+        "ASKELL_PUBLIC_API_KEY": "your_sandbox_public_api_key_optional"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -43,6 +43,8 @@
   },
   "scripts": {
     "dev": "bun run src/index.ts",
+    "dev:prod": "bun --no-env-file --env-file=.env run src/index.ts",
+    "dev:sandbox": "bun --no-env-file --env-file=.env.sandbox run src/index.ts",
     "start": "bun run bin/askell-mcp",
     "test": "bun test",
     "smoke": "bun run scripts/smoke-test.ts",

package/src/config.ts

@@ -1,11 +1,23 @@
 import * as z from 'zod';
 
+export const PRODUCTION_API_BASE_URL = 'https://askell.is/api';
+export const SANDBOX_API_BASE_URL = 'https://sandbox.askell.is/api';
+
+export const ASKELL_ENVS = ['production', 'sandbox'] as const;
+export type AskellOfficialEnv = (typeof ASKELL_ENVS)[number];
+export type AskellEnv = AskellOfficialEnv | 'custom';
+
+export const ASKELL_API_BASE_URLS = {
+  production: PRODUCTION_API_BASE_URL,
+  sandbox: SANDBOX_API_BASE_URL,
+} as const satisfies Record<AskellOfficialEnv, string>;
+
 export const MUTATION_GATES = ['auto', 'elicit', 'off'] as const;
 export type MutationGate = (typeof MUTATION_GATES)[number];
 
 const httpUrl = z
   .url({ protocol: /^https?$/ })
-  .describe('Askell API base URL (default production host)');
+  .describe('Custom Askell API base URL (local/fork override)');
 
 const mutationGateAliases = z
   .enum(['true', 'false', 'on', 'yes', 'no', '1', '0'])
@@ -26,8 +38,55 @@ export const MutationGateSchema = z
     'Mutation confirmation: auto (elicit if client declared it), elicit (require form), off (never)',
   );
 
-export const ConfigSchema = z.object({
-  apiBaseUrl: httpUrl.default('https://askell.is/api'),
+export const AskellEnvSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .transform((value) => (value === 'prod' ? 'production' : value))
+  .pipe(z.enum(ASKELL_ENVS));
+
+export function classifyAskellHost(apiBaseUrl: string): AskellEnv {
+  const normalized = normalizeBaseUrl(apiBaseUrl);
+  if (normalized === PRODUCTION_API_BASE_URL) {
+    return 'production';
+  }
+  if (normalized === SANDBOX_API_BASE_URL) {
+    return 'sandbox';
+  }
+  return 'custom';
+}
+
+export function resolveAskellTarget(input: {
+  askellEnv?: AskellOfficialEnv;
+  apiBaseUrl?: string;
+}): { askellEnv: AskellEnv; apiBaseUrl: string } {
+  if (input.apiBaseUrl) {
+    const apiBaseUrl = normalizeBaseUrl(input.apiBaseUrl);
+    const classified = classifyAskellHost(apiBaseUrl);
+
+    if (input.askellEnv !== undefined) {
+      if (classified === 'custom') {
+        throw new Error(
+          `ASKELL_ENV=${input.askellEnv} selects an official Askell host; omit ASKELL_ENV when ASKELL_API_URL is custom (${apiBaseUrl})`,
+        );
+      }
+      if (classified !== input.askellEnv) {
+        throw new Error(
+          `ASKELL_ENV=${input.askellEnv} does not match ASKELL_API_URL (${apiBaseUrl}). Omit ASKELL_API_URL and let ASKELL_ENV pick the host, or omit ASKELL_ENV.`,
+        );
+      }
+    }
+
+    return { askellEnv: classified, apiBaseUrl };
+  }
+
+  const askellEnv = input.askellEnv ?? 'production';
+  return { askellEnv, apiBaseUrl: ASKELL_API_BASE_URLS[askellEnv] };
+}
+
+const ConfigInputSchema = z.object({
+  askellEnv: AskellEnvSchema.optional(),
+  apiBaseUrl: httpUrl.optional(),
   secretApiKey: z.string().min(1).describe('Secret (private) API key'),
   publicApiKey: z
     .string()
@@ -43,23 +102,60 @@ export const ConfigSchema = z.object({
   mutationGate: MutationGateSchema,
 });
 
-export type AppConfig = z.infer<typeof ConfigSchema>;
+export const ConfigSchema = ConfigInputSchema.superRefine((value, ctx) => {
+  try {
+    resolveAskellTarget({
+      askellEnv: value.askellEnv,
+      apiBaseUrl: value.apiBaseUrl,
+    });
+  } catch (error) {
+    ctx.addIssue({
+      code: 'custom',
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}).transform((value) => {
+  const target = resolveAskellTarget({
+    askellEnv: value.askellEnv,
+    apiBaseUrl: value.apiBaseUrl,
+  });
+  return {
+    ...value,
+    askellEnv: target.askellEnv,
+    apiBaseUrl: target.apiBaseUrl,
+  };
+});
+
+export type AppConfig = z.output<typeof ConfigSchema>;
 
 const CONFIG_HELP = `Askell MCP credentials missing.
 
-Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_API_KEY and ASKELL_API_URL:
+Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_API_KEY.
+Set ASKELL_ENV=production|sandbox (default production) — the server picks the host.
+Keys are per host. ASKELL_API_URL is only for a custom/local API.
 
   Local dev — create .env in the project root (Bun loads it automatically):
+    ASKELL_ENV=sandbox
     ASKELL_PRIVATE_API_KEY=...
     ASKELL_PUBLIC_API_KEY=...
 
-  Published package (requires Bun) — Cursor / Claude mcp.json:
+  Published package (requires Bun) — Cursor / Claude mcp.json (two entries if you use sandbox):
     {
       "mcpServers": {
-        "askell": {
+        "askell-prod": {
+          "command": "bunx",
+          "args": ["-y", "askell-mcp@latest"],
+          "env": {
+            "ASKELL_ENV": "production",
+            "ASKELL_PRIVATE_API_KEY": "...",
+            "ASKELL_PUBLIC_API_KEY": "..."
+          }
+        },
+        "askell-sandbox": {
           "command": "bunx",
-          "args": ["-y", "askell-mcp"],
+          "args": ["-y", "askell-mcp@latest"],
           "env": {
+            "ASKELL_ENV": "sandbox",
             "ASKELL_PRIVATE_API_KEY": "...",
             "ASKELL_PUBLIC_API_KEY": "..."
           }
@@ -75,6 +171,7 @@ function loadConfigFromEnv(): unknown {
     return undefined;
   }
 
+  const askellEnv = env.ASKELL_ENV?.trim() || undefined;
   const apiBaseUrl = env.ASKELL_API_URL ?? env.ASKELL_API_BASE_URL;
   const responseMaxBytes = env.ASKELL_RESPONSE_MAX_BYTES;
   const mutationGateRaw =
@@ -82,6 +179,7 @@ function loadConfigFromEnv(): unknown {
   const mutationGate = mutationGateRaw?.trim().toLowerCase() || undefined;
 
   return {
+    ...(askellEnv ? { askellEnv } : {}),
     ...(apiBaseUrl ? { apiBaseUrl } : {}),
     secretApiKey,
     ...(env.ASKELL_PUBLIC_API_KEY

package/src/index.ts

@@ -8,7 +8,9 @@ try {
 
   void serveStdio(() => createServer(config));
 
-  console.error('askell-mcp running on stdio');
+  console.error(
+    `askell-mcp running on stdio (${config.askellEnv} ${config.apiBaseUrl})`,
+  );
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`askell-mcp failed to start: ${message}`);

package/src/server.ts

@@ -1,13 +1,34 @@
 import { McpServer } from '@modelcontextprotocol/server';
 
 import { AskellClient } from './client/askell-client.ts';
-import type { AppConfig } from './config.ts';
+import {
+  PRODUCTION_API_BASE_URL,
+  SANDBOX_API_BASE_URL,
+  normalizeBaseUrl,
+  type AppConfig,
+} from './config.ts';
 import { registerResources } from './resources/register.ts';
 import { registerAnalysisTools } from './tools/analysis.ts';
 import { registerCallTools } from './tools/call.ts';
 import { registerDiscoveryTools } from './tools/discovery.ts';
+import { PACKAGE_VERSION } from './version.ts';
 
-const SERVER_INSTRUCTIONS = `Askell MCP server for payment and subscription operations.
+export function buildServerInstructions(config: AppConfig): string {
+  const apiBase = normalizeBaseUrl(config.apiBaseUrl);
+  const envLine =
+    config.askellEnv === 'custom'
+      ? `This instance: custom API base ${apiBase} (ASKELL_API_URL override)`
+      : `This instance: ${config.askellEnv} (${apiBase})`;
+
+  return `Askell MCP server for payment and subscription operations.
+
+${envLine}
+Official hosts (picked by ASKELL_ENV=production|sandbox; do not pass the URL):
+- production: ${PRODUCTION_API_BASE_URL}
+- sandbox (isolated tenant, separate API keys): ${SANDBOX_API_BASE_URL}
+v1 and v2 share that base (v2 paths start with /v2/). Keys belong to one host — do not reuse production keys on sandbox or the reverse.
+Áskell Test Gateway is a payment acquirer on either host, not a separate API host.
+If both askell-prod and askell-sandbox MCP servers are connected, pick the instance whose environment matches the intended tenant.
 
 Workflow:
 1. Use askell_list_operations and askell_describe_operation to discover endpoints, parameters, and auth requirements.
@@ -47,15 +68,16 @@ Safety:
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
 - askell://docs/webhook-events — inbound webhook payloads (not in OpenAPI; dummy /your-webhook-url/ is stripped on sync), HMAC-SHA512, /webhooks/ hmac_secret`;
+}
 
 export function createServer(config: AppConfig): McpServer {
   const server = new McpServer(
     {
       name: 'askell-mcp',
-      version: '0.3.1',
+      version: PACKAGE_VERSION,
     },
     {
-      instructions: SERVER_INSTRUCTIONS,
+      instructions: buildServerInstructions(config),
     },
   );
 

package/src/version.ts

@@ -0,0 +1,3 @@
+import packageJson from '../package.json' with { type: 'json' };
+
+export const PACKAGE_VERSION: string = packageJson.version;