Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { type ChildProcess, spawn as nativeSpawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { closeSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
import type { Readable, Writable } from 'node:stream';
import { setTimeout as wait } from 'node:timers/promises';
import {
clientVersionHeaders,
currentCliCommandName,
DEFAULT_SERVER_HOST,
sliceLastSpawnAttempt,
} from '@inkeep/open-knowledge-core';
import { startKeepalive as defaultStartKeepalive } from '@inkeep/open-knowledge-core/keepalive';
import { openSpawnErrorLog, projectSpawnErrorLogPath } from '@inkeep/open-knowledge-core/server';
import {
AutoStartDisabledError,
isProcessAlive as defaultIsProcessAlive,
lockBaseUrl,
MCP_CONNECTION_ID_HEADER,
prepareSpawnProjectLogsDir,
RUNTIME_VERSION,
readServerLock,
type ServerLockMetadata,
} from '@inkeep/open-knowledge-server';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import type { JSONRPCMessage, RequestId } from '@modelcontextprotocol/sdk/types.js';
import { resolveSelfSpawn } from '../commands/self-spawn.ts';
const DEFAULT_SPAWN_TIMEOUT_MS = 5000;
const DEFAULT_POLL_INTERVAL_MS = 100;
const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
function serverStartRecovery(): string {
return `Run \`${currentCliCommandName()} start\` in the target project, then retry this tool. Do not fall back to native file edits for OpenKnowledge content.`;
}
interface ShimTransport {
onerror: ((err: Error) => void) | undefined;
onclose: (() => void) | undefined;
onmessage: ((msg: JSONRPCMessage) => void) | undefined;
setProtocolVersion?: (version: string) => void;
start(): Promise<void>;
close(): Promise<void>;
send(msg: JSONRPCMessage): Promise<void>;
}
function makeFetchWithTimeout(
timeoutMs: number,
): (url: string | URL, init?: RequestInit) => Promise<Response> {
return (url, init) => {
if ((init?.method ?? 'GET').toUpperCase() === 'GET') {
return globalThis.fetch(url as URL, init);
}
const controller = new AbortController();
const timer = setTimeout(
() => controller.abort(new Error(`MCP request timed out after ${timeoutMs}ms`)),
timeoutMs,
);
const signal =
init?.signal instanceof AbortSignal
? AbortSignal.any([init.signal, controller.signal])
: controller.signal;
return globalThis.fetch(url as URL, { ...init, signal }).finally(() => clearTimeout(timer));
};
}
export function parseSpawnTimeoutEnv(raw: string | undefined): number | undefined {
if (raw === undefined || raw === '') return undefined;
const parsed = Number.parseInt(raw, 10);
if (Number.isNaN(parsed) || parsed <= 0) return undefined;
return parsed;
}
interface ResolveMcpHttpUrlOptions {
projectDir: string;
authorityRegistryPath?: string;
lockDir: string;
contentDir: string;
portOverride?: string;
envAutoStart?: string;
spawn?: typeof nativeSpawn;
readLock?: () => ServerLockMetadata | null;
isAlive?: (pid: number) => boolean;
sleep?: (ms: number) => Promise<void>;
readErrorLog?: (path: string) => string;
openErrorLog?: (path: string) => number | Promise<number>;
closeFd?: (fd: number) => void;
timeoutMs?: number;
pollIntervalMs?: number;
}
interface StartMcpShimOptions extends ResolveMcpHttpUrlOptions {
stderr?: NodeJS.WritableStream;
startKeepalive?: typeof defaultStartKeepalive;
createConnectionId?: () => string;
bridgeFn?: (
endpointUrl: string,
opts?: BridgeStdioToHttpMcpOptions,
) => Promise<{ close: () => Promise<void> }>;
}
interface BridgeStdioToHttpMcpOptions {
stderr?: NodeJS.WritableStream;
stdin?: Readable;
stdout?: Writable;
requestTimeoutMs?: number;
connectionId?: string;
onclose?: () => void;
createStdioTransport?: (
stdin: Readable | undefined,
stdout: Writable | undefined,
) => ShimTransport;
createHttpTransport?: (url: URL) => ShimTransport;
}
function formatHost(host: string): string {
if (host === '0.0.0.0' || host === '::') return 'localhost';
return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
}
function mcpUrlForPort(host: string, port: number): string {
return `http://${formatHost(host)}:${port}/mcp`;
}
function mcpUrlForBase(baseUrl: string): string {
return `${baseUrl}/mcp`;
}
function wsUrlForBase(baseUrl: string): string {
return baseUrl.replace(/^http/, 'ws');
}
function wsUrlFromMcpEndpoint(endpointUrl: string): string {
const url = new URL(endpointUrl);
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
url.pathname = '';
url.search = '';
url.hash = '';
return url.toString().replace(/\/$/, '');
}
function liveBaseUrlFromLock(
lock: ServerLockMetadata | null,
isAlive: (pid: number) => boolean,
): string | undefined {
if (!lock) return undefined;
if (lock.draining === true) return undefined;
if (!isAlive(lock.pid)) return undefined;
return lockBaseUrl(lock, { fallbackHost: DEFAULT_SERVER_HOST }) ?? undefined;
}
const SPAWN_STDERR_TAIL_UNITS = 8192;
function readErrorLogDefault(path: string): string {
if (!existsSync(path)) return '';
const attempt = sliceLastSpawnAttempt(readFileSync(path, 'utf-8')).trim();
return attempt.length > SPAWN_STDERR_TAIL_UNITS
? `…${attempt.slice(-SPAWN_STDERR_TAIL_UNITS)}`
: attempt;
}
function formatTimeoutMessage(timeoutMs: number, stderr: string): string {
const stderrBlock = stderr ? ` stderr:\n${stderr}` : '';
return `server did not start within ${timeoutMs}ms${stderrBlock}\n${serverStartRecovery()}`;
}
function requestIdOf(message: JSONRPCMessage): RequestId | undefined {
if (message && typeof message === 'object' && 'method' in message && 'id' in message) {
return message.id;
}
return undefined;
}
function maybeProtocolVersion(message: JSONRPCMessage): string | undefined {
if (!message || typeof message !== 'object' || !('result' in message)) return undefined;
const result = message.result;
if (!result || typeof result !== 'object' || !('protocolVersion' in result)) return undefined;
const version = result.protocolVersion;
return typeof version === 'string' ? version : undefined;
}
function toErrorResponse(id: RequestId, err: unknown): JSONRPCMessage {
return {
jsonrpc: '2.0',
id,
error: {
code: -32000,
message: err instanceof Error ? err.message : String(err),
},
};
}
export async function resolveMcpHttpUrl(opts: ResolveMcpHttpUrlOptions): Promise<string> {
const readLock = opts.readLock ?? (() => readServerLock(opts.lockDir));
const isAlive = opts.isAlive ?? defaultIsProcessAlive;
const sleep = opts.sleep ?? ((ms: number) => wait(ms));
const spawnFn = opts.spawn ?? nativeSpawn;
const readErrorLog = opts.readErrorLog ?? readErrorLogDefault;
const openErrorLog =
opts.openErrorLog ??
(async (path: string) => {
await prepareSpawnProjectLogsDir(opts.projectDir, {
authorityRegistryPath: opts.authorityRegistryPath,
});
return openSpawnErrorLog(path, process.pid);
});
const closeFd = opts.closeFd ?? closeSync;
const timeoutMs = opts.timeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
if (opts.portOverride !== undefined) {
const parsed = Number.parseInt(opts.portOverride, 10);
if (Number.isNaN(parsed) || parsed <= 0) {
throw new Error(
`invalid --port value '${opts.portOverride}' — HTTP MCP shim requires a positive port`,
);
}
return mcpUrlForPort(DEFAULT_SERVER_HOST, parsed);
}
const initialLock = readLock();
const existingBase = liveBaseUrlFromLock(initialLock, isAlive);
if (existingBase !== undefined) return mcpUrlForBase(existingBase);
if (opts.envAutoStart === '0') {
throw new AutoStartDisabledError(
`OpenKnowledge server is not running and OK_MCP_AUTOSTART=0 disables auto-start. ${serverStartRecovery()}`,
);
}
if (initialLock !== null && initialLock.draining === true && isAlive(initialLock.pid)) {
const drainWaitStartedAt = Date.now();
const drainDeadline = drainWaitStartedAt + timeoutMs;
let drainTimedOut = true;
while (Date.now() < drainDeadline) {
const lock = readLock();
if (lock === null || lock.draining !== true || !isAlive(lock.pid)) {
drainTimedOut = false;
break;
}
await sleep(pollIntervalMs);
}
console.error(
`[mcp-shim] waited ${Date.now() - drainWaitStartedAt}ms for a draining predecessor server` +
`${drainTimedOut ? ' (timed out — proceeding anyway)' : ''}`,
);
const baseAfterDrain = liveBaseUrlFromLock(readLock(), isAlive);
if (baseAfterDrain !== undefined) return mcpUrlForBase(baseAfterDrain);
}
if (!existsSync(opts.lockDir)) mkdirSync(opts.lockDir, { recursive: true });
const stderrPath = projectSpawnErrorLogPath(opts.projectDir);
let stderrFd: number;
try {
stderrFd = await openErrorLog(stderrPath);
} catch (err) {
throw new Error(
`spawn failed: could not prepare server-start diagnostics: ${err instanceof Error ? err.message : String(err)}\n${serverStartRecovery()}`,
{ cause: err },
);
}
let child: ChildProcess | undefined;
let asyncSpawnError: string | undefined;
const self = resolveSelfSpawn();
try {
try {
child = spawnFn(self.command, [...self.prefixArgs, 'start'], {
detached: true,
stdio: ['ignore', 'ignore', stderrFd],
windowsHide: true,
cwd: opts.contentDir,
env: {
...process.env,
OK_LOCK_KIND: 'mcp-spawned',
ELECTRON_RUN_AS_NODE: '1',
},
});
child.on('error', (err) => {
asyncSpawnError = err instanceof Error ? err.message : String(err);
});
child.unref();
} catch (err) {
asyncSpawnError = err instanceof Error ? err.message : String(err);
}
} finally {
try {
closeFd(stderrFd);
} catch {}
}
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (asyncSpawnError) {
const stderr = readErrorLog(stderrPath);
const stderrBlock = stderr ? ` stderr:\n${stderr}` : '';
throw new Error(`spawn failed: ${asyncSpawnError}${stderrBlock}\n${serverStartRecovery()}`);
}
await sleep(pollIntervalMs);
const base = liveBaseUrlFromLock(readLock(), isAlive);
if (base !== undefined) return mcpUrlForBase(base);
}
if (asyncSpawnError) {
const stderr = readErrorLog(stderrPath);
const stderrBlock = stderr ? ` stderr:\n${stderr}` : '';
throw new Error(`spawn failed: ${asyncSpawnError}${stderrBlock}\n${serverStartRecovery()}`);
}
throw new Error(formatTimeoutMessage(timeoutMs, readErrorLog(stderrPath)));
}
export function resolveMcpKeepaliveWsUrl(
opts: Pick<ResolveMcpHttpUrlOptions, 'lockDir' | 'portOverride' | 'readLock' | 'isAlive'>,
endpointUrl: string,
): string | undefined {
if (opts.portOverride !== undefined) return wsUrlFromMcpEndpoint(endpointUrl);
const readLock = opts.readLock ?? (() => readServerLock(opts.lockDir));
const isAlive = opts.isAlive ?? defaultIsProcessAlive;
const base = liveBaseUrlFromLock(readLock(), isAlive);
if (base !== undefined) return wsUrlForBase(base);
return undefined;
}
export async function bridgeStdioToHttpMcp(
endpointUrl: string,
opts: BridgeStdioToHttpMcpOptions = {},
): Promise<{ close: () => Promise<void> }> {
const stderr = opts.stderr ?? process.stderr;
const requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
const stdio: ShimTransport = opts.createStdioTransport
? opts.createStdioTransport(opts.stdin, opts.stdout)
: (new StdioServerTransport(opts.stdin, opts.stdout) as unknown as ShimTransport);
const http: ShimTransport = opts.createHttpTransport
? opts.createHttpTransport(new URL(endpointUrl))
: (new StreamableHTTPClientTransport(new URL(endpointUrl), {
fetch: makeFetchWithTimeout(requestTimeoutMs),
requestInit: {
headers: {
...clientVersionHeaders({ kind: 'mcp', runtimeVersion: RUNTIME_VERSION }),
...(opts.connectionId !== undefined
? { [MCP_CONNECTION_ID_HEADER]: opts.connectionId }
: {}),
},
},
}) as unknown as ShimTransport);
let closed = false;
const closeBoth = async (): Promise<void> => {
if (closed) return;
closed = true;
opts.onclose?.();
await Promise.allSettled([stdio.close(), http.close()]);
};
stdio.onerror = (err) => {
stderr.write(`[mcp-shim] stdio error: ${err.message}\n`);
};
http.onerror = (err) => {
stderr.write(`[mcp-shim] HTTP transport error: ${err.message}\n`);
};
stdio.onclose = () => {
void closeBoth();
};
http.onclose = () => {
void closeBoth();
};
let forwardQueue = Promise.resolve();
stdio.onmessage = (message) => {
forwardQueue = forwardQueue
.then(async () => {
try {
await http.send(message);
} catch (err) {
const id = requestIdOf(message);
if (id === undefined) {
stderr.write(
`[mcp-shim] failed to forward stdio notification: ${err instanceof Error ? err.message : String(err)}\n`,
);
return;
}
await stdio.send(toErrorResponse(id, err)).catch((sendErr) => {
stderr.write(
`[mcp-shim] failed to write stdio error response: ${sendErr instanceof Error ? sendErr.message : String(sendErr)}\n`,
);
});
}
})
.catch((err) => {
stderr.write(
`[mcp-shim] unexpected stdio forwarding failure: ${err instanceof Error ? err.message : String(err)}\n`,
);
});
};
http.onmessage = (message) => {
const protocolVersion = maybeProtocolVersion(message);
if (protocolVersion) http.setProtocolVersion?.(protocolVersion);
void stdio.send(message).catch((err) => {
stderr.write(
`[mcp-shim] failed to write stdio response: ${err instanceof Error ? err.message : String(err)}\n`,
);
});
};
try {
await http.start();
await stdio.start();
} catch (err) {
await closeBoth();
throw err;
}
return { close: closeBoth };
}
export async function startMcpShim(opts: StartMcpShimOptions): Promise<void> {
const stderr = opts.stderr ?? process.stderr;
const bridgeFn = opts.bridgeFn ?? bridgeStdioToHttpMcp;
const endpointUrl = await resolveMcpHttpUrl(opts);
const connectionId = opts.createConnectionId?.() ?? randomUUID();
let shuttingDown = false;
const keepalive = (opts.startKeepalive ?? defaultStartKeepalive)({
connectionId,
pid: process.pid,
resolveWsUrl: async () => resolveMcpKeepaliveWsUrl(opts, endpointUrl),
log: (msg) => stderr.write(`[mcp-shim] keepalive: ${msg}\n`),
});
stderr.write(`[mcp-shim] proxying stdio to ${endpointUrl}\n`);
let bridge: Awaited<ReturnType<typeof bridgeFn>>;
try {
bridge = await bridgeFn(endpointUrl, {
stderr,
connectionId,
onclose: () => {
if (!shuttingDown) {
keepalive.close();
process.exit(0);
}
},
});
} catch (err) {
keepalive.close();
throw err;
}
const shutdown = (): void => {
shuttingDown = true;
keepalive.close();
void bridge.close().finally(() => {
process.exit(0);
});
};
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);
}