@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.
@@ -0,0 +1,69 @@
1
+ import WebSocket from 'ws';
2
+ import { parseConnectorInbound, } from './protocol.js';
3
+ const MAX_CHANNEL_MESSAGE_BYTES = 4 * 1024 * 1024;
4
+ export async function connectWebSocketChannel(input) {
5
+ return await new Promise((resolve, reject) => {
6
+ const socket = new WebSocket(input.url, {
7
+ headers: {
8
+ authorization: `Bearer ${input.token}`,
9
+ 'user-agent': input.userAgent ?? '@airctrl/mcp-connector/0.6.0',
10
+ },
11
+ handshakeTimeout: 10_000,
12
+ maxPayload: MAX_CHANNEL_MESSAGE_BYTES,
13
+ perMessageDeflate: false,
14
+ });
15
+ const onError = () => reject(new Error('connector_channel_connect_failed'));
16
+ socket.once('error', onError);
17
+ socket.once('open', () => {
18
+ socket.off('error', onError);
19
+ resolve(new WebSocketConnectorChannel(socket));
20
+ });
21
+ });
22
+ }
23
+ class WebSocketConnectorChannel {
24
+ socket;
25
+ closed;
26
+ handler;
27
+ earlyMessages = [];
28
+ constructor(socket) {
29
+ this.socket = socket;
30
+ this.closed = new Promise((resolve) => {
31
+ socket.once('close', (code, reason) => resolve({ code, reason: reason.toString('utf8') }));
32
+ });
33
+ socket.on('error', () => undefined);
34
+ socket.on('message', (data, isBinary) => {
35
+ if (isBinary) {
36
+ void this.close(1003, 'text_required');
37
+ return;
38
+ }
39
+ try {
40
+ const message = parseConnectorInbound(data.toString());
41
+ if (this.handler)
42
+ this.handler(message);
43
+ else
44
+ this.earlyMessages.push(message);
45
+ }
46
+ catch {
47
+ void this.close(1008, 'invalid_message');
48
+ }
49
+ });
50
+ }
51
+ onMessage(handler) {
52
+ this.handler = handler;
53
+ for (const message of this.earlyMessages.splice(0))
54
+ handler(message);
55
+ }
56
+ async send(message) {
57
+ if (this.socket.readyState !== WebSocket.OPEN)
58
+ throw new Error('connector_channel_closed');
59
+ await new Promise((resolve, reject) => {
60
+ this.socket.send(JSON.stringify(message), (error) => (error ? reject(error) : resolve()));
61
+ });
62
+ }
63
+ async close(code = 1000, reason = 'connector_shutdown') {
64
+ if (this.socket.readyState === WebSocket.CLOSED)
65
+ return;
66
+ this.socket.close(code, reason);
67
+ await this.closed;
68
+ }
69
+ }
@@ -0,0 +1,66 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { resolve } from 'node:path';
3
+ import { z } from 'zod';
4
+ const envName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
5
+ const localServer = z
6
+ .object({
7
+ ref: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
8
+ command: z.string().min(1).max(2048),
9
+ args: z.array(z.string().max(4096)).max(128).default([]),
10
+ env: z.array(envName).max(128).default([]),
11
+ cwd: z.string().min(1).max(4096).optional(),
12
+ })
13
+ .strict();
14
+ const localConfig = z
15
+ .object({
16
+ servers: z.array(localServer).min(1).max(100),
17
+ })
18
+ .strict()
19
+ .superRefine((value, context) => {
20
+ const seen = new Set();
21
+ for (const server of value.servers) {
22
+ if (seen.has(server.ref)) {
23
+ context.addIssue({
24
+ code: 'custom',
25
+ path: ['servers'],
26
+ message: 'connector_server_ref_duplicate',
27
+ });
28
+ }
29
+ seen.add(server.ref);
30
+ }
31
+ });
32
+ function present(value) {
33
+ if (!value?.trim())
34
+ throw new Error('connector_config_incomplete');
35
+ return value.trim();
36
+ }
37
+ function safeChannelUrl(raw) {
38
+ const url = new URL(raw);
39
+ const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '::1';
40
+ if (url.username ||
41
+ url.password ||
42
+ (url.protocol !== 'wss:' && !(local && url.protocol === 'ws:'))) {
43
+ throw new Error('connector_channel_url_invalid');
44
+ }
45
+ return url;
46
+ }
47
+ export async function loadConnectorConfig(env = process.env) {
48
+ const connectorId = present(env.AIRCTRL_MCP_CONNECTOR_ID);
49
+ if (!z.string().uuid().safeParse(connectorId).success)
50
+ throw new Error('connector_id_invalid');
51
+ const token = present(env.AIRCTRL_MCP_CONNECTOR_TOKEN);
52
+ if (token.length < 24)
53
+ throw new Error('connector_token_invalid');
54
+ const channelUrl = safeChannelUrl(present(env.AIRCTRL_MCP_CONNECTOR_URL));
55
+ const configPath = resolve(present(env.AIRCTRL_MCP_CONNECTOR_SERVERS_FILE));
56
+ const parsed = localConfig.parse(JSON.parse(await readFile(configPath, 'utf8')));
57
+ return { connectorId, channelUrl, token, servers: parsed.servers };
58
+ }
59
+ export function connectorStatus(config) {
60
+ return {
61
+ connectorId: config.connectorId,
62
+ channelOrigin: config.channelUrl.origin,
63
+ serverRefs: config.servers.map((server) => server.ref),
64
+ tokenConfigured: true,
65
+ };
66
+ }
@@ -0,0 +1,84 @@
1
+ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
2
+ import { getDefaultEnvironment, StdioClientTransport, } from '@modelcontextprotocol/sdk/client/stdio.js';
3
+ export class StdioLocalServerRegistry {
4
+ logger;
5
+ env;
6
+ definitions;
7
+ running = new Map();
8
+ constructor(definitions, logger, env = process.env) {
9
+ this.logger = logger;
10
+ this.env = env;
11
+ this.definitions = new Map(definitions.map((definition) => [definition.ref, definition]));
12
+ }
13
+ serverRefs() {
14
+ return [...this.definitions.keys()].sort();
15
+ }
16
+ async execute(serverRef, operation, params, signal) {
17
+ const { client } = await this.get(serverRef);
18
+ if (operation === 'ping')
19
+ return await client.ping({ signal });
20
+ if (operation === 'tools/list') {
21
+ return await client.listTools(params?.cursor ? { cursor: String(params.cursor) } : undefined, { signal });
22
+ }
23
+ const name = typeof params?.name === 'string' ? params.name : '';
24
+ if (!name)
25
+ throw new Error('connector_tool_name_required');
26
+ const args = params?.arguments;
27
+ if (args !== undefined && (args === null || typeof args !== 'object' || Array.isArray(args))) {
28
+ throw new Error('connector_tool_arguments_invalid');
29
+ }
30
+ return await client.callTool({ name, arguments: args }, undefined, { signal });
31
+ }
32
+ async closeAll() {
33
+ const running = await Promise.allSettled(this.running.values());
34
+ this.running.clear();
35
+ await Promise.allSettled(running.flatMap((result) => result.status === 'fulfilled'
36
+ ? [result.value.client.close(), result.value.transport.close()]
37
+ : []));
38
+ }
39
+ async get(serverRef) {
40
+ const definition = this.definitions.get(serverRef);
41
+ if (!definition)
42
+ throw new Error('connector_server_not_found');
43
+ let running = this.running.get(serverRef);
44
+ if (!running) {
45
+ running = this.start(definition);
46
+ this.running.set(serverRef, running);
47
+ running.catch(() => this.running.delete(serverRef));
48
+ }
49
+ return await running;
50
+ }
51
+ async start(definition) {
52
+ const childEnv = getDefaultEnvironment();
53
+ for (const name of definition.env) {
54
+ const value = this.env[name];
55
+ if (value === undefined)
56
+ throw new Error('connector_server_env_missing');
57
+ childEnv[name] = value;
58
+ }
59
+ const transport = new StdioClientTransport({
60
+ command: definition.command,
61
+ args: definition.args,
62
+ env: childEnv,
63
+ cwd: definition.cwd,
64
+ stderr: 'pipe',
65
+ maxBufferSize: 10 * 1024 * 1024,
66
+ });
67
+ transport.stderr?.on('data', (chunk) => {
68
+ this.logger.event('warn', 'connector_local_server_stderr', {
69
+ serverRef: definition.ref,
70
+ bytes: Buffer.byteLength(chunk),
71
+ });
72
+ });
73
+ const client = new Client({ name: 'airctrl-connector', version: '0.6.0' });
74
+ try {
75
+ await client.connect(transport);
76
+ this.logger.event('info', 'connector_local_server_ready', { serverRef: definition.ref });
77
+ return { client, transport };
78
+ }
79
+ catch {
80
+ await transport.close().catch(() => undefined);
81
+ throw new Error('connector_server_start_failed');
82
+ }
83
+ }
84
+ }
@@ -0,0 +1,26 @@
1
+ import { connectWebSocketChannel } from './channel.js';
2
+ import { loadConnectorConfig } from './config.js';
3
+ import { StdioLocalServerRegistry } from './local-servers.js';
4
+ import { ConnectorRuntime } from './runtime.js';
5
+ const logger = {
6
+ event(level, event, meta) {
7
+ const serialized = JSON.stringify({ level, event, ...(meta ? { meta } : {}) });
8
+ (level === 'info' ? console.error : level === 'warn' ? console.warn : console.error)(serialized);
9
+ },
10
+ };
11
+ export async function runConnector() {
12
+ const config = await loadConnectorConfig();
13
+ const registry = new StdioLocalServerRegistry(config.servers, logger);
14
+ const runtime = new ConnectorRuntime(config, () => connectWebSocketChannel({ url: config.channelUrl, token: config.token }), registry, { logger });
15
+ const controller = new AbortController();
16
+ const shutdown = () => controller.abort(new Error('connector_shutdown'));
17
+ process.once('SIGINT', shutdown);
18
+ process.once('SIGTERM', shutdown);
19
+ try {
20
+ await runtime.run(controller.signal);
21
+ }
22
+ finally {
23
+ process.off('SIGINT', shutdown);
24
+ process.off('SIGTERM', shutdown);
25
+ }
26
+ }
@@ -0,0 +1,21 @@
1
+ import { z } from 'zod';
2
+ const id = z.string().min(1).max(255);
3
+ export const ConnectorOperationSchema = z.enum(['ping', 'tools/list', 'tools/call']);
4
+ export const ConnectorInboundSchema = z.discriminatedUnion('type', [
5
+ z
6
+ .object({
7
+ type: z.literal('request'),
8
+ requestId: id,
9
+ clientId: id,
10
+ serverRef: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
11
+ operation: ConnectorOperationSchema,
12
+ params: z.record(z.string(), z.unknown()).optional(),
13
+ })
14
+ .strict(),
15
+ z.object({ type: z.literal('cancel'), requestId: id }).strict(),
16
+ z.object({ type: z.literal('ping'), nonce: id }).strict(),
17
+ z.object({ type: z.literal('auth_revoked') }).strict(),
18
+ ]);
19
+ export function parseConnectorInbound(raw) {
20
+ return ConnectorInboundSchema.parse(JSON.parse(raw));
21
+ }
@@ -0,0 +1,182 @@
1
+ const AUTH_REVOKED_CLOSE_CODE = 4003;
2
+ const DEFAULT_HEARTBEAT_MS = 15_000;
3
+ const DEFAULT_MAX_CONCURRENT = 100;
4
+ const defaultLogger = {
5
+ event(level, event, meta) {
6
+ const line = JSON.stringify({ level, event, ...(meta ? { meta } : {}) });
7
+ (level === 'error' ? console.error : level === 'warn' ? console.warn : console.error)(line);
8
+ },
9
+ };
10
+ export class ConnectorRuntime {
11
+ config;
12
+ channelFactory;
13
+ registry;
14
+ logger;
15
+ heartbeatMs;
16
+ maxConcurrent;
17
+ delay;
18
+ channel;
19
+ revoked = false;
20
+ pending = new Map();
21
+ constructor(config, channelFactory, registry, options = {}) {
22
+ this.config = config;
23
+ this.channelFactory = channelFactory;
24
+ this.registry = registry;
25
+ this.logger = options.logger ?? defaultLogger;
26
+ this.heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
27
+ this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
28
+ this.delay = options.delay ?? abortableDelay;
29
+ }
30
+ async run(signal) {
31
+ let attempt = 0;
32
+ try {
33
+ while (!signal.aborted && !this.revoked) {
34
+ try {
35
+ this.channel = await this.channelFactory();
36
+ }
37
+ catch {
38
+ this.logger.event('warn', 'connector_channel_connect_failed', { attempt });
39
+ await this.delay(reconnectDelay(attempt++), signal).catch(() => undefined);
40
+ continue;
41
+ }
42
+ attempt = 0;
43
+ const channel = this.channel;
44
+ channel.onMessage((message) => {
45
+ void this.handle(message, channel);
46
+ });
47
+ await channel.send({
48
+ type: 'hello',
49
+ connectorId: this.config.connectorId,
50
+ version: '0.6.0',
51
+ serverRefs: this.registry.serverRefs(),
52
+ capabilities: { tools: true, cancellation: true, multipleClients: true },
53
+ });
54
+ this.logger.event('info', 'connector_channel_ready', {
55
+ connectorId: this.config.connectorId,
56
+ });
57
+ const timer = setInterval(() => {
58
+ void channel
59
+ .send({
60
+ type: 'heartbeat',
61
+ connectorId: this.config.connectorId,
62
+ sentAt: new Date().toISOString(),
63
+ })
64
+ .catch(() => undefined);
65
+ }, this.heartbeatMs);
66
+ let closed;
67
+ try {
68
+ closed = await Promise.race([channel.closed, aborted(signal)]);
69
+ }
70
+ finally {
71
+ clearInterval(timer);
72
+ }
73
+ if (closed.code === AUTH_REVOKED_CLOSE_CODE)
74
+ this.revoked = true;
75
+ if (!signal.aborted && !this.revoked) {
76
+ this.logger.event('warn', 'connector_channel_disconnected', { code: closed.code });
77
+ await this.delay(reconnectDelay(attempt++), signal).catch(() => undefined);
78
+ }
79
+ }
80
+ }
81
+ finally {
82
+ for (const pending of this.pending.values())
83
+ pending.controller.abort();
84
+ this.pending.clear();
85
+ await this.channel?.close().catch(() => undefined);
86
+ await this.registry.closeAll();
87
+ this.logger.event('info', 'connector_shutdown_complete', {
88
+ connectorId: this.config.connectorId,
89
+ });
90
+ }
91
+ return this.revoked ? 'revoked' : 'stopped';
92
+ }
93
+ async handle(message, channel) {
94
+ if (message.type === 'auth_revoked') {
95
+ this.revoked = true;
96
+ await channel.close(AUTH_REVOKED_CLOSE_CODE, 'auth_revoked');
97
+ return;
98
+ }
99
+ if (message.type === 'ping') {
100
+ await channel.send({ type: 'pong', nonce: message.nonce });
101
+ return;
102
+ }
103
+ if (message.type === 'cancel') {
104
+ this.pending.get(message.requestId)?.controller.abort();
105
+ return;
106
+ }
107
+ if (this.pending.has(message.requestId)) {
108
+ await channel.send({
109
+ type: 'response',
110
+ requestId: message.requestId,
111
+ clientId: message.clientId,
112
+ error: { code: 'connector_duplicate_request' },
113
+ });
114
+ return;
115
+ }
116
+ if (this.pending.size >= this.maxConcurrent) {
117
+ await channel.send({
118
+ type: 'response',
119
+ requestId: message.requestId,
120
+ clientId: message.clientId,
121
+ error: { code: 'connector_busy' },
122
+ });
123
+ return;
124
+ }
125
+ const controller = new AbortController();
126
+ this.pending.set(message.requestId, { clientId: message.clientId, controller });
127
+ try {
128
+ const result = await this.registry.execute(message.serverRef, message.operation, message.params, controller.signal);
129
+ await channel.send({
130
+ type: 'response',
131
+ requestId: message.requestId,
132
+ clientId: message.clientId,
133
+ result,
134
+ });
135
+ }
136
+ catch (error) {
137
+ const code = controller.signal.aborted
138
+ ? 'connector_request_cancelled'
139
+ : safeConnectorError(error);
140
+ await channel
141
+ .send({
142
+ type: 'response',
143
+ requestId: message.requestId,
144
+ clientId: message.clientId,
145
+ error: { code },
146
+ })
147
+ .catch(() => undefined);
148
+ this.logger.event('warn', 'connector_request_failed', {
149
+ requestId: message.requestId,
150
+ serverRef: message.serverRef,
151
+ });
152
+ }
153
+ finally {
154
+ this.pending.delete(message.requestId);
155
+ }
156
+ }
157
+ }
158
+ function safeConnectorError(error) {
159
+ const code = error instanceof Error ? error.message : '';
160
+ return /^connector_[a-z0-9_]+$/.test(code) ? code : 'connector_request_failed';
161
+ }
162
+ function reconnectDelay(attempt) {
163
+ return Math.min(30_000, Math.round(1000 * 1.5 ** Math.min(attempt, 20)));
164
+ }
165
+ async function abortableDelay(milliseconds, signal) {
166
+ if (signal.aborted)
167
+ throw signal.reason;
168
+ await new Promise((resolve, reject) => {
169
+ const timer = setTimeout(resolve, milliseconds);
170
+ signal.addEventListener('abort', () => {
171
+ clearTimeout(timer);
172
+ reject(signal.reason);
173
+ }, { once: true });
174
+ });
175
+ }
176
+ async function aborted(signal) {
177
+ if (signal.aborted)
178
+ return { code: 1000, reason: 'connector_shutdown' };
179
+ return await new Promise((resolve) => signal.addEventListener('abort', () => resolve({ code: 1000, reason: 'connector_shutdown' }), {
180
+ once: true,
181
+ }));
182
+ }
package/dist/index.js CHANGED
@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
4
4
  import { createClient } from '@airctrl/sdk';
5
5
  import { createMcpClientOptions, loadConfig, mcpStatus } from './config.js';
6
6
  import { registerTools } from './tools.js';
7
+ import { runConnector } from './connector/main.js';
7
8
  /**
8
9
  * AIRCTRL MCP server (Fase 2, P2-1). Expone el gateway a agentes MCP-compatibles
9
10
  * (Claude Code, Cursor, …) sobre **stdio**. Corre **local/self-hosted** (D-P2.3):
@@ -12,21 +13,29 @@ import { registerTools } from './tools.js';
12
13
  * entregan el plaintext descifrado al caller. Los tools de gestión (create_gateway, add_provider_key, …)
13
14
  * se registran en S2.3 sobre el HTTP client (S2.2).
14
15
  */
15
- const config = loadConfig();
16
- const client = createClient(createMcpClientOptions(config));
17
- const server = new McpServer({ name: 'airctrl', version: '0.4.0' });
18
- registerTools(server, client, config);
19
- server.registerTool('airctrl_status', {
20
- title: 'AIRCTRL MCP status',
21
- description: 'Report the AIRCTRL API URL and whether MCP runs as a human or Service Account. Never returns credential values.',
22
- inputSchema: {},
23
- }, () => ({
24
- content: [
25
- {
26
- type: 'text',
27
- text: JSON.stringify(mcpStatus(config), null, 2),
28
- },
29
- ],
30
- }));
31
- const transport = new StdioServerTransport();
32
- await server.connect(transport);
16
+ if (process.argv[2] === 'connector') {
17
+ await runConnector();
18
+ }
19
+ else {
20
+ await runLocalMcpServer();
21
+ }
22
+ async function runLocalMcpServer() {
23
+ const config = loadConfig();
24
+ const client = createClient(createMcpClientOptions(config));
25
+ const server = new McpServer({ name: 'airctrl', version: '0.6.0' });
26
+ registerTools(server, client, config);
27
+ server.registerTool('airctrl_status', {
28
+ title: 'AIRCTRL MCP status',
29
+ description: 'Report the AIRCTRL API URL and whether MCP runs as a human or Service Account. Never returns credential values.',
30
+ inputSchema: {},
31
+ }, () => ({
32
+ content: [
33
+ {
34
+ type: 'text',
35
+ text: JSON.stringify(mcpStatus(config), null, 2),
36
+ },
37
+ ],
38
+ }));
39
+ const transport = new StdioServerTransport();
40
+ await server.connect(transport);
41
+ }