@mohou/host 1.0.20

package/src/host/mcp-editor.ts

@@ -0,0 +1,205 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { isCredential, maskCredential, McpClient, McpError, resolveMcpConfig, resolveServerMap, type McpReferenceSources, type McpServerSpec } from '@mohou/mcp-client'
+
+import { hostMcpPath } from './layout.ts'
+import { admitMcpText } from './mcp-import.ts'
+import { mcpConfigEnv, mcpReferenceSources, resolveMcpServers, type ResolvedMcpServers } from './mcp.ts'
+
+/** One server the panel may edit. The file shape stays in the MCP client. */
+export interface McpEditorServer {
+  readonly id: string
+  readonly description?: string
+  readonly enabled?: boolean
+  readonly command?: string
+  readonly args?: readonly string[]
+  readonly env?: Readonly<Record<string, string>>
+  readonly url?: string
+  readonly transport?: 'sse' | 'streamable-http'
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+export interface McpCheck {
+  readonly ok: boolean
+  readonly tools: readonly {
+    readonly name: string
+    readonly description?: string
+    /** The protocol requires this one. */
+    readonly inputSchema?: Record<string, unknown>
+    /** Only a server that declares one sends it. */
+    readonly outputSchema?: Record<string, unknown>
+  }[]
+  readonly code?: string
+  readonly message?: string
+}
+
+/**
+ * Servers currently in the file. A missing default file is an empty list.
+ * @param runtimeRoot - directory that holds the default file
+ * @param env - process environment; only `MINI_APP_MCP_CONFIG` is read
+ * @param sanitize - mask the values that {@link isCredential} recognizes: a name segment that says
+ * credential, or a shape that gives it away. A caller whose output reaches a model or a log sets
+ * it; the panel reads the true values because it has to edit them.
+ */
+export async function readMcpEditor(
+  runtimeRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  sanitize = false,
+): Promise<McpEditorServer[]> {
+  const text = await readFile(mcpFile(runtimeRoot, env), 'utf8').catch(() => undefined)
+  if (text === undefined || text.trim().length === 0) return []
+  try {
+    const servers = admitMcpText(text)
+    return sanitize ? maskEditorServers(servers) : servers
+  } catch (error) {
+    if (error instanceof McpError && error.message === 'mcp import has no servers') return []
+    throw error
+  }
+}
+
+/**
+ * Replace the file with these servers and return the servers they resolved to, so a caller that
+ * holds a live client can hand it the same set it just wrote. The file keeps each reference itself.
+ * A server whose reference names nothing is left out of the return and listed in `failures`, the same
+ * way boot leaves it out. Invalid rows throw and the file stays. An explicit `MINI_APP_MCP_CONFIG`
+ * writes that path.
+ * @param sources - the lookups references resolve through
+ */
+export async function writeMcpEditor(
+  runtimeRoot: string,
+  servers: readonly McpEditorServer[],
+  env: NodeJS.ProcessEnv = process.env,
+  sources: McpReferenceSources = mcpReferenceSources(env),
+): Promise<ResolvedMcpServers> {
+  const resolved = editorToConfig(servers)
+  const body: Record<string, unknown> = {}
+  for (const server of servers) {
+    const spec = resolved[server.id]
+    if (spec === undefined) continue
+    const description = server.description?.trim()
+    body[server.id] = {
+      ...spec,
+      ...description === undefined || description.length === 0 ? {} : { description },
+      ...server.enabled === false ? { disabled: true } : {},
+    }
+  }
+  const file = mcpFile(runtimeRoot, env)
+  await mkdir(path.dirname(file), { recursive: true })
+  await writeFile(file, `${JSON.stringify(body, null, 2)}\n`, 'utf8')
+  return resolveMcpServers(resolved, sources)
+}
+
+/**
+ * Open one server and list its tools. Does not write the file.
+ * References resolve the same way boot resolves them, so a check that passes is a server that starts.
+ * The process is closed before this returns.
+ * @param server - the draft, references included
+ * @param env - process environment
+ * @param sources - the lookups references resolve through
+ */
+export async function checkMcpEditor(
+  server: McpEditorServer,
+  env: NodeJS.ProcessEnv = process.env,
+  sources: McpReferenceSources = mcpReferenceSources(env),
+): Promise<McpCheck> {
+  const resolved = editorToConfig([server])
+  let ready: Record<string, McpServerSpec>
+  try {
+    ready = await resolveServerMap(resolved, sources)
+  } catch (error) {
+    return {
+      ok: false,
+      tools: [],
+      code: error instanceof McpError ? error.code : 'mcp-start-failed',
+      message: error instanceof Error && error.message.length > 0 ? error.message : 'mcp server did not start',
+    }
+  }
+  const client = new McpClient(ready, env, 0)
+  try {
+    const tools = await client.listTools(server.id)
+    return {
+      ok: true,
+      tools: tools.map(tool => ({
+        name: tool.name,
+        ...tool.description === undefined ? {} : { description: tool.description },
+        inputSchema: tool.inputSchema,
+        ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema },
+      })),
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      tools: [],
+      code: error instanceof McpError ? error.code : 'mcp-start-failed',
+      message: error instanceof Error && error.message.length > 0 ? error.message : 'mcp server did not start',
+    }
+  } finally {
+    await client.dispose()
+  }
+}
+
+export function editorServers(resolved: Record<string, McpServerSpec>): McpEditorServer[] {
+  return Object.entries(resolved).map(([id, spec]) => {
+    if ('command' in spec) {
+      return {
+        id,
+        command: spec.command,
+        ...spec.args === undefined ? {} : { args: spec.args },
+        ...spec.env === undefined ? {} : { env: spec.env },
+      }
+    }
+    return {
+      id,
+      url: spec.url,
+      ...spec.transport === undefined ? {} : { transport: spec.transport },
+      ...spec.headers === undefined ? {} : { headers: spec.headers },
+    }
+  })
+}
+
+export function editorToConfig(servers: readonly McpEditorServer[]): Record<string, McpServerSpec> {
+  const raw: Record<string, unknown> = {}
+  for (const server of servers) {
+    if (server.id.trim().length === 0) throw new McpError('config-invalid', 'mcp server id is empty')
+    raw[server.id] = {
+      ...server.command === undefined ? {} : { command: server.command },
+      ...server.args === undefined ? {} : { args: [...server.args] },
+      ...server.env === undefined ? {} : { env: { ...server.env } },
+      ...server.url === undefined ? {} : { url: server.url },
+      ...server.transport === undefined ? {} : { transport: server.transport },
+      ...server.headers === undefined ? {} : { headers: { ...server.headers } },
+    }
+  }
+  return resolveMcpConfig(raw)
+}
+
+/** Mask the credential entries of a map. Keys stay, and an ordinary setting keeps its value. */
+/** The rows a caller that is not the file's owner may see: credential-shaped values masked. */
+export function maskEditorServers(rows: readonly McpEditorServer[]): McpEditorServer[] {
+  return rows.map(maskServer)
+}
+
+function maskServer(row: McpEditorServer): McpEditorServer {
+  return {
+    ...row,
+    ...row.env === undefined ? {} : { env: maskValues(row.env) },
+    ...row.headers === undefined ? {} : { headers: maskValues(row.headers) },
+  }
+}
+
+function maskValues(values: Readonly<Record<string, string>>): Record<string, string> {
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, isCredential(key, value) ? maskCredential(value) : value]))
+}
+
+/** Read one import file. Shell chooses the path. Host does not name another product's home. */
+export async function readMcpImport(file: string): Promise<McpEditorServer[]> {
+  const text = await readFile(file, 'utf8').catch(() => undefined)
+  if (text === undefined) throw new McpError('config-invalid', `mcp import is missing: ${file}`)
+  return admitMcpText(text)
+}
+
+function mcpFile(runtimeRoot: string, env: NodeJS.ProcessEnv): string {
+  const override = env[mcpConfigEnv]
+  return typeof override === 'string' && override.length > 0 ? override : hostMcpPath(runtimeRoot)
+}

package/src/host/mcp-import.ts

@@ -0,0 +1,141 @@
+import { McpError } from '@mohou/mcp-client'
+
+import type { McpEditorServer } from './mcp-editor.ts'
+
+const commandKeys = ['command', 'cmd'] as const
+const urlKeys = ['url', 'serverUrl', 'baseUrl', 'endpoint'] as const
+
+/**
+ * Turn pasted or file text into editor servers.
+ * A fragment without braces is wrapped. A map, an `mcpServers` object, and one server object are accepted.
+ * Other editors' field names are mapped onto command, args, url, and env.
+ */
+export function admitMcpText(raw: string): McpEditorServer[] {
+  const text = brace(stripFence(raw.trim()))
+  if (text.length === 0) throw new McpError('config-invalid', 'mcp import is empty')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text) as unknown
+  } catch (error) {
+    throw new McpError('config-invalid', 'mcp import is not JSON', { cause: error })
+  }
+  return admitParsed(parsed)
+}
+
+function admitParsed(value: unknown): McpEditorServer[] {
+  if (Array.isArray(value)) return value.flatMap((item, index) => oneServer(item, `server-${index + 1}`))
+  if (!isRecord(value)) throw new McpError('config-invalid', 'mcp import must be an object')
+  const wrapped = isRecord(value.mcpServers) ? value.mcpServers : value
+  if (isServerEntry(wrapped)) return oneServer(wrapped, nameOf(wrapped) ?? 'imported')
+  const servers: McpEditorServer[] = []
+  for (const [id, entry] of Object.entries(wrapped)) {
+    if (id === 'settings') continue
+    servers.push(...oneServer(entry, id))
+  }
+  if (servers.length === 0) throw new McpError('config-invalid', 'mcp import has no servers')
+  return servers
+}
+
+function oneServer(value: unknown, fallbackId: string): McpEditorServer[] {
+  if (!isRecord(value)) return []
+  const id = (nameOf(value) ?? fallbackId).trim()
+  if (id.length === 0 || id === 'settings') return []
+  const command = stringField(value, commandKeys)
+  const url = stringField(value, urlKeys)
+  const kind = transportOf(value.transport ?? value.type)
+  const args = argsOf(value.args ?? value.arguments ?? value.arg)
+  const env = recordOf(value.env ?? value.environment ?? value.envVars)
+  const headers = recordOf(value.headers)
+  const description = descriptionOf(value)
+  const note = description === undefined ? {} : { description }
+  const remote = kind === 'sse' || kind === 'http' || (url !== undefined && command === undefined)
+  if (remote && url !== undefined) {
+    return [flagged({
+      id,
+      url,
+      transport: kind === 'sse' ? 'sse' : 'streamable-http',
+      ...headers === undefined ? {} : { headers },
+      ...env === undefined ? {} : { env },
+      ...note,
+    }, value)]
+  }
+  if (command === undefined) return []
+  return [flagged({
+    id,
+    command,
+    ...args === undefined ? {} : { args },
+    ...env === undefined ? {} : { env },
+    ...note,
+  }, value)]
+}
+
+function flagged(server: McpEditorServer, value: Record<string, unknown>): McpEditorServer {
+  return value.disabled === true || value.enabled === false ? { ...server, enabled: false } : server
+}
+
+function nameOf(value: Record<string, unknown>): string | undefined {
+  if (typeof value.name === 'string' && value.name.trim().length > 0) return value.name.trim()
+  return undefined
+}
+
+function isServerEntry(value: Record<string, unknown>): boolean {
+  return stringField(value, [...commandKeys, ...urlKeys]) !== undefined || value.transport !== undefined || value.type !== undefined
+}
+
+function descriptionOf(value: Record<string, unknown>): string | undefined {
+  if (typeof value.description === 'string' && value.description.trim().length > 0) return value.description.trim()
+  const meta = value._monkeyagent
+  if (!isRecord(meta) || typeof meta.description !== 'string') return undefined
+  const text = meta.description.trim()
+  return text.length === 0 ? undefined : text
+}
+
+function transportOf(value: unknown): 'stdio' | 'sse' | 'http' | undefined {
+  if (typeof value !== 'string') return undefined
+  const text = value.trim().toLowerCase()
+  if (text === 'stdio' || text === 'local' || text.startsWith('stdio')) return 'stdio'
+  if (text === 'sse' || text.startsWith('sse')) return 'sse'
+  if (text === 'http' || text.startsWith('http') || text === 'streamable-http' || text === 'streamable_http') return 'http'
+  return undefined
+}
+
+function stringField(value: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const item = value[key]
+    if (typeof item === 'string' && item.trim().length > 0) return item.trim()
+  }
+  return undefined
+}
+
+function argsOf(value: unknown): string[] | undefined {
+  if (typeof value === 'string') {
+    const args = value.split(/\s+/).filter(item => item.length > 0)
+    return args.length === 0 ? undefined : args
+  }
+  if (!Array.isArray(value)) return undefined
+  const args = value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return args.length === 0 ? undefined : args
+}
+
+function recordOf(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) return undefined
+  const record: Record<string, string> = {}
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item === 'string') record[key] = item
+  }
+  return Object.keys(record).length === 0 ? undefined : record
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function stripFence(text: string): string {
+  const fenced = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)
+  return (fenced?.[1] ?? text).trim()
+}
+
+function brace(text: string): string {
+  if (text.startsWith('{') || text.startsWith('[')) return text
+  return `{${text}}`
+}

package/src/host/mcp.ts

@@ -0,0 +1,109 @@
+import { readFile } from 'node:fs/promises'
+
+import { McpError, resolveMcpConfig, resolveServerValues, type McpReferenceSources, type McpServerSpec } from '@mohou/mcp-client'
+
+import type { CredentialProvider } from '../credentials/provider.ts'
+import { hostMcpPath } from './layout.ts'
+
+/** Explicit config path. Set means that file, not a search of another home. */
+export const mcpConfigEnv = 'MINI_APP_MCP_CONFIG'
+
+/**
+ * The lookups a `${env:NAME}` or `${credential:NAME}` reference resolves through.
+ * Host binds them here and nowhere else: the environment, and the credential interface Shell
+ * injects. Another credential implementation — a system keychain, say — changes the binding
+ * Shell passes and not the resolver, nor any caller of it.
+ * @param env - process environment
+ * @param credentials - the read port, when Shell injected one
+ */
+export function mcpReferenceSources(env: NodeJS.ProcessEnv, credentials?: CredentialProvider): McpReferenceSources {
+  return {
+    env: name => env[name],
+    credential: credentials === undefined ? () => undefined : name => credentials.get(name),
+  }
+}
+
+/** A server that is not started, and why. `code` is the MCP client's own code. */
+export interface McpLoadFailure {
+  readonly id: string
+  readonly code: string
+  readonly message: string
+}
+
+export interface ResolvedMcpServers {
+  readonly servers: Record<string, McpServerSpec>
+  /** One entry per server a reference left unresolvable. Those servers do not start. */
+  readonly failures: readonly McpLoadFailure[]
+}
+
+/**
+ * Resolve one admitted map, one server at a time. A reference that names nothing leaves that server
+ * out and reports it; the value never becomes an empty string. Boot and a write share this rule, so a
+ * file written at runtime reads back the way the next boot would read it.
+ * @param admitted - servers a config read accepted
+ * @param sources - the lookups references resolve through
+ */
+export async function resolveMcpServers(
+  admitted: Record<string, McpServerSpec>,
+  sources: McpReferenceSources,
+): Promise<ResolvedMcpServers> {
+  const servers: Record<string, McpServerSpec> = {}
+  const failures: McpLoadFailure[] = []
+  for (const [id, spec] of Object.entries(admitted)) {
+    try {
+      servers[id] = await resolveServerValues(spec, sources, id)
+    } catch (error) {
+      failures.push({
+        id,
+        code: error instanceof McpError ? error.code : 'config-invalid',
+        message: error instanceof Error && error.message.length > 0 ? error.message : 'server value did not resolve',
+      })
+    }
+  }
+  return { servers, failures }
+}
+
+/**
+ * Read MCP servers for Host boot, and resolve the references in them.
+ * A missing default file is zero servers. A present bad file, or a missing explicit path, fails boot:
+ * the file itself is unusable. A reference that names nothing is not the same class — that one server
+ * is left out and reported in `failures`, so the host still serves the panel that can fix it. The
+ * value never falls back to an empty string either way.
+ * @param runtimeRoot - directory that contains the default file
+ * @param env - process environment; only {@link mcpConfigEnv} is read
+ * @param sources - the lookups references resolve through
+ */
+export async function loadMcpServers(
+  runtimeRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  sources: McpReferenceSources = mcpReferenceSources(env),
+): Promise<ResolvedMcpServers> {
+  const override = env[mcpConfigEnv]
+  const explicit = typeof override === 'string' && override.length > 0
+  const file = explicit ? override : hostMcpPath(runtimeRoot)
+  const text = await readFile(file, 'utf8').catch(() => undefined)
+  if (text === undefined) {
+    if (explicit) throw new McpError('config-invalid', `mcp config is missing: ${file}`)
+    return { servers: {}, failures: [] }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text) as unknown
+  } catch (error) {
+    throw new McpError('config-invalid', 'mcp config is not JSON', { cause: error })
+  }
+  return resolveMcpServers(resolveMcpConfig(omitDisabled(parsed)), sources)
+}
+
+function omitDisabled(value: unknown): unknown {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return value
+  const record = value as Record<string, unknown>
+  const wrapped = typeof record.mcpServers === 'object' && record.mcpServers !== null && !Array.isArray(record.mcpServers)
+  const source = wrapped ? record.mcpServers as Record<string, unknown> : record
+  const next: Record<string, unknown> = {}
+  for (const [id, entry] of Object.entries(source)) {
+    if (typeof entry === 'object' && entry !== null && 'disabled' in entry && entry.disabled === true) continue
+    next[id] = entry
+  }
+  return wrapped ? { ...record, mcpServers: next } : next
+}

package/src/host/port.ts

@@ -0,0 +1,83 @@
+import { createServer } from 'node:net'
+
+import { DEFAULT_PORT_BOUND, type PortBound } from './config.ts'
+
+/** How many successive ports to probe after the preferred one. Host policy, not locked. */
+export const HOST_PORT_PROBE_SPAN = 64
+
+/**
+ * Preferred port is busy on an existing `host.json`.
+ * Start does not rebind or rewrite the file; the caller offers a confirm path.
+ */
+export class PortInUseError extends Error {
+  readonly code = 'port-in-use' as const
+  readonly busyPort: number
+  readonly suggestedPort: number
+
+  constructor(busyPort: number, suggestedPort: number) {
+    super(`port ${busyPort} is in use`)
+    this.name = 'PortInUseError'
+    this.busyPort = busyPort
+    this.suggestedPort = suggestedPort
+  }
+}
+
+export function isPortInUseError(error: unknown): error is PortInUseError {
+  return error instanceof PortInUseError
+    || (typeof error === 'object' && error !== null && 'code' in error && error.code === 'port-in-use'
+      && 'busyPort' in error && 'suggestedPort' in error)
+}
+
+/** True when loopback can bind `port` right now. */
+export function isHostPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', () => {
+      resolve(false)
+    })
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => {
+        resolve(true)
+      })
+    })
+  })
+}
+
+/**
+ * First free loopback port at or above `preferred` within the probe span and bound.
+ * Falls back to an ephemeral OS port when the span is exhausted.
+ */
+export async function allocateHostPort(
+  preferred: number,
+  ports: PortBound = DEFAULT_PORT_BOUND,
+  span = HOST_PORT_PROBE_SPAN,
+): Promise<number> {
+  const start = clampPort(preferred, ports)
+  const last = Math.min(ports.max, start + span - 1)
+  for (let port = start; port <= last; port++) {
+    if (await isHostPortFree(port)) return port
+  }
+  return ephemeralHostPort()
+}
+
+function clampPort(port: number, ports: PortBound): number {
+  if (!Number.isInteger(port)) return ports.min
+  if (port < ports.min) return ports.min
+  if (port > ports.max) return ports.max
+  return port
+}
+
+function ephemeralHostPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address !== null ? address.port : 0
+      server.close((error) => {
+        if (error) reject(error)
+        else resolve(port)
+      })
+    })
+  })
+}