@airctrl/mcp 0.4.0 → 0.6.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/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>`,
@@ -149,6 +153,19 @@ export const SERVICE_ACCOUNT_MCP_TOOLS = [
149
153
  'read_usage',
150
154
  'read_gateway_log',
151
155
  'read_gateway_key_access',
156
+ 'list_mcp_gateways',
157
+ 'get_mcp_gateway',
158
+ 'list_mcp_server_catalog',
159
+ 'list_mcp_servers',
160
+ 'list_mcp_tools',
161
+ 'list_mcp_clients',
162
+ 'list_mcp_policies',
163
+ 'list_mcp_calls',
164
+ 'get_mcp_server_health',
165
+ 'list_mcp_client_keys',
166
+ 'list_mcp_grants',
167
+ 'get_mcp_call_metrics',
168
+ 'export_mcp_calls_csv',
152
169
  'list_records',
153
170
  'get_secret',
154
171
  'read_record',
@@ -289,6 +306,140 @@ export function registerTools(inputServer, client, config) {
289
306
  description: 'List the gateways in a project.',
290
307
  inputSchema: { projectId: z.string().uuid() },
291
308
  }, ({ projectId }) => run(() => client.listGateways(projectId)));
309
+ const mcpGateways = new Proxy({}, {
310
+ get: (_target, property) => (...args) => {
311
+ const method = client.mcpGateways()[property];
312
+ return method(...args);
313
+ },
314
+ });
315
+ server.registerTool('list_mcp_gateways', {
316
+ title: 'List MCP gateways', description: 'List governed MCP gateways in one project.',
317
+ inputSchema: { projectId: z.string().uuid() },
318
+ }, ({ projectId }) => run(() => mcpGateways.list(projectId)));
319
+ server.registerTool('get_mcp_gateway', {
320
+ title: 'Get MCP gateway', description: 'Read one MCP gateway with its real server and client inventory.',
321
+ inputSchema: { gatewayId: z.string().uuid() },
322
+ }, ({ gatewayId }) => run(() => mcpGateways.get(gatewayId)));
323
+ server.registerTool('list_mcp_server_catalog', {
324
+ title: 'List MCP server catalog', description: 'List curated MCP server recipes and their official source metadata.', inputSchema: {},
325
+ }, () => run(() => mcpGateways.catalog()));
326
+ server.registerTool('list_mcp_servers', {
327
+ title: 'List MCP servers', description: 'List servers connected to one MCP gateway.', inputSchema: { gatewayId: z.string().uuid() },
328
+ }, ({ gatewayId }) => run(() => mcpGateways.listServers(gatewayId)));
329
+ server.registerTool('list_mcp_tools', {
330
+ title: 'List MCP tools', description: 'List synchronized, namespaced tools exposed by one MCP gateway.', inputSchema: { gatewayId: z.string().uuid() },
331
+ }, ({ gatewayId }) => run(() => mcpGateways.listTools(gatewayId)));
332
+ server.registerTool('list_mcp_clients', {
333
+ title: 'List MCP clients', description: 'List registered client identities. Secrets are never returned.', inputSchema: { gatewayId: z.string().uuid() },
334
+ }, ({ gatewayId }) => run(() => mcpGateways.listClients(gatewayId)));
335
+ server.registerTool('list_mcp_policies', {
336
+ title: 'List MCP policies', description: 'List tool rules configured on one MCP gateway.', inputSchema: { gatewayId: z.string().uuid() },
337
+ }, ({ gatewayId }) => run(() => mcpGateways.listPolicies(gatewayId)));
338
+ server.registerTool('list_mcp_calls', {
339
+ title: 'List MCP call evidence', description: 'List bounded tool-call metadata; retained payload bodies are not included.',
340
+ inputSchema: { gatewayId: z.string().uuid(), since: z.string().datetime().optional(), until: z.string().datetime().optional(), tool: z.string().optional(), outcome: z.enum(['succeeded', 'blocked', 'failed', 'cancelled', 'timed_out']).optional(), limit: z.number().int().min(1).max(200).optional() },
341
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.listCalls(gatewayId, input)));
342
+ server.registerTool('create_mcp_gateway', {
343
+ title: 'Create MCP gateway', description: 'Create a governed MCP gateway in a project.',
344
+ inputSchema: { projectId: z.string().uuid(), name: z.string().min(1).max(100), slug: z.string().max(64).optional() },
345
+ }, (input) => run(() => mcpGateways.create(input)));
346
+ server.registerTool('create_mcp_server', {
347
+ title: 'Add MCP server', description: 'Connect a remote, legacy SSE or connector-backed MCP server to a gateway.',
348
+ inputSchema: { gatewayId: z.string().uuid(), name: z.string().min(1), namespace: z.string().min(1).max(63), transport: z.enum(['streamable_http', 'sse', 'stdio']), endpointUrl: z.string().url().optional(), catalogSlug: z.string().optional(), authMode: z.enum(['none', 'bearer', 'custom_headers', 'connector_record']), authSecretEnv: z.string().optional() },
349
+ }, ({ gatewayId, authSecretEnv, ...input }) => run(() => mcpGateways.createServer(gatewayId, { ...input, authSecret: authSecretEnv ? resolveProviderKeyEnv(authSecretEnv) : undefined })));
350
+ server.registerTool('sync_mcp_server', {
351
+ title: 'Synchronize MCP server tools', description: 'Fetch the current tool inventory from one connected server.',
352
+ inputSchema: { gatewayId: z.string().uuid(), serverId: z.string().uuid() },
353
+ }, ({ gatewayId, serverId }) => run(() => mcpGateways.syncServer(gatewayId, serverId)));
354
+ server.registerTool('create_mcp_client', {
355
+ title: 'Create MCP client', description: 'Register a named MCP client identity. Create its scoped key separately.',
356
+ inputSchema: { gatewayId: z.string().uuid(), name: z.string().min(1), clientType: z.literal('api_key') },
357
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.createClient(gatewayId, input)));
358
+ server.registerTool('create_mcp_client_key', {
359
+ title: 'Create MCP client key', description: 'Create a scoped key. Its plaintext is returned once and must be stored securely.',
360
+ inputSchema: { gatewayId: z.string().uuid(), clientId: z.string().uuid(), scopes: z.array(z.enum(['mcp:connect', 'mcp:read', 'mcp:call', 'mcp:admin'])).optional(), serverIds: z.array(z.string().uuid()).optional() },
361
+ }, ({ gatewayId, clientId, ...input }) => run(() => mcpGateways.createKey(gatewayId, clientId, input)));
362
+ server.registerTool('create_mcp_policy', {
363
+ title: 'Create MCP tool policy', description: 'Add an allow, block or ask-first rule to one MCP gateway.',
364
+ inputSchema: { gatewayId: z.string().uuid(), name: z.string().min(1), serverId: z.string().uuid().optional(), toolPattern: z.string().min(1), effect: z.enum(['allow', 'block', 'ask_first']), accessMode: z.enum(['full', 'read_only']), priority: z.number().int().optional() },
365
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.createPolicy(gatewayId, input)));
366
+ server.registerTool('export_mcp_policy', {
367
+ title: 'Export MCP policy as code', description: 'Export the canonical YAML policy document for review or version control.', inputSchema: { gatewayId: z.string().uuid() },
368
+ }, ({ gatewayId }) => run(() => mcpGateways.exportPolicy(gatewayId)));
369
+ server.registerTool('preview_mcp_policy', {
370
+ title: 'Preview MCP policy changes', description: 'Validate YAML and preview its diff without applying it.',
371
+ inputSchema: { gatewayId: z.string().uuid(), yaml: z.string().min(1), prune: z.boolean().optional() },
372
+ }, ({ gatewayId, yaml, prune }) => run(() => mcpGateways.importPolicy(gatewayId, { yaml, apply: false, prune: prune ?? false, confirmed: false })));
373
+ server.registerTool('update_mcp_gateway', {
374
+ title: 'Update MCP gateway', description: 'Update the name or active state of one MCP gateway.',
375
+ inputSchema: { gatewayId: z.string().uuid(), name: z.string().min(1).optional(), isActive: z.boolean().optional() },
376
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.update(gatewayId, input)));
377
+ server.registerTool('update_mcp_runtime', {
378
+ title: 'Update MCP runtime limits', description: 'Update discovery mode, bounded timeout, response, concurrency, rate and optional IP allowlist settings.',
379
+ inputSchema: { gatewayId: z.string().uuid(), toolDiscoveryMode: z.enum(['progressive', 'eager']).optional(), requestTimeoutMs: z.number().int().min(1000).max(60000).optional(), maxResultBytes: z.number().int().min(65536).max(10485760).optional(), maxConcurrentCalls: z.number().int().min(1).max(32).optional(), rateLimitPerMin: z.number().int().min(1).nullable().optional(), ipAllowlist: z.array(z.string()).max(64).optional() },
380
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.updateRuntime(gatewayId, input)));
381
+ server.registerTool('delete_mcp_gateway', {
382
+ title: 'Delete MCP gateway', description: 'Permanently delete one MCP gateway. Requires explicit confirmation.',
383
+ inputSchema: { gatewayId: z.string().uuid(), confirm: z.literal(true) },
384
+ }, ({ gatewayId }) => run(() => mcpGateways.remove(gatewayId)));
385
+ server.registerTool('update_mcp_server', {
386
+ title: 'Update MCP server', description: 'Update one connected MCP server.',
387
+ inputSchema: { gatewayId: z.string().uuid(), serverId: z.string().uuid(), name: z.string().min(1).optional(), endpointUrl: z.string().url().optional(), enabled: z.boolean().optional() },
388
+ }, ({ gatewayId, serverId, ...input }) => run(() => mcpGateways.updateServer(gatewayId, serverId, input)));
389
+ server.registerTool('delete_mcp_server', {
390
+ title: 'Remove MCP server', description: 'Remove one server and its synchronized tool inventory. Requires explicit confirmation.',
391
+ inputSchema: { gatewayId: z.string().uuid(), serverId: z.string().uuid(), confirm: z.literal(true) },
392
+ }, ({ gatewayId, serverId }) => run(() => mcpGateways.removeServer(gatewayId, serverId)));
393
+ server.registerTool('get_mcp_server_health', {
394
+ title: 'Get MCP server health', description: 'Read synchronization and connector health for one MCP server.',
395
+ inputSchema: { gatewayId: z.string().uuid(), serverId: z.string().uuid() },
396
+ }, ({ gatewayId, serverId }) => run(() => mcpGateways.serverHealth(gatewayId, serverId)));
397
+ server.registerTool('update_mcp_client', {
398
+ title: 'Update MCP client', description: 'Rename one MCP client identity.',
399
+ inputSchema: { gatewayId: z.string().uuid(), clientId: z.string().uuid(), name: z.string().min(1) },
400
+ }, ({ gatewayId, clientId, name }) => run(() => mcpGateways.updateClient(gatewayId, clientId, { name })));
401
+ server.registerTool('revoke_mcp_client', {
402
+ title: 'Revoke MCP client', description: 'Revoke one client and all of its keys. Requires explicit confirmation.',
403
+ inputSchema: { gatewayId: z.string().uuid(), clientId: z.string().uuid(), confirm: z.literal(true) },
404
+ }, ({ gatewayId, clientId }) => run(() => mcpGateways.revokeClient(gatewayId, clientId)));
405
+ server.registerTool('list_mcp_client_keys', {
406
+ title: 'List MCP client keys', description: 'List safe key metadata for one MCP client.',
407
+ inputSchema: { gatewayId: z.string().uuid(), clientId: z.string().uuid() },
408
+ }, ({ gatewayId, clientId }) => run(() => mcpGateways.listKeys(gatewayId, clientId)));
409
+ server.registerTool('revoke_mcp_client_key', {
410
+ title: 'Revoke MCP client key', description: 'Revoke one client key. Requires explicit confirmation.',
411
+ inputSchema: { gatewayId: z.string().uuid(), clientId: z.string().uuid(), keyId: z.string().uuid(), confirm: z.literal(true) },
412
+ }, ({ gatewayId, clientId, keyId }) => run(() => mcpGateways.revokeKey(gatewayId, clientId, keyId)));
413
+ server.registerTool('delete_mcp_policy', {
414
+ title: 'Delete MCP policy', description: 'Delete one tool policy. Requires explicit confirmation.',
415
+ inputSchema: { gatewayId: z.string().uuid(), policyId: z.string().uuid(), confirm: z.literal(true) },
416
+ }, ({ gatewayId, policyId }) => run(() => mcpGateways.removePolicy(gatewayId, policyId)));
417
+ server.registerTool('list_mcp_grants', {
418
+ title: 'List MCP grants', description: 'List direct user, service-account, group and role grants.', inputSchema: { gatewayId: z.string().uuid() },
419
+ }, ({ gatewayId }) => run(() => mcpGateways.listGrants(gatewayId)));
420
+ server.registerTool('create_mcp_grant', {
421
+ title: 'Create MCP grant', description: 'Grant full or read-only gateway access to an existing AIRCTRL principal.',
422
+ inputSchema: { gatewayId: z.string().uuid(), subjectType: z.enum(['user', 'service_account', 'group', 'role']), subjectId: z.string().uuid(), accessMode: z.enum(['full', 'read_only']) },
423
+ }, ({ gatewayId, ...input }) => run(() => mcpGateways.createGrant(gatewayId, input)));
424
+ server.registerTool('revoke_mcp_grant', {
425
+ title: 'Revoke MCP grant', description: 'Revoke one MCP grant. Requires explicit confirmation.',
426
+ inputSchema: { gatewayId: z.string().uuid(), grantId: z.string().uuid(), confirm: z.literal(true) },
427
+ }, ({ gatewayId, grantId }) => run(() => mcpGateways.revokeGrant(gatewayId, grantId)));
428
+ server.registerTool('apply_mcp_policy', {
429
+ title: 'Apply MCP policy as code', description: 'Apply a reviewed YAML policy document. Requires explicit confirmation.',
430
+ inputSchema: { gatewayId: z.string().uuid(), yaml: z.string().min(1), prune: z.boolean().optional(), confirm: z.literal(true) },
431
+ }, ({ gatewayId, yaml, prune }) => run(() => mcpGateways.importPolicy(gatewayId, { yaml, apply: true, prune: prune ?? false, confirmed: true })));
432
+ server.registerTool('get_mcp_call_metrics', {
433
+ title: 'Get MCP call metrics', description: 'Read call totals, outcomes and average latency.', inputSchema: { gatewayId: z.string().uuid() },
434
+ }, ({ gatewayId }) => run(() => mcpGateways.callMetrics(gatewayId)));
435
+ server.registerTool('get_mcp_call_payload', {
436
+ title: 'Get retained MCP call payload', description: 'Read one authorized encrypted payload record when body retention was enabled.',
437
+ inputSchema: { gatewayId: z.string().uuid(), callId: z.string().uuid() },
438
+ }, ({ gatewayId, callId }) => run(() => mcpGateways.callPayload(gatewayId, callId)));
439
+ server.registerTool('export_mcp_calls_csv', {
440
+ title: 'Export MCP call evidence', description: 'Export a bounded CSV of MCP call metadata.',
441
+ inputSchema: { gatewayId: z.string().uuid(), since: z.string().datetime().optional(), until: z.string().datetime().optional(), serverId: z.string().uuid().optional(), tool: z.string().optional(), outcome: z.enum(['succeeded', 'blocked', 'failed', 'cancelled', 'timed_out']).optional() },
442
+ }, ({ gatewayId, ...filters }) => run(() => mcpGateways.callsCsv(gatewayId, filters)));
292
443
  server.registerTool('create_gateway', {
293
444
  title: 'Create gateway',
294
445
  description: 'Create an empty gateway in a project. Use this only when you need a bare gateway; if the user is connecting a provider key, prefer ' +
@@ -415,9 +566,12 @@ export function registerTools(inputServer, client, config) {
415
566
  inputSchema: {
416
567
  gatewayId: z.string().uuid(),
417
568
  since: z.string().optional(),
569
+ until: z.string().optional(),
418
570
  provider: z.string().max(64).optional(),
419
571
  model: z.string().max(200).optional(),
420
572
  status: z.number().int().min(100).max(599).optional(),
573
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
574
+ search: z.string().min(2).max(200).optional(),
421
575
  cursor: z.string().max(2048).optional(),
422
576
  limit: z.number().int().min(1).max(200).optional(),
423
577
  offset: z.number().int().min(0).optional(),
@@ -429,6 +583,7 @@ export function registerTools(inputServer, client, config) {
429
583
  inputSchema: {
430
584
  projectId: z.string().uuid(),
431
585
  since: z.string().optional(),
586
+ until: z.string().optional(),
432
587
  provider: z.string().max(64).optional(),
433
588
  model: z.string().max(200).optional(),
434
589
  status: z.number().int().min(100).max(599).optional(),
@@ -446,17 +601,26 @@ export function registerTools(inputServer, client, config) {
446
601
  server.registerTool('read_usage_spend', {
447
602
  title: 'Read project spend',
448
603
  description: 'Read spend versus configured caps for a project.',
449
- inputSchema: { projectId: z.string().uuid() },
450
- }, ({ projectId }) => run(() => client.getUsageSpend(projectId)));
604
+ inputSchema: {
605
+ projectId: z.string().uuid(),
606
+ gatewayId: z.string().uuid().optional(),
607
+ },
608
+ }, ({ projectId, gatewayId }) => run(() => client.getUsageSpend(projectId, gatewayId)));
451
609
  server.registerTool('read_usage_metrics', {
452
610
  title: 'Read project usage metrics',
453
611
  description: 'Read bucketed usage metrics and KPIs for a project.',
454
612
  inputSchema: {
455
613
  projectId: z.string().uuid(),
456
614
  since: z.string().optional(),
615
+ until: z.string().optional(),
457
616
  bucket: z.enum(['hour', 'day']).optional(),
617
+ gatewayId: z.string().uuid().optional(),
618
+ provider: z.string().max(64).optional(),
619
+ model: z.string().max(200).optional(),
620
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
621
+ search: z.string().min(2).max(200).optional(),
458
622
  },
459
- }, ({ projectId, since, bucket }) => run(() => client.getUsageMetrics(projectId, { since, bucket })));
623
+ }, ({ projectId, ...input }) => run(() => client.getUsageMetrics(projectId, input)));
460
624
  server.registerTool('get_connection_config', {
461
625
  title: 'Get connection config',
462
626
  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.',
@@ -670,11 +834,12 @@ export function registerTools(inputServer, client, config) {
670
834
  gatewayId: z.string().uuid(),
671
835
  outcome: z.enum(['granted', 'denied', 'error']).optional(),
672
836
  since: z.string().optional(),
837
+ until: z.string().optional(),
673
838
  cursor: z.string().max(4096).optional(),
674
839
  limit: z.number().int().min(1).max(200).optional(),
675
840
  offset: z.number().int().min(0).optional(),
676
841
  },
677
- }, ({ gatewayId, outcome, since, cursor, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, cursor, limit, offset })));
842
+ }, ({ gatewayId, outcome, since, until, cursor, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, until, cursor, limit, offset })));
678
843
  server.registerTool('list_provider_credentials', {
679
844
  title: 'List provider credentials',
680
845
  description: 'List provider credential metadata for an account. Secret values are never returned.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/mcp",
3
- "version": "0.4.0",
3
+ "version": "0.6.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,11 +37,13 @@
37
37
  "start": "node dist/index.js"
38
38
  },
39
39
  "dependencies": {
40
- "@airctrl/sdk": "0.4.0",
40
+ "@airctrl/sdk": "0.6.0",
41
41
  "@modelcontextprotocol/sdk": "1.32.1",
42
+ "ws": "8.21.3",
42
43
  "zod": "4.6.7"
43
44
  },
44
45
  "devDependencies": {
45
- "@types/node": "22.20.0"
46
+ "@types/node": "22.20.0",
47
+ "@types/ws": "8.18.1"
46
48
  }
47
49
  }