Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { execFile } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { realpathSync, statSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';
import { OK_PROJECT_MARKER, resolveIsHostedAgent } from '@inkeep/open-knowledge-core';
import { type KeepaliveHandle, startKeepalive } from '@inkeep/open-knowledge-core/keepalive';
import { filesystemIdentity } from '@inkeep/open-knowledge-core/server';
import {
type AgentIdentity,
type Config,
getLocalDir,
installJsonSchemaDialect,
installPrettyZodErrors,
isProjectRoot,
MCP_SERVER_NAME,
RUNTIME_VERSION,
registerAllTools,
resolveContentDir,
sanitizeClientName,
withHiddenWindowsConsole,
} from '@inkeep/open-knowledge-server';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { createProjectConfigResolver } from '../config/loader.ts';
import {
type BundleIdentityWatcherHandle,
captureBootIdentity,
detectBundleIdentity,
formatBootIdentityLine,
formatBundleReplacedLine,
startBundleIdentityWatcher,
} from './bundle-identity.ts';
import { type HostLivenessWatchHandle, startHostLivenessWatch } from './host-liveness.ts';
import { attachLifecycleLogging } from './lifecycle-logging.ts';
import { parseSpawnTimeoutEnv, resolveMcpHttpUrl, resolveMcpKeepaliveWsUrl } from './shim.ts';
import { createMcpStderrMirror } from './stderr-mirror.ts';
const execFileAsync = promisify(execFile);
export async function countWorktrees(dir: string): Promise<number> {
try {
const { stdout } = await execFileAsync(
'git',
['-C', dir, 'worktree', 'list', '--porcelain'],
withHiddenWindowsConsole({
timeout: 2000,
}),
);
return stdout.split('\n').filter((line) => line.startsWith('worktree ')).length;
} catch {
return 0;
}
}
interface StartGlobalMcpServerOptions {
startupCwd: string;
startupConfig: Config;
bundleAnchorPath: string | undefined;
spawnTimeoutMs?: number;
envAutoStart?: string;
}
interface StartGlobalMcpServerHandle {
close: () => Promise<void>;
}
export function findProjectDir(startCwd: string): string {
let dir = resolve(startCwd);
while (true) {
if (isProjectRoot(dir)) return dir;
const parent = dirname(dir);
if (parent === dir) {
throw new Error(
`No OpenKnowledge project found at or above ${startCwd}. Pass an explicit \`cwd\` argument that points inside an OK project (a directory with a \`${OK_PROJECT_MARKER}\`).`,
);
}
dir = parent;
}
}
export function rootUriToFsPath(uri: string): string | undefined {
try {
const parsed = new URL(uri);
if (parsed.protocol !== 'file:') return undefined;
return fileURLToPath(parsed);
} catch {
return undefined;
}
}
export async function tryListRootsFallback(opts: {
getClientCapabilities: () => { roots?: unknown } | undefined;
listRoots: () => Promise<{ roots: { uri: string }[] }>;
log?: (msg: string) => void;
}): Promise<string | undefined> {
const caps = opts.getClientCapabilities();
if (!caps?.roots) return undefined;
let result: { roots: { uri: string }[] };
try {
result = await opts.listRoots();
} catch (err) {
opts.log?.(`listRoots fallback failed: ${err instanceof Error ? err.message : String(err)}`);
return undefined;
}
const roots = result.roots ?? [];
if (roots.length !== 1) return undefined;
const fsPath = rootUriToFsPath(roots[0].uri);
if (fsPath === undefined) {
opts.log?.(`single root URI not usable as fs path: ${roots[0].uri}`);
}
return fsPath;
}
export interface StickyProjectResolution {
projectDir: string | undefined;
viaRootGuess: boolean;
nextSticky: string | undefined;
}
export async function resolveStickyProjectDir(
explicit: string | undefined,
sticky: string | undefined,
rootsFallback: () => Promise<string | undefined>,
findProject: (startCwd: string) => string = findProjectDir,
): Promise<StickyProjectResolution> {
if (explicit !== undefined) {
const pd = findProject(explicit);
return { projectDir: pd, viaRootGuess: false, nextSticky: pd };
}
if (sticky !== undefined) {
const pd = findProject(sticky);
return { projectDir: pd, viaRootGuess: false, nextSticky: pd };
}
const fromRoots = await rootsFallback();
if (fromRoots === undefined) {
return { projectDir: undefined, viaRootGuess: false, nextSticky: undefined };
}
return { projectDir: findProject(fromRoots), viaRootGuess: true, nextSticky: undefined };
}
const CWD_REQUIRED_MESSAGE =
'`cwd` is required for tool calls against the global MCP server. Pass an absolute path inside an OpenKnowledge project, or have the MCP client advertise a single root.';
export async function startGlobalMcpServer(
opts: StartGlobalMcpServerOptions,
): Promise<StartGlobalMcpServerHandle> {
const mirror = createMcpStderrMirror();
const stderr = {
write: (chunk: string): boolean => {
mirror.write(chunk);
return process.stderr.write(chunk);
},
};
const spawnTimeoutMs =
opts.spawnTimeoutMs ?? parseSpawnTimeoutEnv(process.env.OK_MCP_SPAWN_TIMEOUT_MS);
const envAutoStart = opts.envAutoStart ?? process.env.OK_MCP_AUTOSTART;
const resolveConfigForCwd = createProjectConfigResolver({
startupCwd: opts.startupCwd,
startupConfig: opts.startupConfig,
});
const server = new McpServer({
name: MCP_SERVER_NAME,
version: RUNTIME_VERSION,
});
installPrettyZodErrors(server);
const connectionId = randomUUID();
const identityRef: { current: AgentIdentity } = {
current: {
connectionId,
displayName: connectionId,
colorSeed: connectionId,
},
};
const keepalivesByProject = new Map<string, KeepaliveHandle>();
const ensureKeepaliveForProject = (projectDir: string): void => {
if (keepalivesByProject.has(projectDir)) return;
const lockDir = getLocalDir(projectDir);
const id = identityRef.current;
const handle = startKeepalive({
connectionId,
pid: process.pid,
displayName: id.displayName,
clientName: id.clientInfo?.name ?? id.displayName,
colorSeed: id.colorSeed,
resolveWsUrl: async () => resolveMcpKeepaliveWsUrl({ lockDir }, ''),
log: (msg) => stderr.write(`[mcp] keepalive[${projectDir}]: ${msg}\n`),
});
keepalivesByProject.set(projectDir, handle);
};
const rootsFallback = (): Promise<string | undefined> =>
tryListRootsFallback({
getClientCapabilities: () => server.server.getClientCapabilities(),
listRoots: () => server.server.listRoots() as Promise<{ roots: { uri: string }[] }>,
log: (msg) => stderr.write(`[mcp] ${msg}\n`),
});
let stickyProjectDir: string | undefined;
let warnedWorktreeAmbiguity = false;
const maybeWarnWorktreeAmbiguity = async (projectDir: string): Promise<void> => {
if (warnedWorktreeAmbiguity) return;
warnedWorktreeAmbiguity = true;
const count = await countWorktrees(projectDir);
if (count <= 1) {
warnedWorktreeAmbiguity = false;
return;
}
const msg =
`Routed to ${projectDir} from the MCP client's single advertised root, but this repo ` +
`has ${count} git worktrees. If you are working in a worktree, pass its path as \`cwd\` on ` +
`OK tool calls once — it sticks for the session, so reads, writes, and the preview all ` +
`target that worktree instead of this checkout.`;
try {
stderr.write(`[mcp] ${msg}\n`);
await server.server.sendLoggingMessage({ level: 'warning', data: msg });
} catch {}
};
const resolveCwd = async (explicit?: string): Promise<string> => {
const r = await resolveStickyProjectDir(explicit, stickyProjectDir, rootsFallback);
stickyProjectDir = r.nextSticky ?? stickyProjectDir;
if (r.projectDir === undefined) throw new Error(CWD_REQUIRED_MESSAGE);
if (r.viaRootGuess) void maybeWarnWorktreeAmbiguity(r.projectDir);
return r.projectDir;
};
const resolveServerUrlForCwd = async (cwd?: string): Promise<string | undefined> => {
const r = await resolveStickyProjectDir(cwd, stickyProjectDir, rootsFallback);
stickyProjectDir = r.nextSticky ?? stickyProjectDir;
if (r.projectDir === undefined) return undefined;
if (r.viaRootGuess) void maybeWarnWorktreeAmbiguity(r.projectDir);
const projectDir = r.projectDir;
const config = await resolveConfigForCwd(projectDir);
const mcpUrl = await resolveMcpHttpUrl({
projectDir,
lockDir: getLocalDir(projectDir),
contentDir: resolveContentDir(config, projectDir),
envAutoStart,
...(spawnTimeoutMs !== undefined ? { timeoutMs: spawnTimeoutMs } : {}),
});
ensureKeepaliveForProject(projectDir);
return mcpUrl.replace(/\/mcp$/, '');
};
server.server.oninitialized = () => {
const clientInfo = server.server.getClientVersion();
const name = sanitizeClientName(clientInfo?.name, connectionId);
identityRef.current = {
connectionId,
clientInfo: clientInfo ? { name, version: clientInfo.version } : undefined,
displayName: name,
colorSeed: name,
};
};
registerAllTools(server, {
serverUrl: resolveServerUrlForCwd,
resolveCwd,
config: resolveConfigForCwd,
identityRef,
isHostedAgent: resolveIsHostedAgent(process.env),
});
installJsonSchemaDialect(server);
const transport = new StdioServerTransport();
let closed = false;
let bundleWatcher: BundleIdentityWatcherHandle | undefined;
let hostLiveness: HostLivenessWatchHandle | undefined;
const close = async (): Promise<void> => {
if (closed) return;
closed = true;
bundleWatcher?.stop();
hostLiveness?.stop();
for (const handle of keepalivesByProject.values()) {
try {
handle.close();
} catch (err) {
stderr.write(
`[mcp] keepalive close error: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}
keepalivesByProject.clear();
const results = await Promise.allSettled([server.close(), transport.close()]);
for (const result of results) {
if (result.status === 'rejected') {
const err = result.reason;
stderr.write(
`[mcp] shutdown close error: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}
};
await server.connect(transport);
stderr.write('[mcp] global stdio server ready (per-call project routing)\n');
let shuttingDown = false;
const shutdown = (): void => {
if (shuttingDown) return;
shuttingDown = true;
setTimeout(() => {
stderr.write('[mcp] shutdown deadline (5s) reached — forcing exit(1)\n');
process.exit(1);
}, 5000).unref();
void close().finally(() => {
process.exit(0);
});
};
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);
process.stdin.on('end', () => {
stderr.write('[mcp] stdin end — host disconnected, shutting down\n');
shutdown();
});
process.stdin.on('error', (err) => {
stderr.write(
`[mcp] stdin error (${err instanceof Error ? err.message : String(err)}) — host disconnected, shutting down\n`,
);
shutdown();
});
hostLiveness = startHostLivenessWatch({
getPpid: () => process.ppid,
onHostGone: (reason) => {
stderr.write(`[mcp] ${reason} — shutting down\n`);
shutdown();
},
});
attachLifecycleLogging({
log: (m) => stderr.write(`${m}\n`),
transport,
process,
stdin: process.stdin,
});
const bundleAnchorPath = process.platform === 'darwin' ? opts.bundleAnchorPath : undefined;
if (process.platform === 'darwin' && bundleAnchorPath === undefined) {
stderr.write('[mcp] bundle identity watcher off: no CLI entry path was recorded\n');
}
if (bundleAnchorPath !== undefined) {
const bootIdentity = captureBootIdentity(bundleAnchorPath, {
realpathSync,
statInoSync: (p) => filesystemIdentity(statSync(p, { bigint: true })),
log: (m) => stderr.write(`${m}\n`),
});
if (bootIdentity !== undefined) {
stderr.write(`${formatBootIdentityLine(bootIdentity, RUNTIME_VERSION)}\n`);
const { resolvedPath: capturedAnchorPath, inode: capturedInode } = bootIdentity;
bundleWatcher = startBundleIdentityWatcher({
detect: () =>
detectBundleIdentity({
bundleAnchorPath,
currentInode: capturedInode,
platform: process.platform,
realpath: realpathSync,
statInode: (p) => filesystemIdentity(statSync(p, { bigint: true })),
}),
onReplaced: (state) => {
stderr.write(`${formatBundleReplacedLine(capturedAnchorPath, state, RUNTIME_VERSION)}\n`);
shutdown();
},
log: (msg) => stderr.write(`[mcp] ${msg}\n`),
});
}
}
return { close };
}