easy-local-mcp 0.3.9

package/dist/lifecycle.js

@@ -0,0 +1,321 @@
+import { spawn } from 'node:child_process';
+import { timingSafeEqual } from 'node:crypto';
+import { createConnection, createServer } from 'node:net';
+import { mkdir, open, readFile, rm, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { controlEndpoint } from './control-endpoint.js';
+import { ensureControlSecret, getControlSecret } from './security.js';
+import { ensureRelayConfigured } from './relay-config.js';
+export const stateDir = resolve(homedir(), '.localmcp');
+export const logFile = resolve(stateDir, 'agent.log');
+const endpoint = controlEndpoint(stateDir);
+const lockFile = resolve(stateDir, 'control.lock');
+const pause = (ms) => new Promise(resolvePause => setTimeout(resolvePause, ms));
+function secureEqual(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function maskMcpUrl(url) {
+    if (!url)
+        return '-';
+    try {
+        const parsed = new URL(url);
+        const segments = parsed.pathname.split('/').filter(Boolean);
+        if (segments.length) {
+            const last = segments.length - 1;
+            segments[last] = '<redacted>';
+            parsed.pathname = '/' + segments.join('/');
+        }
+        parsed.search = '';
+        parsed.hash = '';
+        parsed.username = '';
+        parsed.password = '';
+        return parsed.href;
+    }
+    catch {
+        return '<redacted>';
+    }
+}
+export async function request(command = 'status', options = {}) {
+    const secret = await getControlSecret();
+    return new Promise((resolveStatus, reject) => {
+        const socket = createConnection(endpoint.address);
+        let data = '';
+        const timer = setTimeout(() => socket.destroy(new Error('Easy Local MCP control request timed out')), 20000);
+        socket.on('connect', () => {
+            const payload = {
+                command,
+                secret,
+                ...(options.minutes === undefined ? {} : { minutes: options.minutes }),
+                ...(options.workerUrl === undefined ? {} : { workerUrl: options.workerUrl })
+            };
+            socket.write(JSON.stringify(payload) + '\n');
+        });
+        socket.on('data', chunk => {
+            data += chunk;
+            if (data.length > 65536) {
+                socket.destroy(new Error('Invalid control response'));
+            }
+        });
+        socket.on('error', reject);
+        socket.on('close', () => clearTimeout(timer));
+        socket.on('end', () => {
+            try {
+                if (!data) {
+                    throw Object.assign(new Error('Easy Local MCP control connection closed'), { code: 'ECONNRESET' });
+                }
+                const response = JSON.parse(data);
+                if (response.error)
+                    reject(new Error(response.error));
+                else
+                    resolveStatus(response);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+export async function status() {
+    try {
+        return await request();
+    }
+    catch (error) {
+        if (!['ENOENT', 'ECONNREFUSED', 'ECONNRESET', 'EPIPE'].includes(error.code)) {
+            throw error;
+        }
+        return {
+            status: 'stopped',
+            pid: null,
+            url: null,
+            config: resolve(process.env.LOCALMCP_CONFIG || resolve(stateDir, 'localmcp.json')),
+            log: logFile,
+            ready: false,
+            locked: true,
+            unlockExpiresAt: null,
+            workerUrl: null,
+            deviceId: null,
+            workerManagedByEnv: process.env.LOCALMCP_WORKER_URL !== undefined
+        };
+    }
+}
+export function printStatus(value) {
+    console.log(`Status: ${value.status}\n`
+        + `PID: ${value.pid ?? '-'}\n`
+        + `Security: ${value.locked ? 'LOCKED' : 'UNLOCKED'}\n`
+        + `Unlock expires: ${value.unlockExpiresAt ?? '-'}\n`
+        + `MCP URL: ${maskMcpUrl(value.url)}\n`
+        + `Config: ${value.config}\n`
+        + `Log: ${value.log}`);
+}
+export function printUrl(value) {
+    if (value.status !== 'running' || !value.url) {
+        throw new Error('Easy Local MCP is not running or has no MCP URL');
+    }
+    console.log(value.url);
+}
+async function locked(action) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + 90000;
+    while (true) {
+        try {
+            const file = await open(lockFile, 'wx', 0o600);
+            try {
+                await file.writeFile(String(process.pid));
+            }
+            finally {
+                await file.close();
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let pid = 0;
+            try {
+                pid = Number(await readFile(lockFile, 'utf8'));
+            }
+            catch (readError) {
+                if (readError.code !== 'ENOENT')
+                    throw readError;
+            }
+            if (Number.isInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (killError) {
+                    if (killError.code === 'ESRCH') {
+                        await rm(lockFile, { force: true });
+                        continue;
+                    }
+                }
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`Another Easy Local MCP command is still running (${lockFile})`);
+            }
+            await pause(100);
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await rm(lockFile, { force: true });
+    }
+}
+export async function control(command, initialize = async () => { }) {
+    return locked(async () => {
+        let current = await status();
+        if (command === 'reload') {
+            if (current.status === 'stopped') {
+                throw new Error('Easy Local MCP is stopped; run easy-local-mcp to start it');
+            }
+            current = await request('reload');
+            console.log('Easy Local MCP configuration reloaded.');
+        }
+        else if (command === 'stop') {
+            if (current.status === 'running') {
+                await request('stop');
+                for (let i = 0; i < 100; i++) {
+                    current = await status();
+                    if (current.status === 'stopped')
+                        break;
+                    await pause(100);
+                }
+                if (current.status !== 'stopped') {
+                    throw new Error(`Easy Local MCP did not stop; see ${logFile}`);
+                }
+            }
+        }
+        else {
+            let child;
+            if (current.status === 'stopped') {
+                await ensureRelayConfigured();
+                await initialize();
+                if (endpoint.socketFile) {
+                    await rm(endpoint.socketFile, { force: true });
+                }
+                const log = await open(logFile, 'a', 0o600);
+                try {
+                    child = spawn(process.execPath, [fileURLToPath(new URL('./agent.js', import.meta.url))], {
+                        detached: true,
+                        stdio: ['ignore', log.fd, log.fd],
+                        env: process.env,
+                        windowsHide: process.platform === 'win32'
+                    });
+                    await new Promise((ready, reject) => {
+                        child.once('spawn', ready);
+                        child.once('error', reject);
+                    });
+                    child.unref();
+                }
+                finally {
+                    await log.close();
+                }
+            }
+            const deadline = Date.now() + 60000;
+            while (!current.ready) {
+                if (child && (child.exitCode !== null || child.signalCode !== null)) {
+                    throw new Error(`Easy Local MCP startup failed; see ${logFile}`);
+                }
+                if (Date.now() > deadline) {
+                    child?.kill('SIGTERM');
+                    throw new Error(`Easy Local MCP startup timed out; see ${logFile}`);
+                }
+                await pause(100);
+                current = await status();
+            }
+        }
+        printStatus(current);
+    });
+}
+export async function serveControl(getStatus, handlers) {
+    const controlSecret = await ensureControlSecret();
+    const server = createServer({ allowHalfOpen: true }, socket => {
+        let data = '';
+        let handled = false;
+        socket.setTimeout(20000, () => socket.destroy());
+        socket.on('error', () => { });
+        const handle = () => {
+            if (handled || socket.destroyed)
+                return;
+            handled = true;
+            void (async () => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(data.trim());
+                }
+                catch {
+                    throw new Error('Invalid control request');
+                }
+                if (!parsed
+                    || typeof parsed.command !== 'string'
+                    || typeof parsed.secret !== 'string'
+                    || !secureEqual(parsed.secret, controlSecret)) {
+                    throw new Error('Unauthorized control request');
+                }
+                switch (parsed.command) {
+                    case 'status':
+                        break;
+                    case 'reload':
+                        await handlers.reload();
+                        break;
+                    case 'unlock':
+                        await handlers.unlock(parsed.minutes);
+                        break;
+                    case 'lock':
+                        await handlers.lock();
+                        break;
+                    case 'rotate':
+                        await handlers.rotate();
+                        break;
+                    case 'reregister':
+                        if (typeof parsed.workerUrl !== 'string' || !parsed.workerUrl) {
+                            throw new Error('workerUrl is required');
+                        }
+                        await handlers.reregister(parsed.workerUrl);
+                        break;
+                    case 'stop':
+                        socket.once('close', handlers.stop);
+                        break;
+                    default:
+                        throw new Error('Unknown control command');
+                }
+                socket.end(JSON.stringify(await getStatus()));
+            })().catch(error => {
+                socket.end(JSON.stringify({
+                    error: error instanceof Error ? error.message : String(error)
+                }));
+            });
+        };
+        socket.on('data', chunk => {
+            data += chunk;
+            if (data.length > 4096) {
+                socket.destroy();
+                return;
+            }
+            if (data.includes('\n')) {
+                handle();
+            }
+        });
+        socket.on('end', handle);
+    });
+    await new Promise((ready, reject) => {
+        server.once('error', reject);
+        server.listen(endpoint.address, ready);
+    });
+    if (endpoint.socketFile) {
+        await chmod(endpoint.socketFile, 0o600);
+    }
+    return async () => {
+        await new Promise((done, reject) => {
+            server.close(error => error ? reject(error) : done());
+        });
+        if (endpoint.socketFile) {
+            await rm(endpoint.socketFile, { force: true });
+        }
+    };
+}

package/dist/mcp/loader.js

@@ -0,0 +1,86 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+export class McpLoader {
+    servers;
+    loaded = [];
+    starting = new Map();
+    pending = new Set();
+    track(operation) { this.pending.add(operation); return operation.finally(() => this.pending.delete(operation)); }
+    constructor(servers) {
+        this.servers = servers;
+    }
+    getLoaded(name) { return this.loaded.find(server => server.name === name); }
+    async ensure(name) {
+        const existing = this.getLoaded(name);
+        if (existing)
+            return existing;
+        const inFlight = this.starting.get(name);
+        if (inFlight)
+            return inFlight;
+        const cfg = this.servers[name];
+        if (!cfg)
+            throw new Error(`Unknown MCP server '${name}'`);
+        const operation = (async () => {
+            const client = new Client({ name: `easy-local-mcp-${name}`, version: '0.3.0' });
+            const transport = new StdioClientTransport({ command: cfg.command, args: cfg.args || [], env: cfg.env, stderr: 'inherit' });
+            const server = { name, client, tools: [] };
+            try {
+                await client.connect(transport);
+                await this.refresh(server);
+                this.loaded.push(server);
+                return server;
+            }
+            catch (error) {
+                await client.close().catch(() => { });
+                throw error;
+            }
+            finally {
+                this.starting.delete(name);
+            }
+        })();
+        this.starting.set(name, operation);
+        return operation;
+    }
+    async start() {
+        try {
+            for (const name of Object.keys(this.servers))
+                await this.ensure(name);
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    async refresh(server) {
+        const tools = [];
+        let cursor;
+        do {
+            const page = await server.client.listTools({ cursor });
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor);
+        server.tools = tools;
+        return tools;
+    }
+    listServers() { return Object.keys(this.servers).map(name => ({ name, running: !!this.getLoaded(name) })); }
+    async listTools(server) {
+        return this.track((async () => this.refresh(await this.ensure(server)))());
+    }
+    async call(serverName, toolName, args) {
+        const server = await this.ensure(serverName);
+        const tool = server.tools.find(tool => tool.name === toolName);
+        if (!tool)
+            throw new Error(`Unknown MCP tool '${toolName}' on server '${serverName}'; use list_mcp_tools first`);
+        const validation = new AjvJsonSchemaValidator().getValidator(tool.inputSchema)(args);
+        if (!validation.valid)
+            throw new Error(`Invalid arguments for MCP tool '${toolName}': ${validation.errorMessage}`);
+        return this.track(server.client.callTool({ name: toolName, arguments: args }, undefined, { timeout: 60000 }));
+    }
+    async close() {
+        await Promise.allSettled([...this.pending, ...this.starting.values()]);
+        await Promise.allSettled(this.loaded.map(server => server.client.close()));
+        this.loaded = [];
+        this.starting.clear();
+    }
+}

package/dist/process.js

@@ -0,0 +1,122 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+const MAX_BUFFER = 1024 * 1024;
+export class ProcessManager {
+    processes = new Map();
+    start(command, cwd) {
+        const env = {};
+        for (const key of ['PATH', 'HOME', 'USER', 'TMPDIR', 'LANG', 'SHELL', 'SystemRoot'])
+            if (process.env[key])
+                env[key] = process.env[key];
+        const child = spawn(command, { cwd, shell: true, detached: process.platform !== 'win32', env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: process.platform === 'win32' });
+        const proc = { id: randomUUID(), child, command, cwd, stdout: '', stderr: '', stdoutOffset: 0, stderrOffset: 0, startedAt: new Date().toISOString(), running: true, exitCode: null, signal: null };
+        const collect = (stream, chunk) => {
+            const text = chunk.toString('utf8');
+            proc[stream] += text;
+            if (Buffer.byteLength(proc[stream]) > MAX_BUFFER) {
+                const excess = Buffer.byteLength(proc[stream]) - MAX_BUFFER;
+                proc[stream] = Buffer.from(proc[stream]).subarray(excess).toString('utf8');
+                if (stream === 'stdout')
+                    proc.stdoutOffset += excess;
+                else
+                    proc.stderrOffset += excess;
+            }
+        };
+        child.stdout?.on('data', c => collect('stdout', c));
+        child.stderr?.on('data', c => collect('stderr', c));
+        const markExited = (code, signal) => {
+            proc.running = false;
+            proc.exitCode = code;
+            proc.signal = signal;
+        };
+        // Use exit for process state. On Windows, close can be delayed indefinitely
+        // when descendants inherit the shell's stdio handles after the shell exits.
+        child.on('exit', markExited);
+        child.on('close', markExited);
+        child.on('error', () => { proc.running = false; });
+        this.processes.set(proc.id, proc);
+        return { processId: proc.id, pid: child.pid, running: true, startedAt: proc.startedAt };
+    }
+    read(id, stdoutCursor = 0, stderrCursor = 0) {
+        const proc = this.mustGet(id);
+        const readOne = (text, base, cursor) => {
+            const effective = Math.max(cursor, base);
+            const data = Buffer.from(text);
+            const local = Math.min(Math.max(0, effective - base), data.length);
+            return { text: data.subarray(local).toString('utf8'), nextCursor: base + data.length, truncatedBeforeCursor: cursor < base };
+        };
+        const out = readOne(proc.stdout, proc.stdoutOffset, stdoutCursor);
+        const err = readOne(proc.stderr, proc.stderrOffset, stderrCursor);
+        return { processId: id, stdout: out.text, stderr: err.text, nextStdoutCursor: out.nextCursor, nextStderrCursor: err.nextCursor, stdoutTruncated: out.truncatedBeforeCursor, stderrTruncated: err.truncatedBeforeCursor, running: proc.running, exitCode: proc.exitCode, signal: proc.signal };
+    }
+    write(id, input) {
+        const proc = this.mustGet(id);
+        if (!proc.running || !proc.child.stdin || proc.child.stdin.destroyed)
+            throw new Error('Process stdin is not available');
+        proc.child.stdin.write(input);
+        return { processId: id, bytes: Buffer.byteLength(input) };
+    }
+    stop(id) {
+        const proc = this.mustGet(id);
+        if (!proc.running)
+            return { processId: id, running: false, exitCode: proc.exitCode, signal: proc.signal };
+        this.terminate(proc, false);
+        return { processId: id, stopping: true };
+    }
+    list() {
+        return [...this.processes.values()].map(proc => ({ processId: proc.id, pid: proc.child.pid, command: proc.command, cwd: proc.cwd, startedAt: proc.startedAt, running: proc.running, exitCode: proc.exitCode, signal: proc.signal }));
+    }
+    async close() {
+        const pending = [];
+        for (const proc of this.processes.values()) {
+            if (!proc.running)
+                continue;
+            pending.push(this.waitForExit(proc));
+            this.terminate(proc, true);
+        }
+        await Promise.allSettled(pending);
+    }
+    terminate(proc, force) {
+        try {
+            if (process.platform === 'win32' && proc.child.pid) {
+                const killer = spawn('taskkill', ['/PID', String(proc.child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+                killer.once('error', () => {
+                    try {
+                        proc.child.kill(force ? 'SIGKILL' : 'SIGTERM');
+                    }
+                    catch { }
+                });
+            }
+            else if (proc.child.pid) {
+                process.kill(-proc.child.pid, force ? 'SIGKILL' : 'SIGTERM');
+            }
+            else {
+                proc.child.kill(force ? 'SIGKILL' : 'SIGTERM');
+            }
+        }
+        catch { }
+    }
+    async waitForExit(proc) {
+        if (!proc.running)
+            return;
+        await new Promise(resolveExit => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolveExit();
+            };
+            const timer = setTimeout(finish, 3000);
+            proc.child.once('exit', finish);
+            proc.child.once('close', finish);
+        });
+    }
+    mustGet(id) {
+        const proc = this.processes.get(id);
+        if (!proc)
+            throw new Error('Unknown processId');
+        return proc;
+    }
+}

package/dist/relay-config.js

@@ -0,0 +1,145 @@
+import { access, readFile, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { DEFAULT_PUBLIC_WORKER_URL, validatedWorkerOrigin } from './relay.js';
+import { secureWriteFileAtomic } from './security.js';
+const relayStateDir = resolve(homedir(), '.localmcp');
+export const relayConfigFile = resolve(relayStateDir, 'relay.json');
+export const registeredWorkerFile = resolve(relayStateDir, 'worker.json');
+export const pendingRegistrationTokenFile = resolve(relayStateDir, 'registration-token.pending');
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function workerUrlFrom(value, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Invalid Relay configuration in ${path}`);
+    }
+    const workerUrl = value.workerUrl;
+    if (typeof workerUrl !== 'string' || !workerUrl.trim()) {
+        throw new Error(`Invalid workerUrl in ${path}`);
+    }
+    return validatedWorkerOrigin(workerUrl).href;
+}
+export async function relaySetupState() {
+    const envWorker = process.env.LOCALMCP_WORKER_URL?.trim();
+    if (envWorker) {
+        return {
+            configured: true,
+            workerUrl: validatedWorkerOrigin(envWorker).href,
+            suggestedWorkerUrl: validatedWorkerOrigin(envWorker).href,
+            source: 'env',
+            managedByEnv: true,
+            registrationTokenManagedByEnv: process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined
+        };
+    }
+    const saved = await readJson(relayConfigFile);
+    if (saved !== undefined) {
+        const workerUrl = workerUrlFrom(saved, relayConfigFile);
+        return {
+            configured: true,
+            workerUrl,
+            suggestedWorkerUrl: workerUrl,
+            source: 'saved',
+            managedByEnv: false,
+            registrationTokenManagedByEnv: process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined
+        };
+    }
+    const registered = await readJson(registeredWorkerFile);
+    if (registered !== undefined) {
+        const workerUrl = workerUrlFrom(registered, registeredWorkerFile);
+        return {
+            configured: true,
+            workerUrl,
+            suggestedWorkerUrl: workerUrl,
+            source: 'registered',
+            managedByEnv: false,
+            registrationTokenManagedByEnv: process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined
+        };
+    }
+    return {
+        configured: false,
+        workerUrl: null,
+        suggestedWorkerUrl: validatedWorkerOrigin(DEFAULT_PUBLIC_WORKER_URL).href,
+        source: 'unconfigured',
+        managedByEnv: false,
+        registrationTokenManagedByEnv: process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined
+    };
+}
+export async function ensureRelayConfigured() {
+    const envWorker = process.env.LOCALMCP_WORKER_URL?.trim();
+    if (envWorker) {
+        validatedWorkerOrigin(envWorker);
+        return;
+    }
+    const saved = await readJson(relayConfigFile);
+    if (saved !== undefined) {
+        workerUrlFrom(saved, relayConfigFile);
+        return;
+    }
+    try {
+        await access(registeredWorkerFile);
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    throw new Error('Relay is not configured. Open the Easy Local MCP Control Center and choose a Relay before starting the Agent.');
+}
+export async function configuredRelayUrl() {
+    const state = await relaySetupState();
+    if (!state.configured || !state.workerUrl) {
+        throw new Error('Relay is not configured. Open the Easy Local MCP Control Center and choose a Relay before starting the Agent.');
+    }
+    return state.workerUrl;
+}
+export async function saveRelayPreference(workerUrl) {
+    if (process.env.LOCALMCP_WORKER_URL) {
+        throw new Error('Relay is controlled by LOCALMCP_WORKER_URL; remove the environment override before changing it in the UI.');
+    }
+    const normalized = validatedWorkerOrigin(workerUrl).href;
+    await secureWriteFileAtomic(relayConfigFile, JSON.stringify({ workerUrl: normalized }, null, 2) + '\n');
+    return normalized;
+}
+export async function savePendingRegistrationToken(value) {
+    if (process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined) {
+        if (value?.trim()) {
+            throw new Error('Registration token is controlled by LOCALMCP_REGISTRATION_TOKEN; remove the environment override before changing it in the UI.');
+        }
+        return;
+    }
+    const token = value?.trim() ?? '';
+    if (!token) {
+        await rm(pendingRegistrationTokenFile, { force: true });
+        return;
+    }
+    if (token.length > 8192) {
+        throw new Error('Registration token is too long');
+    }
+    await secureWriteFileAtomic(pendingRegistrationTokenFile, token + '\n');
+}
+export async function registrationToken() {
+    if (process.env.LOCALMCP_REGISTRATION_TOKEN !== undefined) {
+        return process.env.LOCALMCP_REGISTRATION_TOKEN;
+    }
+    try {
+        return (await readFile(pendingRegistrationTokenFile, 'utf8')).trim() || undefined;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function clearPendingRegistrationToken() {
+    if (process.env.LOCALMCP_REGISTRATION_TOKEN === undefined) {
+        await rm(pendingRegistrationTokenFile, { force: true });
+    }
+}