@airctrl/mcp 0.3.0 → 0.4.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.
- package/README.md +80 -7
- package/dist/index.js +1 -1
- package/dist/tools.js +23 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -14,6 +14,39 @@ npx --yes @airctrl/mcp
|
|
|
14
14
|
|
|
15
15
|
Requires Node.js 22.x.
|
|
16
16
|
|
|
17
|
+
## Current release
|
|
18
|
+
|
|
19
|
+
**Coordinated package version:** `0.4.0`
|
|
20
|
+
|
|
21
|
+
### SDK
|
|
22
|
+
|
|
23
|
+
- Added `OAuthPartnerClient`, PKCE generation, authorization-code exchange, rotating refresh tokens, and token revocation for confidential partner backends.
|
|
24
|
+
- Added provider resolution, provider-key validation, live model discovery, entitlement preflight, atomic protection provisioning, and installation-bound protection reads and updates.
|
|
25
|
+
- Added provider-key rotation, runtime-token rotation, revoke, and reactivate lifecycle operations with typed idempotency and error handling.
|
|
26
|
+
- Added public multi-organization OAuth Apps: one publisher-owned Client ID can create isolated installations inside customer-selected AIRCTRL organizations.
|
|
27
|
+
- Added `listProtectionLogs()` and `getProtectionSpend()` with dedicated least-privilege scopes and strict installation/protection binding.
|
|
28
|
+
- Added stable cursor pagination and canonical account, project, gateway, token, principal, trace, and span correlation across request-log, usage, and audit feeds.
|
|
29
|
+
- Added OpenTelemetry body-export controls and shared gateway connection types aligned with the public API contract.
|
|
30
|
+
|
|
31
|
+
### CLI
|
|
32
|
+
|
|
33
|
+
- Added opaque cursor support to gateway logs, provider-key access, usage logs, record alerts, and record access commands.
|
|
34
|
+
- Added the `audit-events` command with cursor, action, actor, and date filters.
|
|
35
|
+
- Added OpenTelemetry request/response body-export configuration while preserving the existing header-custody contract.
|
|
36
|
+
|
|
37
|
+
### MCP
|
|
38
|
+
|
|
39
|
+
- Added opaque cursor inputs to gateway, usage, record-alert, and record-access tools.
|
|
40
|
+
- Added `list_record_audit` with stable filters and pagination.
|
|
41
|
+
- Added OpenTelemetry body-export configuration and aligned pagination limits with the API contract.
|
|
42
|
+
|
|
43
|
+
### Release engineering
|
|
44
|
+
|
|
45
|
+
- Kept SDK, CLI, and MCP manifests, internal dependencies, exported version constants, generated READMEs, and tarball names aligned at `0.4.0`.
|
|
46
|
+
- Build `@airctrl/client-contracts` before OpenAPI generation and full-stack certification so clean release runners never depend on cached workspace output.
|
|
47
|
+
- Expanded package verification across the public API, generated examples, installed-package behavior, exact tarballs, and Linux, Windows, and macOS certification.
|
|
48
|
+
- Kept `@airctrl/crypto` and `@airctrl/secrets` private and bundled the required runtime into the public SDK.
|
|
49
|
+
|
|
17
50
|
## MCP setup
|
|
18
51
|
|
|
19
52
|
`@airctrl/mcp` runs locally on your machine or in infrastructure you control. It uses `@airctrl/sdk` for AIRCTRL operations.
|
|
@@ -269,10 +302,25 @@ These metadata tools are human-only. Service Account creation, state changes, cr
|
|
|
269
302
|
| Tool | Inputs | Purpose |
|
|
270
303
|
|---|---|---|
|
|
271
304
|
| `read_record_audit` | `recordId`; optional `limit` | Read audit events for one record. |
|
|
305
|
+
| `list_record_audit` | `recordId`; optional `cursor`, `action`, `actor`, `from`, `to`, `limit`, legacy `offset` | Read a stable filtered audit-event page. |
|
|
272
306
|
| `list_record_anomalies` | Optional `accountId`, `scopeType`, `scopeId` | List unusual record events. |
|
|
273
307
|
| `list_record_activity` | `day`; optional `accountId`, `scopeType`, `scopeId` | Read one UTC day's record activity. |
|
|
274
|
-
| `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset` | Read the record alert feed. |
|
|
275
|
-
| `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset`, `actions` | Read the record access feed. |
|
|
308
|
+
| `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset` | Read the record alert feed. |
|
|
309
|
+
| `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset`, `actions` | Read the record access feed. |
|
|
310
|
+
|
|
311
|
+
Ask an agent for a bounded page and keep the returned cursor opaque:
|
|
312
|
+
|
|
313
|
+
```text
|
|
314
|
+
List the first 25 record.update audit events for record
|
|
315
|
+
00000000-0000-4000-8000-000000000020 where the actor contains "david".
|
|
316
|
+
Return pagination.next_cursor without decoding it.
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
**MCP tool used:** `list_record_audit`
|
|
322
|
+
|
|
323
|
+
|
|
276
324
|
|
|
277
325
|
### Providers and gateway setup
|
|
278
326
|
|
|
@@ -308,10 +356,10 @@ These metadata tools are human-only. Service Account creation, state changes, cr
|
|
|
308
356
|
|
|
309
357
|
| Tool | Inputs | Purpose |
|
|
310
358
|
|---|---|---|
|
|
311
|
-
| `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `limit`, `offset` | Read filtered request metadata for one gateway. |
|
|
359
|
+
| `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway. |
|
|
312
360
|
| `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
|
|
313
361
|
| `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
|
|
314
|
-
| `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `limit`, `offset` | List usage across a project. |
|
|
362
|
+
| `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
|
|
315
363
|
| `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
|
|
316
364
|
| `read_usage_spend` | `projectId` | Compare spend with effective limits. |
|
|
317
365
|
| `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
|
|
@@ -325,7 +373,7 @@ These metadata tools are human-only. Service Account creation, state changes, cr
|
|
|
325
373
|
- `read_record.scope` accepts sections only: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
|
|
326
374
|
- Omit `environment` to select General, or use `development`, `staging`, or `production` to select exactly that record value. The PAT or Service Account token must permit the selected scope; an absent value never falls back to General or another Environment.
|
|
327
375
|
- `get_secret`, `read_record` with `fields`, and `get_all` return plaintext to the local MCP client. The model or agent can receive that plaintext; use these tools only when that exposure is approved.
|
|
328
|
-
-
|
|
376
|
+
- Log pagination starts without a cursor. Continue with `pagination.next_cursor`, the same scope and the exact same filters. Cursors cannot be combined with legacy `offset`. Keep `limit` small when an agent only needs a summary.
|
|
329
377
|
- `accountId` selects the account. It does not grant access to it.
|
|
330
378
|
- `projectId`, `recordId`, `gatewayId`, `credentialId` and `tokenId` select resources. AIRCTRL still checks RBAC and resource access.
|
|
331
379
|
- Optional booleans must be real JSON booleans such as `true`, not strings such as `"true"`.
|
|
@@ -493,6 +541,19 @@ After confirmation, revoke only that token and report its final status.
|
|
|
493
541
|
|
|
494
542
|
|
|
495
543
|
|
|
544
|
+
### OAuth partner Apps
|
|
545
|
+
|
|
546
|
+
The MCP server has no OAuth App credential mode, authorization-code flow, or
|
|
547
|
+
installation/protection lifecycle tools. Do not place OAuth client secrets, authorization codes,
|
|
548
|
+
access tokens, or refresh tokens in MCP configuration or an agent conversation. Neither is a
|
|
549
|
+
confidential partner token store, and a hosted MCP would violate the partner-backend boundary.
|
|
550
|
+
|
|
551
|
+
Implement OAuth partner flows through direct HTTP/OpenAPI or `OAuthPartnerClient` in the partner's
|
|
552
|
+
confidential backend. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
|
|
553
|
+
[OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
|
|
554
|
+
[OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). MCP may manage ordinary gateways with a
|
|
555
|
+
separately authorized human PAT; those tools do not act as an OAuth installation.
|
|
556
|
+
|
|
496
557
|
### Tool results
|
|
497
558
|
|
|
498
559
|
API-backed tools return structured JSON from `@airctrl/sdk`. Read tools return the requested resource, list tools return arrays or paginated data, and write tools return the new or updated resource. One-time credentials are the exception: their plaintext is present only in the successful creation result.
|
|
@@ -1113,6 +1174,18 @@ Show the 25 most recent audit events for record "00000000-0000-4000-8000-0000000
|
|
|
1113
1174
|
|
|
1114
1175
|
|
|
1115
1176
|
|
|
1177
|
+
#### Page and filter one record's audit history
|
|
1178
|
+
|
|
1179
|
+
```text
|
|
1180
|
+
List the first 25 record.update audit events for record "00000000-0000-4000-8000-000000000020" where the actor contains "david". Return pagination.next_cursor without decoding it so I can request the next page with the same filters.
|
|
1181
|
+
```
|
|
1182
|
+
|
|
1183
|
+
|
|
1184
|
+
|
|
1185
|
+
**MCP tool used:** `list_record_audit`
|
|
1186
|
+
|
|
1187
|
+
|
|
1188
|
+
|
|
1116
1189
|
#### Find unusual record activity
|
|
1117
1190
|
|
|
1118
1191
|
```text
|
|
@@ -1516,7 +1589,7 @@ Show the OpenTelemetry export settings for gateway "00000000-0000-4000-8000-0000
|
|
|
1516
1589
|
#### Change OpenTelemetry settings
|
|
1517
1590
|
|
|
1518
1591
|
```text
|
|
1519
|
-
Enable OpenTelemetry metrics and traces for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Send them to "https://otel.example.com
|
|
1592
|
+
Enable OpenTelemetry metrics and traces for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Request events are automatic while export is enabled. Include request/response bodies only if gateway Log bodies is enabled. Send them to the base endpoint "https://otel.example.com" and read headers from "OTEL_EXPORT_HEADERS". Show the destination and enabled data, then wait for my confirmation.
|
|
1520
1593
|
```
|
|
1521
1594
|
|
|
1522
1595
|
|
|
@@ -1691,7 +1764,7 @@ Replace provider credential "00000000-0000-4000-8000-000000000071" in account "0
|
|
|
1691
1764
|
### Configure OpenTelemetry and verify safe state
|
|
1692
1765
|
|
|
1693
1766
|
```text
|
|
1694
|
-
For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", show the current OpenTelemetry state, endpoint and export flags without requesting header values. Prepare to enable metrics and traces to "https://otel.example.com
|
|
1767
|
+
For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", show the current OpenTelemetry state, endpoint and export flags without requesting header values. Prepare to enable metrics and traces to the base endpoint "https://otel.example.com" using headers from "OTEL_EXPORT_HEADERS"; request events are automatic while export is enabled. Include bodies only when gateway Log bodies is enabled. Wait for my confirmation, apply the change, and report only the final safe settings.
|
|
1695
1768
|
```
|
|
1696
1769
|
|
|
1697
1770
|
|
package/dist/index.js
CHANGED
|
@@ -14,7 +14,7 @@ import { registerTools } from './tools.js';
|
|
|
14
14
|
*/
|
|
15
15
|
const config = loadConfig();
|
|
16
16
|
const client = createClient(createMcpClientOptions(config));
|
|
17
|
-
const server = new McpServer({ name: 'airctrl', version: '0.
|
|
17
|
+
const server = new McpServer({ name: 'airctrl', version: '0.4.0' });
|
|
18
18
|
registerTools(server, client, config);
|
|
19
19
|
server.registerTool('airctrl_status', {
|
|
20
20
|
title: 'AIRCTRL MCP status',
|
package/dist/tools.js
CHANGED
|
@@ -418,6 +418,7 @@ export function registerTools(inputServer, client, config) {
|
|
|
418
418
|
provider: z.string().max(64).optional(),
|
|
419
419
|
model: z.string().max(200).optional(),
|
|
420
420
|
status: z.number().int().min(100).max(599).optional(),
|
|
421
|
+
cursor: z.string().max(2048).optional(),
|
|
421
422
|
limit: z.number().int().min(1).max(200).optional(),
|
|
422
423
|
offset: z.number().int().min(0).optional(),
|
|
423
424
|
},
|
|
@@ -432,6 +433,7 @@ export function registerTools(inputServer, client, config) {
|
|
|
432
433
|
model: z.string().max(200).optional(),
|
|
433
434
|
status: z.number().int().min(100).max(599).optional(),
|
|
434
435
|
gatewayId: z.string().uuid().optional(),
|
|
436
|
+
cursor: z.string().max(2048).optional(),
|
|
435
437
|
limit: z.number().int().min(1).max(200).optional(),
|
|
436
438
|
offset: z.number().int().min(0).optional(),
|
|
437
439
|
},
|
|
@@ -629,6 +631,7 @@ export function registerTools(inputServer, client, config) {
|
|
|
629
631
|
endpoint: z.string().nullable().optional(),
|
|
630
632
|
exportMetrics: z.boolean().optional(),
|
|
631
633
|
exportTraces: z.boolean().optional(),
|
|
634
|
+
exportBodies: z.boolean().optional(),
|
|
632
635
|
headersEnv: z.string().optional(),
|
|
633
636
|
clearHeaders: z.boolean().optional(),
|
|
634
637
|
},
|
|
@@ -667,10 +670,11 @@ export function registerTools(inputServer, client, config) {
|
|
|
667
670
|
gatewayId: z.string().uuid(),
|
|
668
671
|
outcome: z.enum(['granted', 'denied', 'error']).optional(),
|
|
669
672
|
since: z.string().optional(),
|
|
673
|
+
cursor: z.string().max(4096).optional(),
|
|
670
674
|
limit: z.number().int().min(1).max(200).optional(),
|
|
671
675
|
offset: z.number().int().min(0).optional(),
|
|
672
676
|
},
|
|
673
|
-
}, ({ gatewayId, outcome, since, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, limit, offset })));
|
|
677
|
+
}, ({ gatewayId, outcome, since, cursor, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, cursor, limit, offset })));
|
|
674
678
|
server.registerTool('list_provider_credentials', {
|
|
675
679
|
title: 'List provider credentials',
|
|
676
680
|
description: 'List provider credential metadata for an account. Secret values are never returned.',
|
|
@@ -723,6 +727,20 @@ export function registerTools(inputServer, client, config) {
|
|
|
723
727
|
limit: z.number().int().min(1).max(1000).optional(),
|
|
724
728
|
},
|
|
725
729
|
}, ({ recordId, limit }) => run(() => client.getRecordAudit(recordId, limit)));
|
|
730
|
+
server.registerTool('list_record_audit', {
|
|
731
|
+
title: 'List record audit events',
|
|
732
|
+
description: 'List one stable cursor page of audit-event metadata for a record. Secret values are never returned.',
|
|
733
|
+
inputSchema: {
|
|
734
|
+
recordId: z.string().uuid(),
|
|
735
|
+
limit: z.number().int().min(1).max(100).optional(),
|
|
736
|
+
offset: z.number().int().min(0).optional(),
|
|
737
|
+
cursor: z.string().max(4096).optional(),
|
|
738
|
+
action: z.string().max(160).optional(),
|
|
739
|
+
actor: z.string().max(254).optional(),
|
|
740
|
+
from: z.string().optional(),
|
|
741
|
+
to: z.string().optional(),
|
|
742
|
+
},
|
|
743
|
+
}, ({ recordId, ...input }) => run(() => client.listRecordAudit(recordId, input)));
|
|
726
744
|
server.registerTool('update_record_metadata', {
|
|
727
745
|
title: 'Update record metadata',
|
|
728
746
|
description: 'Update a record name, tags, due date, or rotation interval without changing ciphertext.',
|
|
@@ -862,7 +880,8 @@ export function registerTools(inputServer, client, config) {
|
|
|
862
880
|
accountId: z.string().uuid().optional(),
|
|
863
881
|
scopeType: z.enum(['user', 'project']).optional(),
|
|
864
882
|
scopeId: z.string().uuid().optional(),
|
|
865
|
-
|
|
883
|
+
cursor: z.string().max(4096).optional(),
|
|
884
|
+
limit: z.number().int().min(1).max(100).optional(),
|
|
866
885
|
offset: z.number().int().min(0).optional(),
|
|
867
886
|
},
|
|
868
887
|
}, (input) => run(() => client.listRecordAlerts(input)));
|
|
@@ -873,7 +892,8 @@ export function registerTools(inputServer, client, config) {
|
|
|
873
892
|
accountId: z.string().uuid().optional(),
|
|
874
893
|
scopeType: z.enum(['user', 'project']).optional(),
|
|
875
894
|
scopeId: z.string().uuid().optional(),
|
|
876
|
-
|
|
895
|
+
cursor: z.string().max(4096).optional(),
|
|
896
|
+
limit: z.number().int().min(1).max(100).optional(),
|
|
877
897
|
offset: z.number().int().min(0).optional(),
|
|
878
898
|
actions: z.array(z.string().min(1)).optional(),
|
|
879
899
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@airctrl/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Local/self-hosted MCP server for AIRCTRL records, projects, gateways and usage workflows.",
|
|
6
6
|
"license": "UNLICENSED",
|
|
@@ -37,9 +37,9 @@
|
|
|
37
37
|
"start": "node dist/index.js"
|
|
38
38
|
},
|
|
39
39
|
"dependencies": {
|
|
40
|
-
"@airctrl/sdk": "0.
|
|
40
|
+
"@airctrl/sdk": "0.4.0",
|
|
41
41
|
"@modelcontextprotocol/sdk": "1.32.1",
|
|
42
|
-
"zod": "4.
|
|
42
|
+
"zod": "4.6.7"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
45
45
|
"@types/node": "22.20.0"
|