askell-mcp 0.1.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +16 -5
  2. package/package.json +9 -8
  3. package/spec/openapi-v2.json +435 -49
  4. package/src/client/response-formatter.ts +113 -32
  5. package/src/config.ts +36 -27
  6. package/src/openapi/registry.ts +17 -7
  7. package/src/resources/register.ts +53 -27
  8. package/src/server.ts +13 -7
  9. package/src/tools/analysis.ts +38 -10
  10. package/src/tools/call.ts +142 -61
  11. package/src/tools/discovery.ts +9 -5
  12. package/src/tools/mutation-gate.ts +74 -0
package/README.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  [MCP](https://modelcontextprotocol.io) server for the [Askell](https://askell.is) payment and subscription API.
4
4
 
5
- Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpoints, inspect customers/contracts/billing, and call the API — with confirmation before mutating requests.
5
+ Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpoints, inspect customers/contracts/billing, and call the API. Reads and writes are separate tools so clients can show their own approval UI on mutations.
6
6
 
7
7
  ## Requirements
8
8
 
9
9
  - An [Askell](https://askell.is) account and **secret API key** (from the Askell dashboard)
10
10
  - One of:
11
- - [Bun](https://bun.sh) ≥ 1.3.14 (for `bunx`), or
11
+ - [Bun](https://bun.sh) ≥ 1.4.0 (for `bunx`), or
12
12
  - a prebuilt binary from [Releases](https://github.com/Neschadin/askell-mcp/releases) (no Bun needed)
13
13
 
14
14
  ## Quick start
@@ -62,17 +62,26 @@ Restart the client after saving.
62
62
  | `ASKELL_PUBLIC_API_KEY` | no | — | Public key for a few checkout/payment endpoints |
63
63
  | `ASKELL_API_URL` | no | `https://askell.is/api` | API base URL (_or_ `ASKELL_API_BASE_URL`) |
64
64
  | `ASKELL_RESPONSE_MAX_BYTES` | no | `64000` | Max response size returned to the model |
65
- | `ASKELL_REQUIRE_MUTATION_APPROVAL` | no | `true` | Confirm before POST/PUT/PATCH/DELETE |
65
+ | `ASKELL_MUTATION_GATE` | no | `auto` | `auto` / `elicit` / `off` — see below |
66
+ | `ASKELL_REQUIRE_MUTATION_APPROVAL` | no | — | Deprecated alias: `true`→`elicit`, `false`→`off` |
66
67
 
67
68
  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).
68
69
 
70
+ `ASKELL_MUTATION_GATE`:
71
+
72
+ - **`auto` (default)** — confirmation form only if *this request's* `_meta` envelope declared form elicitation (MCP 2026-07-28). 2025-era clients (Cursor, most hosts) do not send that envelope, so the mutation runs and their own “allow this tool” UI is the gate.
73
+ - **`elicit`** — always return an elicitation form. The SDK refuses the call if the client cannot fulfil it (2026 envelope / 2025 initialize via the legacy shim).
74
+ - **`off`** — never ask (eval / trusted automation).
75
+
76
+ If both `ASKELL_MUTATION_GATE` and `ASKELL_REQUIRE_MUTATION_APPROVAL` are set, `ASKELL_MUTATION_GATE` wins.
77
+
69
78
  ## What you can do
70
79
 
71
80
  Typical agent workflow:
72
81
 
73
82
  1. **Discover** — `askell_list_operations` / `askell_describe_operation` (from bundled OpenAPI v1 + v2)
74
83
  2. **Support tasks** — customer/contract/billing helpers below
75
- 3. **Anything else** — `askell_call` for a raw endpoint (mutations ask for approval when enabled)
84
+ 3. **Anything else** — `askell_call` for GET/HEAD, `askell_mutate` for POST/PUT/PATCH/DELETE
76
85
 
77
86
  ### Tools
78
87
 
@@ -80,7 +89,8 @@ Typical agent workflow:
80
89
  | --------------------------- | ---------------------------------------- |
81
90
  | `askell_list_operations` | Search bundled OpenAPI operations |
82
91
  | `askell_describe_operation` | Params and body schema for one operation |
83
- | `askell_call` | Call any v1/v2 endpoint |
92
+ | `askell_call` | GET/HEAD any v1/v2 endpoint |
93
+ | `askell_mutate` | POST/PUT/PATCH/DELETE any v1/v2 endpoint |
84
94
  | `askell_paginate_all` | Follow paginated list endpoints |
85
95
  | `askell_customer_overview` | v1 customer + subscriptions |
86
96
  | `askell_contract_overview` | v2 subscription contract + billing runs |
@@ -99,6 +109,7 @@ Typical agent workflow:
99
109
 
100
110
  - **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
101
111
  - **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
112
+ - **v2 coupons** — `GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount` (one active coupon). Quotes take `promotion_code`. Not the v1 `discount` 0–100 field.
102
113
  - Paths use **trailing slashes**
103
114
  - Prefer **v2** for new integrations; v1 remains for existing ones
104
115
  - Docs: [docs.askell.is](https://docs.askell.is/) · OpenAPI: [v1](https://askell.is/api/swagger/swagger.json) · [v2](https://askell.is/api/swagger/v2/swagger.json)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "askell-mcp",
3
- "version": "0.1.2",
3
+ "version": "0.3.0",
4
4
  "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
5
5
  "author": "Neschadin Oleksandr",
6
6
  "license": "MIT",
@@ -35,7 +35,7 @@
35
35
  "mcp.json.example"
36
36
  ],
37
37
  "engines": {
38
- "bun": ">=1.3.14"
38
+ "bun": ">=1.4.0"
39
39
  },
40
40
  "publishConfig": {
41
41
  "access": "public",
@@ -47,19 +47,20 @@
47
47
  "test": "bun test",
48
48
  "smoke": "bun run scripts/smoke-test.ts",
49
49
  "test:integration": "bun run scripts/integration-test.ts",
50
+ "eval:tools": "bun run scripts/eval-tools.ts",
50
51
  "typecheck": "tsc --noEmit",
51
52
  "inspect": "bunx @modelcontextprotocol/inspector bun bin/askell-mcp",
52
53
  "sync-specs": "bun run scripts/sync-specs.ts",
53
54
  "prepack": "bun test && bun run typecheck",
54
- "build": "bun build --compile --minify src/index.ts --outfile dist/askell-mcp",
55
- "build:linux-x64": "bun build --compile --minify --target=bun-linux-x64 src/index.ts --outfile dist/askell-mcp-linux-x64",
56
- "build:linux-arm64": "bun build --compile --minify --target=bun-linux-arm64 src/index.ts --outfile dist/askell-mcp-linux-arm64",
57
- "build:darwin-arm64": "bun build --compile --minify --target=bun-darwin-arm64 src/index.ts --outfile dist/askell-mcp-darwin-arm64",
58
- "build:darwin-x64": "bun build --compile --minify --target=bun-darwin-x64 src/index.ts --outfile dist/askell-mcp-darwin-x64",
55
+ "build": "bun build --compile --minify --bytecode --format=esm src/index.ts --outfile dist/askell-mcp",
56
+ "build:linux-x64": "bun build --compile --minify --bytecode --format=esm --target=bun-linux-x64 src/index.ts --outfile dist/askell-mcp-linux-x64",
57
+ "build:linux-arm64": "bun build --compile --minify --bytecode --format=esm --target=bun-linux-arm64 src/index.ts --outfile dist/askell-mcp-linux-arm64",
58
+ "build:darwin-arm64": "bun build --compile --minify --bytecode --format=esm --target=bun-darwin-arm64 src/index.ts --outfile dist/askell-mcp-darwin-arm64",
59
+ "build:darwin-x64": "bun build --compile --minify --bytecode --format=esm --target=bun-darwin-x64 src/index.ts --outfile dist/askell-mcp-darwin-x64",
59
60
  "build:all": "bun run build && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-arm64 && bun run build:darwin-x64"
60
61
  },
61
62
  "devDependencies": {
62
- "@types/bun": "1.3.14",
63
+ "@types/bun": "1.4.0",
63
64
  "typescript": "7.0.2"
64
65
  },
65
66
  "dependencies": {