@airctrl/mcp 0.4.0 → 0.5.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
@@ -16,36 +16,26 @@ Requires Node.js 22.x.
16
16
 
17
17
  ## Current release
18
18
 
19
- **Coordinated package version:** `0.4.0`
19
+ **Coordinated package version:** `0.5.0`
20
20
 
21
21
  ### SDK
22
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.
23
+ - Added privileged full-text gateway log search, HTTP status-family filtering, and gateway-scoped usage metrics and spend inputs.
24
+ - Added native connection URLs for Groq, Novita AI, Atlas Cloud, and xAI to the shared gateway connection builder.
25
+ - Added pricing display text and structured rate-card tiers so provider-published zero and context-tiered rates remain explicit.
30
26
 
31
27
  ### CLI
32
28
 
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.
29
+ - Added gateway log `--search` and `--status-class` filters plus gateway-scoped usage metrics and spend flags.
36
30
 
37
31
  ### MCP
38
32
 
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.
33
+ - Added the same gateway log search and scoped metrics inputs to `read_usage`, `read_usage_metrics`, and `read_usage_spend`.
42
34
 
43
35
  ### Release engineering
44
36
 
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.
37
+ - Coordinated SDK, CLI, MCP, Web, and Authenticator package references at `0.5.0` so clean builds consume the exact release candidate instead of the previously published SDK.
38
+ - Retained sealed-candidate certification and manual npm publication with final approval and 2FA.
49
39
 
50
40
  ## MCP setup
51
41
 
@@ -329,14 +319,14 @@ Return pagination.next_cursor without decoding it.
329
319
  | `list_providers` | None | List enabled AI providers. |
330
320
  | `list_provider_credentials` | `accountId` | List safe provider credential metadata. |
331
321
  | `add_provider_key` | `accountId`, `providerId`, `apiKeyEnv`; optional `label`, `baseUrlOverride`, `credentialKind` | Read a provider value from an allowed environment variable and store it. `credentialKind` accepts `api_key`, `oauth`, `aws_sigv4`, or `gcp_sa`. |
332
- | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential. |
322
+ | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential, including official numeric rates, `displayText`, and context-tiered `rateCard` data. |
333
323
  | `rotate_provider_key` | `accountId`, `credentialId`, `apiKeyEnv` | Replace a provider credential using an `AIRCTRL_MCP_KEY_*` environment variable; the raw key never enters the tool call. |
334
324
  | `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. |
335
325
  | `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. |
336
326
  | `list_gateways` | `projectId` | List gateways in one project. |
337
327
  | `create_gateway` | `accountId`, `projectId`, `name`; optional `slug`, `credentialBindings` | Create a gateway, optionally with explicit credential/model bindings. |
338
328
  | `setup_gateway` | `projectId`, `provider`, `apiKeyEnv`, `models`; optional `name`, `tokenName`, `baseUrlOverride` | Add or reuse a provider credential, validate and bind every live-catalog model, create a gateway, mint a token and return connection data. |
339
- | `get_connection_config` | `gatewayId` | Return compatibility and native OpenAI, Anthropic, Gemini, Mistral and OpenRouter URLs, plus supported realtime WebSocket URLs. |
329
+ | `get_connection_config` | `gatewayId` | Return compatibility and native OpenAI, Anthropic, Gemini, Mistral, OpenRouter, HiTheo, Groq, Novita AI, Atlas Cloud, and xAI URLs, plus supported realtime WebSocket URLs. |
340
330
  | `set_routing` | `accountId`, `gatewayId`; optional `name`, `isActive`, `attachCredentialId`, `modelIds` | Update gateway metadata and optionally attach one credential to several live-catalog models. `attachCredentialId` and `modelIds` are provided together. |
341
331
  | `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails or allowed models. |
342
332
  | `detach_gateway_credential` | `accountId`, `gatewayId`, `credentialId`; optional `modelId` | With `modelId`, remove one exact model binding. Without it, detach every model for the credential. The credential is not revoked. |
@@ -356,13 +346,13 @@ Return pagination.next_cursor without decoding it.
356
346
 
357
347
  | Tool | Inputs | Purpose |
358
348
  |---|---|---|
359
- | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway. |
349
+ | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `statusClass`, `search`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway and search stored bodies when authorized. |
360
350
  | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
361
351
  | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
362
352
  | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
363
353
  | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
364
- | `read_usage_spend` | `projectId` | Compare spend with effective limits. |
365
- | `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
354
+ | `read_usage_spend` | `projectId`; optional `gatewayId` | Compare spend with effective project or gateway limits. |
355
+ | `read_usage_metrics` | `projectId`; optional `since`, `bucket`, `gatewayId`, `provider`, `model`, `statusClass`, `search` | Read filterable project or gateway metrics. |
366
356
  | `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. |
367
357
  | `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. |
368
358
 
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.4.0' });
17
+ const server = new McpServer({ name: 'airctrl', version: '0.5.0' });
18
18
  registerTools(server, client, config);
19
19
  server.registerTool('airctrl_status', {
20
20
  title: 'AIRCTRL MCP status',
package/dist/tools.js CHANGED
@@ -52,6 +52,10 @@ function buildConnectionConfig(config, gw) {
52
52
  mistral: connection.mistralBaseUrl,
53
53
  openrouter: connection.openrouterBaseUrl,
54
54
  hitheo: connection.hitheoBaseUrl,
55
+ groq: connection.groqBaseUrl,
56
+ novita: connection.novitaBaseUrl,
57
+ atlas: connection.atlasBaseUrl,
58
+ xai: connection.xaiBaseUrl,
55
59
  },
56
60
  realtime: {
57
61
  openai: `${connection.openaiRealtimeUrl}?model=<model>`,
@@ -418,6 +422,8 @@ export function registerTools(inputServer, client, config) {
418
422
  provider: z.string().max(64).optional(),
419
423
  model: z.string().max(200).optional(),
420
424
  status: z.number().int().min(100).max(599).optional(),
425
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
426
+ search: z.string().min(2).max(200).optional(),
421
427
  cursor: z.string().max(2048).optional(),
422
428
  limit: z.number().int().min(1).max(200).optional(),
423
429
  offset: z.number().int().min(0).optional(),
@@ -446,8 +452,11 @@ export function registerTools(inputServer, client, config) {
446
452
  server.registerTool('read_usage_spend', {
447
453
  title: 'Read project spend',
448
454
  description: 'Read spend versus configured caps for a project.',
449
- inputSchema: { projectId: z.string().uuid() },
450
- }, ({ projectId }) => run(() => client.getUsageSpend(projectId)));
455
+ inputSchema: {
456
+ projectId: z.string().uuid(),
457
+ gatewayId: z.string().uuid().optional(),
458
+ },
459
+ }, ({ projectId, gatewayId }) => run(() => client.getUsageSpend(projectId, gatewayId)));
451
460
  server.registerTool('read_usage_metrics', {
452
461
  title: 'Read project usage metrics',
453
462
  description: 'Read bucketed usage metrics and KPIs for a project.',
@@ -455,8 +464,13 @@ export function registerTools(inputServer, client, config) {
455
464
  projectId: z.string().uuid(),
456
465
  since: z.string().optional(),
457
466
  bucket: z.enum(['hour', 'day']).optional(),
467
+ gatewayId: z.string().uuid().optional(),
468
+ provider: z.string().max(64).optional(),
469
+ model: z.string().max(200).optional(),
470
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
471
+ search: z.string().min(2).max(200).optional(),
458
472
  },
459
- }, ({ projectId, since, bucket }) => run(() => client.getUsageMetrics(projectId, { since, bucket })));
473
+ }, ({ projectId, ...input }) => run(() => client.getUsageMetrics(projectId, input)));
460
474
  server.registerTool('get_connection_config', {
461
475
  title: 'Get connection config',
462
476
  description: 'Compose the copy-paste connection config for a gateway: the data-plane base URLs for the OpenAI SDK (/compat), OpenAI-native, and Claude Code (/anthropic). Pair with a token from create_gateway_token.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/mcp",
3
- "version": "0.4.0",
3
+ "version": "0.5.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,7 +37,7 @@
37
37
  "start": "node dist/index.js"
38
38
  },
39
39
  "dependencies": {
40
- "@airctrl/sdk": "0.4.0",
40
+ "@airctrl/sdk": "0.5.0",
41
41
  "@modelcontextprotocol/sdk": "1.32.1",
42
42
  "zod": "4.6.7"
43
43
  },