@ulexid/mcp-server 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @ulexid/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version `0.1.1` — [Ulexid Documentation](https://docs.ulexid.com)
+
+Stdio MCP proxy connecting AI coding agents to the hosted [Ulexid](https://www.ulexid.com) control plane (`https://ulexid.com/mcp`).
+
+```bash
+npx @ulexid/mcp-server
+```
+
+## License
+
+Proprietary (`UNLICENSED`). Copyright (c) Ulexid. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+export declare const ENVIRONMENT_ISSUERS: {
+    readonly prod: "https://ulexid.com";
+    readonly stage: "https://stage.ulexid.com";
+    readonly dev: "https://dev.ulexid.com";
+};
+export type UlexEnvironment = keyof typeof ENVIRONMENT_ISSUERS;
+export interface ResolveEndpointOptions {
+    readonly url?: string;
+    readonly baseUrl?: string;
+    readonly env?: string;
+}
+export interface UlexMcpProxyClientOptions {
+    readonly endpoint: string;
+    readonly apiKey?: string;
+    readonly fetchFn?: typeof fetch;
+}
+export interface JsonRpcTransportResult {
+    readonly status: number;
+    readonly json?: unknown;
+}
+export interface StdioProxyOptions extends ResolveEndpointOptions {
+    readonly endpoint?: string;
+    readonly apiKey?: string;
+    readonly stdin?: NodeJS.ReadableStream;
+    readonly stdout?: NodeJS.WritableStream;
+    readonly stderr?: NodeJS.WritableStream;
+    readonly fetchFn?: typeof fetch;
+}
+export interface ProxyCliArgs {
+    readonly url?: string;
+    readonly env?: string;
+    readonly apiKey?: string;
+    readonly help: boolean;
+}
+/**
+ * Resolve the target hosted MCP endpoint URL from explicit flags or environment
+ * variables, defaulting to production (`https://ulexid.com/mcp`).
+ */
+export declare function resolveMcpEndpoint(options?: ResolveEndpointOptions): string;
+/**
+ * HTTP Streamable-MCP client that forwards JSON-RPC payloads to the hosted
+ * Ulexid control plane, maintains `Mcp-Session-Id`, and hot-captures the
+ * tenant `api_key` minted by `ulex_poll_agent_connection`.
+ */
+export declare class UlexMcpProxyClient {
+    readonly endpoint: string;
+    private apiKey;
+    private sessionId;
+    private readonly fetchFn;
+    private nextRequestId;
+    constructor(options: UlexMcpProxyClientOptions);
+    getApiKey(): string | undefined;
+    setApiKey(apiKey: string | undefined): void;
+    getSessionId(): string | undefined;
+    sendJsonRpc(payload: unknown): Promise<JsonRpcTransportResult>;
+    initialize(clientName?: string, clientVersion?: string): Promise<unknown>;
+    listTools(): Promise<unknown[]>;
+    callTool(name: string, args?: Record<string, unknown>, explicitId?: string | number): Promise<unknown>;
+}
+export declare function parseProxyCliArgs(argv: readonly string[]): ProxyCliArgs;
+export declare function formatProxyHelp(): string;
+/**
+ * Run a newline-delimited JSON-RPC stdio loop forwarding every MCP message to
+ * the hosted Ulexid HTTP endpoint.
+ */
+export declare function runStdioProxy(options?: StdioProxyOptions): Promise<void>;
+export declare function runStdioProxyFromCli(argv: readonly string[]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,394 @@
+import { createInterface } from 'node:readline';
+export const ENVIRONMENT_ISSUERS = {
+    prod: 'https://ulexid.com',
+    stage: 'https://stage.ulexid.com',
+    dev: 'https://dev.ulexid.com',
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeEnvironment(raw) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'prod' || normalized === 'production')
+        return 'prod';
+    if (normalized === 'stage' || normalized === 'staging')
+        return 'stage';
+    if (normalized === 'dev' || normalized === 'development')
+        return 'dev';
+    throw new Error(`Unknown ulex environment "${raw}". Expected one of: prod, stage, dev.`);
+}
+/**
+ * Resolve the target hosted MCP endpoint URL from explicit flags or environment
+ * variables, defaulting to production (`https://ulexid.com/mcp`).
+ */
+export function resolveMcpEndpoint(options) {
+    const formatUrl = (rawUrl) => {
+        let parsed;
+        try {
+            parsed = new URL(rawUrl.trim());
+        }
+        catch {
+            throw new Error(`Invalid MCP URL: "${rawUrl}"`);
+        }
+        const cleanPath = parsed.pathname.replace(/\/+$/, '');
+        parsed.pathname = cleanPath.endsWith('/mcp') ? cleanPath : `${cleanPath}/mcp`;
+        return parsed.toString();
+    };
+    const explicitUrl = options?.url ?? options?.baseUrl;
+    if (explicitUrl !== undefined && explicitUrl.trim().length > 0) {
+        return formatUrl(explicitUrl);
+    }
+    if (options?.env !== undefined && options.env.trim().length > 0) {
+        return `${ENVIRONMENT_ISSUERS[normalizeEnvironment(options.env)]}/mcp`;
+    }
+    const envUrl = process.env['ULEX_MCP_URL'] ?? process.env['ULEX_URL'];
+    if (envUrl !== undefined && envUrl.trim().length > 0) {
+        return formatUrl(envUrl);
+    }
+    const rawEnv = process.env['ULEX_ENV'] ?? 'prod';
+    const envKey = normalizeEnvironment(rawEnv);
+    return `${ENVIRONMENT_ISSUERS[envKey]}/mcp`;
+}
+function extractApiKeyFromResponse(response) {
+    if (!isRecord(response))
+        return undefined;
+    const result = response['result'];
+    if (!isRecord(result) || result['isError'] === true)
+        return undefined;
+    const structured = result['structuredContent'];
+    if (isRecord(structured)) {
+        const data = isRecord(structured['data']) ? structured['data'] : structured;
+        const key = data['api_key'];
+        if (typeof key === 'string' && key.startsWith('ulex_')) {
+            return key;
+        }
+    }
+    const content = result['content'];
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            if (!isRecord(item) || item['type'] !== 'text')
+                continue;
+            const text = item['text'];
+            if (typeof text !== 'string')
+                continue;
+            const trimmed = text.trim();
+            if (!trimmed.startsWith('{'))
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (!isRecord(parsed))
+                    continue;
+                const data = isRecord(parsed['data']) ? parsed['data'] : parsed;
+                const key = data['api_key'];
+                if (typeof key === 'string' && key.startsWith('ulex_')) {
+                    return key;
+                }
+            }
+            catch {
+                // Non-JSON text blocks are expected in human-readable MCP tool output.
+            }
+        }
+    }
+    return undefined;
+}
+function extractToolCallName(payload) {
+    if (!isRecord(payload))
+        return undefined;
+    if (payload['method'] !== 'tools/call')
+        return undefined;
+    const params = payload['params'];
+    if (!isRecord(params))
+        return undefined;
+    const name = params['name'];
+    return typeof name === 'string' ? name : undefined;
+}
+function parseSseMessages(bodyText, expectedId) {
+    const frames = bodyText.split(/\r?\n\r?\n/);
+    const parsedMessages = [];
+    for (const frame of frames) {
+        const dataLines = [];
+        for (const line of frame.split(/\r?\n/)) {
+            if (line.startsWith('data:')) {
+                dataLines.push(line.slice(5).trimStart());
+            }
+        }
+        if (dataLines.length === 0)
+            continue;
+        const raw = dataLines.join('\n').trim();
+        if (raw.length === 0 || raw === '[DONE]')
+            continue;
+        try {
+            parsedMessages.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip malformed partial SSE keep-alive/comment frames.
+        }
+    }
+    if (parsedMessages.length === 0) {
+        throw new Error('Hosted MCP SSE response contained no JSON-RPC payload.');
+    }
+    if (expectedId !== undefined) {
+        for (const msg of parsedMessages) {
+            if (isRecord(msg) && msg['id'] === expectedId) {
+                return msg;
+            }
+        }
+    }
+    return parsedMessages[parsedMessages.length - 1];
+}
+/**
+ * HTTP Streamable-MCP client that forwards JSON-RPC payloads to the hosted
+ * Ulexid control plane, maintains `Mcp-Session-Id`, and hot-captures the
+ * tenant `api_key` minted by `ulex_poll_agent_connection`.
+ */
+export class UlexMcpProxyClient {
+    endpoint;
+    apiKey;
+    sessionId;
+    fetchFn;
+    nextRequestId = 1;
+    constructor(options) {
+        this.endpoint = options.endpoint;
+        const initialKey = options.apiKey ?? process.env['ULEX_API_KEY'];
+        this.apiKey = initialKey && initialKey.trim().length > 0 ? initialKey.trim() : undefined;
+        this.fetchFn = options.fetchFn ?? fetch;
+    }
+    getApiKey() {
+        return this.apiKey;
+    }
+    setApiKey(apiKey) {
+        this.apiKey = apiKey && apiKey.trim().length > 0 ? apiKey.trim() : undefined;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    async sendJsonRpc(payload) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+        };
+        if (this.apiKey !== undefined) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        if (this.sessionId !== undefined) {
+            headers['Mcp-Session-Id'] = this.sessionId;
+        }
+        const res = await this.fetchFn(this.endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload),
+        });
+        const returnedSession = res.headers.get('mcp-session-id');
+        if (returnedSession !== null && returnedSession.trim().length > 0) {
+            this.sessionId = returnedSession.trim();
+        }
+        if (res.status === 202) {
+            return { status: 202 };
+        }
+        const bodyText = await res.text();
+        const contentType = (res.headers.get('content-type') ?? '').toLowerCase();
+        if (!res.ok) {
+            if (contentType.includes('application/json') && bodyText.trim().length > 0) {
+                try {
+                    const parsedError = JSON.parse(bodyText);
+                    if (isRecord(parsedError) && ('jsonrpc' in parsedError || 'error' in parsedError)) {
+                        return { status: res.status, json: parsedError };
+                    }
+                }
+                catch {
+                    // Fall through to status error below.
+                }
+            }
+            throw new Error(`Hosted MCP request failed with HTTP ${String(res.status)}: ${bodyText.slice(0, 300)}`);
+        }
+        if (bodyText.trim().length === 0) {
+            return { status: res.status };
+        }
+        const requestId = isRecord(payload) ? payload['id'] : undefined;
+        const json = contentType.includes('text/event-stream')
+            ? parseSseMessages(bodyText, requestId)
+            : JSON.parse(bodyText);
+        const toolName = extractToolCallName(payload);
+        if (toolName !== undefined && (toolName === 'ulex_poll_agent_connection' || this.apiKey === undefined)) {
+            const captured = extractApiKeyFromResponse(json);
+            if (captured !== undefined) {
+                this.apiKey = captured;
+            }
+        }
+        return { status: res.status, json };
+    }
+    async initialize(clientName = '@ulexid/mcp-server-proxy', clientVersion = '0.1.1') {
+        const id = this.nextRequestId++;
+        const { json } = await this.sendJsonRpc({
+            jsonrpc: '2.0',
+            id,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: clientName, version: clientVersion },
+            },
+        });
+        await this.sendJsonRpc({
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+            params: {},
+        });
+        return json;
+    }
+    async listTools() {
+        if (this.sessionId === undefined) {
+            await this.initialize();
+        }
+        const id = this.nextRequestId++;
+        const { json } = await this.sendJsonRpc({
+            jsonrpc: '2.0',
+            id,
+            method: 'tools/list',
+            params: {},
+        });
+        if (isRecord(json) && isRecord(json['error'])) {
+            const msg = typeof json['error']['message'] === 'string' ? json['error']['message'] : 'MCP tools/list error';
+            throw new Error(msg);
+        }
+        if (isRecord(json) && isRecord(json['result']) && Array.isArray(json['result']['tools'])) {
+            return json['result']['tools'];
+        }
+        return [];
+    }
+    async callTool(name, args = {}, explicitId) {
+        if (this.sessionId === undefined) {
+            await this.initialize();
+        }
+        const id = explicitId ?? this.nextRequestId++;
+        const { json } = await this.sendJsonRpc({
+            jsonrpc: '2.0',
+            id,
+            method: 'tools/call',
+            params: { name, arguments: args },
+        });
+        if (isRecord(json) && isRecord(json['error'])) {
+            const msg = typeof json['error']['message'] === 'string' ? json['error']['message'] : `MCP error calling ${name}`;
+            throw new Error(msg);
+        }
+        if (isRecord(json) && 'result' in json) {
+            return json['result'];
+        }
+        return json;
+    }
+}
+export function parseProxyCliArgs(argv) {
+    let url;
+    let env;
+    let apiKey;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === undefined)
+            continue;
+        if (token === '-h' || token === '--help') {
+            help = true;
+        }
+        else if (token === '--url' || token.startsWith('--url=')) {
+            url = token.includes('=') ? token.slice(token.indexOf('=') + 1) : argv[++i];
+        }
+        else if (token === '--env' || token.startsWith('--env=')) {
+            env = token.includes('=') ? token.slice(token.indexOf('=') + 1) : argv[++i];
+        }
+        else if (token === '--api-key' || token.startsWith('--api-key=')) {
+            apiKey = token.includes('=') ? token.slice(token.indexOf('=') + 1) : argv[++i];
+        }
+    }
+    return {
+        ...(url !== undefined ? { url } : {}),
+        ...(env !== undefined ? { env } : {}),
+        ...(apiKey !== undefined ? { apiKey } : {}),
+        help,
+    };
+}
+export function formatProxyHelp() {
+    return [
+        '@ulexid/mcp-server — stdio proxy for the hosted Ulexid MCP control plane',
+        '',
+        'Usage:',
+        '  npx @ulexid/mcp-server [options]',
+        '',
+        'Options:',
+        '  --env <prod|stage|dev>   Target Ulexid environment (default: prod -> https://ulexid.com/mcp)',
+        '  --url <url>              Override full Ulexid base or /mcp endpoint URL',
+        '  --api-key <key>          Tenant API key (defaults to ULEX_API_KEY env var)',
+        '  -h, --help               Show this help message',
+        '',
+        'Environment variables:',
+        '  ULEX_MCP_URL / ULEX_URL  Explicit hosted endpoint URL override',
+        '  ULEX_ENV                 Environment selector (prod, stage, dev)',
+        '  ULEX_API_KEY             Bearer API key sent to the hosted control plane',
+    ].join('\n');
+}
+/**
+ * Run a newline-delimited JSON-RPC stdio loop forwarding every MCP message to
+ * the hosted Ulexid HTTP endpoint.
+ */
+export async function runStdioProxy(options = {}) {
+    const endpoint = options.endpoint ?? resolveMcpEndpoint(options);
+    const client = new UlexMcpProxyClient({
+        endpoint,
+        ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+        ...(options.fetchFn !== undefined ? { fetchFn: options.fetchFn } : {}),
+    });
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+    let chain = Promise.resolve();
+    const processLine = async (line) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        let payload;
+        try {
+            payload = JSON.parse(trimmed);
+        }
+        catch {
+            stdout.write(`${JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error: invalid JSON on stdin' },
+            })}\n`);
+            return;
+        }
+        const requestId = isRecord(payload) && 'id' in payload ? payload['id'] : undefined;
+        try {
+            const response = await client.sendJsonRpc(payload);
+            if (response.json !== undefined) {
+                stdout.write(`${JSON.stringify(response.json)}\n`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            stderr.write(`[ulexid-mcp] ${message}\n`);
+            if (requestId !== undefined) {
+                stdout.write(`${JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: requestId,
+                    error: { code: -32603, message },
+                })}\n`);
+            }
+        }
+    };
+    rl.on('line', (line) => {
+        chain = chain.then(() => processLine(line));
+    });
+    await new Promise((resolve) => {
+        rl.once('close', resolve);
+    });
+    await chain;
+}
+export async function runStdioProxyFromCli(argv) {
+    const args = parseProxyCliArgs(argv);
+    if (args.help) {
+        process.stdout.write(`${formatProxyHelp()}\n`);
+        return;
+    }
+    await runStdioProxy(args);
+}

package/dist/stdio.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runStdioProxyFromCli } from './index.js';
+runStdioProxyFromCli(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`[ulexid-mcp] ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@ulexid/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Ulexid MCP stdio proxy — connect AI coding agents to https://ulexid.com/mcp",
+  "homepage": "https://www.ulexid.com",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mcp-server": "dist/stdio.js",
+    "ulex-mcp": "dist/stdio.js",
+    "ulexid-mcp": "dist/stdio.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./stdio": "./dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {}
+}