askell-mcp 0.1.0 → 0.1.2
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.
- package/README.md +58 -150
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,18 +1,25 @@
|
|
|
1
1
|
# askell-mcp
|
|
2
2
|
|
|
3
|
-
MCP server for [Askell](https://askell.is) payment and subscription API
|
|
3
|
+
[MCP](https://modelcontextprotocol.io) server for the [Askell](https://askell.is) payment and subscription API.
|
|
4
4
|
|
|
5
|
-
|
|
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.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Requirements
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- An [Askell](https://askell.is) account and **secret API key** (from the Askell dashboard)
|
|
10
|
+
- One of:
|
|
11
|
+
- [Bun](https://bun.sh) ≥ 1.3.14 (for `bunx`), or
|
|
12
|
+
- a prebuilt binary from [Releases](https://github.com/Neschadin/askell-mcp/releases) (no Bun needed)
|
|
10
13
|
|
|
11
|
-
##
|
|
14
|
+
## Quick start
|
|
12
15
|
|
|
13
|
-
###
|
|
16
|
+
### 1. Get API keys
|
|
14
17
|
|
|
15
|
-
|
|
18
|
+
In the Askell dashboard, copy your **private (secret)** API key. Optionally also the **public** key (only needed for temporary payment-method / checkout status endpoints).
|
|
19
|
+
|
|
20
|
+
### 2. Add to your MCP client
|
|
21
|
+
|
|
22
|
+
**With Bun** (`bunx`):
|
|
16
23
|
|
|
17
24
|
```json
|
|
18
25
|
{
|
|
@@ -21,25 +28,14 @@ Requires Bun on the machine. In Cursor / Claude Desktop `mcp.json`:
|
|
|
21
28
|
"command": "bunx",
|
|
22
29
|
"args": ["-y", "askell-mcp"],
|
|
23
30
|
"env": {
|
|
24
|
-
"ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
|
|
25
|
-
"ASKELL_PUBLIC_API_KEY": "your_public_api_key_optional"
|
|
31
|
+
"ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
|
|
26
32
|
}
|
|
27
33
|
}
|
|
28
34
|
}
|
|
29
35
|
}
|
|
30
36
|
```
|
|
31
37
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
bun add -g askell-mcp
|
|
36
|
-
askell-mcp
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
### Option B — compiled binary (no Bun at runtime)
|
|
40
|
-
|
|
41
|
-
Download the asset for your OS/arch from the [GitHub Release](https://github.com/Neschadin/askell-mcp/releases) for the version you want
|
|
42
|
-
(`askell-mcp-linux-x64`, `askell-mcp-darwin-arm64`, …), `chmod +x`, then:
|
|
38
|
+
**With a binary** (download `askell-mcp-<os>-<arch>` from [Releases](https://github.com/Neschadin/askell-mcp/releases), then `chmod +x`):
|
|
43
39
|
|
|
44
40
|
```json
|
|
45
41
|
{
|
|
@@ -54,151 +50,63 @@ Download the asset for your OS/arch from the [GitHub Release](https://github.com
|
|
|
54
50
|
}
|
|
55
51
|
```
|
|
56
52
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
## Features
|
|
60
|
-
|
|
61
|
-
- **`askell_call`** — call any v1/v2 endpoint; mutating requests require operator approval via MCP elicitation
|
|
62
|
-
- **`askell_list_operations` / `askell_describe_operation`** — discover endpoints from bundled OpenAPI specs
|
|
63
|
-
- **Analysis helpers** — `askell_paginate_all`, `askell_customer_overview`, `askell_contract_overview`, `askell_billing_run_triage`, `askell_list_webhooks`
|
|
64
|
-
- **Resources** — bundled OpenAPI v1/v2 specs and webhook event reference
|
|
53
|
+
Example file: [`mcp.json.example`](./mcp.json.example).
|
|
65
54
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
Askell does **not** expose a separate sandbox/staging API host. Production and test integrations use the same base URL:
|
|
69
|
-
|
|
70
|
-
```text
|
|
71
|
-
https://askell.is/api
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Testing is done with the **Áskell Test Gateway** payment acquirer in your Askell account dashboard, not via a different API hostname. See [Askell Set Up docs](https://docs.askell.is/en/getting_started/index.html).
|
|
75
|
-
|
|
76
|
-
`apiBaseUrl` remains configurable in case Askell adds environments later.
|
|
55
|
+
Restart the client after saving.
|
|
77
56
|
|
|
78
57
|
## Configuration
|
|
79
58
|
|
|
80
|
-
| Variable
|
|
81
|
-
|
|
|
82
|
-
| `ASKELL_PRIVATE_API_KEY`
|
|
83
|
-
| `ASKELL_PUBLIC_API_KEY`
|
|
84
|
-
| `ASKELL_API_URL`
|
|
85
|
-
| `ASKELL_RESPONSE_MAX_BYTES`
|
|
86
|
-
| `ASKELL_REQUIRE_MUTATION_APPROVAL`
|
|
87
|
-
|
|
88
|
-
## Develop locally
|
|
89
|
-
|
|
90
|
-
```bash
|
|
91
|
-
cp .env.example .env
|
|
92
|
-
# edit keys
|
|
93
|
-
bun install
|
|
94
|
-
bun run dev
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
Bun loads `.env` automatically from the project root.
|
|
98
|
-
|
|
99
|
-
From a checkout (without publishing):
|
|
100
|
-
|
|
101
|
-
```json
|
|
102
|
-
{
|
|
103
|
-
"mcpServers": {
|
|
104
|
-
"askell": {
|
|
105
|
-
"command": "bun",
|
|
106
|
-
"args": ["run", "bin/askell-mcp"],
|
|
107
|
-
"cwd": "/absolute/path/to/askell-mcp",
|
|
108
|
-
"env": {
|
|
109
|
-
"ASKELL_PRIVATE_API_KEY": "..."
|
|
110
|
-
}
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
Unit tests (no network):
|
|
59
|
+
| Variable | Required | Default | Description |
|
|
60
|
+
| ---------------------------------- | -------- | ----------------------- | ----------------------------------------------- |
|
|
61
|
+
| `ASKELL_PRIVATE_API_KEY` | yes\* | — | Secret API key (_or_ `ASKELL_SECRET_API_KEY`) |
|
|
62
|
+
| `ASKELL_PUBLIC_API_KEY` | no | — | Public key for a few checkout/payment endpoints |
|
|
63
|
+
| `ASKELL_API_URL` | no | `https://askell.is/api` | API base URL (_or_ `ASKELL_API_BASE_URL`) |
|
|
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 |
|
|
117
66
|
|
|
118
|
-
|
|
119
|
-
bun test
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
Live smoke / integration (needs `ASKELL_PRIVATE_API_KEY` in `.env`):
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
bun run smoke
|
|
126
|
-
bun run test:integration
|
|
127
|
-
```
|
|
67
|
+
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).
|
|
128
68
|
|
|
129
|
-
|
|
69
|
+
## What you can do
|
|
130
70
|
|
|
131
|
-
|
|
132
|
-
bun run inspect
|
|
133
|
-
```
|
|
71
|
+
Typical agent workflow:
|
|
134
72
|
|
|
135
|
-
|
|
73
|
+
1. **Discover** — `askell_list_operations` / `askell_describe_operation` (from bundled OpenAPI v1 + v2)
|
|
74
|
+
2. **Support tasks** — customer/contract/billing helpers below
|
|
75
|
+
3. **Anything else** — `askell_call` for a raw endpoint (mutations ask for approval when enabled)
|
|
136
76
|
|
|
137
|
-
|
|
138
|
-
bun run sync-specs
|
|
139
|
-
```
|
|
77
|
+
### Tools
|
|
140
78
|
|
|
141
|
-
|
|
79
|
+
| Tool | Description |
|
|
80
|
+
| --------------------------- | ---------------------------------------- |
|
|
81
|
+
| `askell_list_operations` | Search bundled OpenAPI operations |
|
|
82
|
+
| `askell_describe_operation` | Params and body schema for one operation |
|
|
83
|
+
| `askell_call` | Call any v1/v2 endpoint |
|
|
84
|
+
| `askell_paginate_all` | Follow paginated list endpoints |
|
|
85
|
+
| `askell_customer_overview` | v1 customer + subscriptions |
|
|
86
|
+
| `askell_contract_overview` | v2 subscription contract + billing runs |
|
|
87
|
+
| `askell_billing_run_triage` | v2 billing run (+ optional contract) |
|
|
88
|
+
| `askell_list_webhooks` | List configured webhooks |
|
|
142
89
|
|
|
143
|
-
|
|
144
|
-
- v2: https://askell.is/api/swagger/v2/swagger.json
|
|
90
|
+
### Resources
|
|
145
91
|
|
|
146
|
-
|
|
92
|
+
| URI | Content |
|
|
93
|
+
| ------------------------------ | ----------------------- |
|
|
94
|
+
| `askell://spec/v1` | OpenAPI v1 |
|
|
95
|
+
| `askell://spec/v2` | OpenAPI v2 |
|
|
96
|
+
| `askell://docs/webhook-events` | Webhook event reference |
|
|
147
97
|
|
|
148
|
-
|
|
98
|
+
## API notes (short)
|
|
149
99
|
|
|
150
|
-
|
|
100
|
+
- **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
|
|
101
|
+
- **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
|
|
102
|
+
- Paths use **trailing slashes**
|
|
103
|
+
- Prefer **v2** for new integrations; v1 remains for existing ones
|
|
104
|
+
- 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)
|
|
151
105
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
Classic `NPM_TOKEN` + 2FA fails CI with `EOTP`. Use OIDC only:
|
|
155
|
-
|
|
156
|
-
1. Create the package on [npmjs.com](https://www.npmjs.com/) (empty / first manual publish if the name is new)
|
|
157
|
-
2. Open **askell-mcp** → **Settings** → **Trusted Publisher** → GitHub Actions:
|
|
158
|
-
- Organization or user: `Neschadin`
|
|
159
|
-
- Repository: `askell-mcp`
|
|
160
|
-
- Workflow filename: `release.yml` (filename only)
|
|
161
|
-
3. Do **not** set `NPM_TOKEN` / `NODE_AUTH_TOKEN` in the repo — workflow uses `id-token: write`
|
|
162
|
-
4. After a successful OIDC publish, revoke any legacy automation tokens and prefer “Require 2FA and disallow tokens”
|
|
163
|
-
|
|
164
|
-
Local binary builds:
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
bun run build:linux-x64
|
|
168
|
-
# → dist/askell-mcp-linux-x64
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
Dry-run pack:
|
|
106
|
+
## License
|
|
172
107
|
|
|
173
|
-
|
|
174
|
-
npm pack --dry-run
|
|
175
|
-
```
|
|
108
|
+
[MIT](./LICENSE)
|
|
176
109
|
|
|
177
|
-
##
|
|
178
|
-
|
|
179
|
-
| Tool | Description |
|
|
180
|
-
| --------------------------- | ----------------------------------------- |
|
|
181
|
-
| `askell_list_operations` | Search bundled OpenAPI operations |
|
|
182
|
-
| `askell_describe_operation` | Full params/body schema for one operation |
|
|
183
|
-
| `askell_call` | Raw API call with mutation approval |
|
|
184
|
-
| `askell_paginate_all` | Auto-follow paginated list endpoints |
|
|
185
|
-
| `askell_customer_overview` | v1 customer + subscriptions |
|
|
186
|
-
| `askell_contract_overview` | v2 contract + billing runs |
|
|
187
|
-
| `askell_billing_run_triage` | v2 billing run + optional contract |
|
|
188
|
-
| `askell_list_webhooks` | v1 webhook management list |
|
|
189
|
-
|
|
190
|
-
## Evaluation
|
|
191
|
-
|
|
192
|
-
`evaluation.xml` has 10 read-only Q&A pairs for testing whether an LLM can use these tools effectively. Run with the skill harness if present:
|
|
193
|
-
|
|
194
|
-
```bash
|
|
195
|
-
python .agents/skills/mcp-tool-design/scripts/evaluation.py \
|
|
196
|
-
-t stdio -c bun -a run bin/askell-mcp \
|
|
197
|
-
-e ASKELL_PRIVATE_API_KEY=... \
|
|
198
|
-
-o evaluation_report.md \
|
|
199
|
-
evaluation.xml
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
## License
|
|
110
|
+
## Contributing
|
|
203
111
|
|
|
204
|
-
|
|
112
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for local development, tests, and releases.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "askell-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
|
|
5
5
|
"author": "Neschadin Oleksandr",
|
|
6
6
|
"license": "MIT",
|
|
@@ -51,11 +51,11 @@
|
|
|
51
51
|
"inspect": "bunx @modelcontextprotocol/inspector bun bin/askell-mcp",
|
|
52
52
|
"sync-specs": "bun run scripts/sync-specs.ts",
|
|
53
53
|
"prepack": "bun test && bun run typecheck",
|
|
54
|
-
"build": "bun build --compile src/index.ts --outfile dist/askell-mcp",
|
|
55
|
-
"build:linux-x64": "bun build --compile --target=bun-linux-x64 src/index.ts --outfile dist/askell-mcp-linux-x64",
|
|
56
|
-
"build:linux-arm64": "bun build --compile --target=bun-linux-arm64 src/index.ts --outfile dist/askell-mcp-linux-arm64",
|
|
57
|
-
"build:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/index.ts --outfile dist/askell-mcp-darwin-arm64",
|
|
58
|
-
"build:darwin-x64": "bun build --compile --target=bun-darwin-x64 src/index.ts --outfile dist/askell-mcp-darwin-x64",
|
|
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",
|
|
59
59
|
"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
60
|
},
|
|
61
61
|
"devDependencies": {
|