@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 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
- - Pagination starts at `offset: 0`. Keep `limit` small when an agent only needs a summary.
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/v1/traces" and read headers from "OTEL_EXPORT_HEADERS". Show the destination and enabled data, then wait for my confirmation.
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/v1/traces" using headers from "OTEL_EXPORT_HEADERS". Wait for my confirmation, apply the change, and report only the final safe settings.
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.3.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
- limit: z.number().int().min(1).max(200).optional(),
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
- limit: z.number().int().min(1).max(200).optional(),
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.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.3.0",
40
+ "@airctrl/sdk": "0.4.0",
41
41
  "@modelcontextprotocol/sdk": "1.32.1",
42
- "zod": "4.4.3"
42
+ "zod": "4.6.7"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@types/node": "22.20.0"