@auggieteo/dsh-mcp-adapter 0.2.2 → 0.4.0

package/src/host/index.js

@@ -4,69 +4,92 @@ import { createMcpConnection } from './mcp-connection.js'
 import { installMcpOauthCommands } from './oauth-commands.js'
 import { createFileTokenStore } from './oauth.js'
 import { installMcpOauth } from './oauth-service.js'
+import { importLegacyMcpSettings } from './legacy-import.js'
 import { installMcpPromptCommand } from './prompt-commands.js'
 import { installMcpPromotions } from './promotions.js'
 import { installMcpProxyTool } from './proxy-tool.js'
-import { installMcpSettings } from './settings.js'
+import { createMcpConfigScope, McpConfigSchema } from './settings.js'
 import { installMcpSkill } from './skill.js'
 import { installWorkspaceLayer } from './workspace-config.js'
 
 export const name = 'dsh-mcp-adapter'
 
-// Settings and Timer are optional at the Adapter row. The manager starts only
-// while both Services exist, but the Config namespace can exist without Timer.
+// 0.1.7 model: the Adapter's configuration is its Loader-entry Config (the
+// `Config` schema below), always readable from `ctx.config`; Timer is only
+// needed by the connection manager, and Settings by writes and the page.
 export const inject = []
 
+export const Config = McpConfigSchema
+
 export function apply(ctx) {
   // The bundled agent skill is independent of every other Adapter feature: a
-  // deployment without the skills service simply gets no skill entry. Sibling
-  // inject fibers run in registration order while the services exist, so the
-  // settings callback reads `skillInstall` before the skills callback runs;
-  // without the settings service the skill module's 'file' default applies.
-  let skillInstall
-  installMcpSettings(ctx, (settingsCtx, scope) => {
-    skillInstall = scope.get()?.skillInstall
-    const layeredScope = installWorkspaceLayer(settingsCtx, scope)
-    settingsCtx.inject(['timer'], (managerCtx) => {
-      const store = createFileTokenStore()
-      let oauth
-      const manager = installMcpManager(managerCtx, layeredScope, {
-        connectionFactory: (serverName, config, callbacks, signal, sdk) =>
-          createMcpConnection(serverName, config, callbacks, signal, sdk, {
-            store,
-            onAuthorizationRequired: (url) =>
-              oauth?.noteAuthorizationRequired(serverName, url),
-          }),
-      })
-      // The OAuth controller and every command read the LAYERED scope, so a
-      // workspace-defined Server is signable and status-visible. Writes still
-      // land in the global namespace: the layered scope forwards them there.
-      oauth = installMcpOauth(managerCtx, manager, layeredScope, { store })
-      managerCtx.inject(['connection'], (rpcCtx) => {
-        installMcpManagerRpc(rpcCtx, manager, {
-          // Refresh the workspace layer before each snapshot, giving the
-          // Settings page poll a real refresh path for a file created after
-          // startup.
-          layerSnapshot: async () => {
-            await layeredScope.refreshLayers()
-            return layeredScope.layerSnapshot()
-          },
-          oauth,
-        })
-      })
-      installMcpCommands(managerCtx, manager, layeredScope)
-      installMcpOauthCommands(managerCtx, layeredScope, oauth)
-      installMcpPromptCommand(managerCtx, manager)
-      managerCtx.inject(['tools'], (toolCtx) => {
-        installMcpProxyTool(toolCtx, manager)
-        installMcpPromotions(toolCtx, manager, layeredScope)
+  // deployment without the skills service simply gets no skill entry.
+  // `skillInstall` is read once here, from the entry Config.
+  const scope = createMcpConfigScope(ctx)
+  ctx.effect(() => () => scope.dispose(), 'dsh-mcp-adapter: config scope')
+  const skillInstall = scope.get().skillInstall
+  const layeredScope = installWorkspaceLayer(ctx, scope)
+
+  // The Adapter owns a hand-built Settings page, so the shell must not also
+  // auto-generate a form page for this entry. While the settings service is
+  // mounted, also finish the one-time legacy import after the Loader settles:
+  // the platform renames settings.yaml and imports same-named sections only,
+  // so the `mcp` section under our `mcp-adapter` entry id is left behind.
+  let disposed = false
+  ctx.effect(() => () => {
+    disposed = true
+  }, 'dsh-mcp-adapter: fiber disposal flag')
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.effect(
+      () => settingsCtx.settings.configure({ auto: false }, ctx.fiber),
+      'dsh-mcp-adapter: settings presentation',
+    )
+    void ctx.root.loader
+      .await()
+      .then(() => (disposed ? undefined : importLegacyMcpSettings(settingsCtx)))
+      .catch((error) => settingsCtx.logger?.warn?.(error))
+  })
+
+  ctx.inject(['timer'], (managerCtx) => {
+    const store = createFileTokenStore()
+    let oauth
+    const manager = installMcpManager(managerCtx, layeredScope, {
+      connectionFactory: (serverName, config, callbacks, signal, sdk) =>
+        createMcpConnection(serverName, config, callbacks, signal, sdk, {
+          store,
+          onAuthorizationRequired: (url) =>
+            oauth?.noteAuthorizationRequired(serverName, url),
+        }),
+    })
+    // The OAuth controller and every command read the LAYERED scope, so a
+    // workspace-defined Server is signable and status-visible. Writes still
+    // land in the entry Config: the layered scope forwards them there.
+    oauth = installMcpOauth(managerCtx, manager, layeredScope, { store })
+    managerCtx.inject(['connection'], (rpcCtx) => {
+      installMcpManagerRpc(rpcCtx, manager, {
+        // Refresh the workspace layer before each snapshot, giving the
+        // Settings page poll a real refresh path for a file created after
+        // startup.
+        layerSnapshot: async () => {
+          await layeredScope.refreshLayers()
+          return layeredScope.layerSnapshot()
+        },
+        oauth,
       })
     })
+    installMcpCommands(managerCtx, manager, layeredScope)
+    installMcpOauthCommands(managerCtx, layeredScope, oauth)
+    installMcpPromptCommand(managerCtx, manager)
+    managerCtx.inject(['tools'], (toolCtx) => {
+      installMcpProxyTool(toolCtx, manager)
+      installMcpPromotions(toolCtx, manager, layeredScope)
+    })
   })
   ctx.inject(['skills'], (skillCtx) => installMcpSkill(skillCtx, { skillInstall }))
 }
 
 export * from './commands.js'
+export * from './legacy-import.js'
 export * from './manager.js'
 export * from './mcp-connection.js'
 export * from './oauth-commands.js'

package/src/host/legacy-import.js

@@ -0,0 +1,121 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
+import {
+  MCP_SETTINGS_NAMESPACE,
+  McpConfigSchema,
+  validateMcpSettings,
+} from './settings.js'
+import { errorMessage } from './errors.js'
+
+// 0.1.7 importLegacyDocument renames the profile's settings.yaml to
+// settings.yaml.imported and moves only sections whose name matches a Loader
+// entry id. The Adapter's legacy section is `mcp` while its entry id is
+// `mcp-adapter`, so the platform leaves it behind; this import finishes the
+// migration exactly once per profile.
+const LEGACY_DOCUMENT_NAMES = ['settings.yaml.imported', 'settings.yaml']
+const LEGACY_SECTION = 'mcp'
+const MARKER_NAME = 'mcp-adapter.legacy-imported'
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Whether the entry still answers with pure defaults and no user section. */
+function isUntouched(descriptor) {
+  if (descriptor === undefined) return false
+  const user = descriptor.user
+  if (user !== undefined && Object.keys(user).length > 0) return false
+  const value = descriptor.value
+  if (!isPlainObject(value)) return true
+  return Object.keys(value.mcpServers ?? {}).length === 0
+}
+
+/**
+ * Import the removed settings.yaml `mcp` section into this entry's profile
+ * Config once. Runs after the Loader settles (the platform import runs first
+ * and skips our mismatched section name). A `user` section or non-default
+ * servers on the entry mean the config was already written, so the legacy
+ * data stays untouched in the imported document; failures only warn, they
+ * never throw. On success a marker file prevents re-import, so deliberately
+ * clearing every Server later never resurrects the legacy list.
+ */
+export async function importLegacyMcpSettings(ctx, deps = {}) {
+  const settings = deps.settings ?? ctx.get('settings')
+  const profileContext = deps.profileContext ?? ctx.get('profileContext')
+  const logger = deps.logger ?? ctx.logger
+  if (settings === undefined || profileContext?.home === undefined) return
+
+  const home = profileContext.home
+  const readFileFn = deps.readFile ?? ((path) => readFile(path, 'utf8'))
+  const writeFileFn = deps.writeFile ?? ((path, text) => writeFile(path, text))
+  const markerPath = join(home, MARKER_NAME)
+
+  try {
+    try {
+      await readFileFn(markerPath)
+      return // already imported for this profile
+    } catch {
+      // No marker yet; continue.
+    }
+
+    let documentPath
+    let sections
+    for (const name of LEGACY_DOCUMENT_NAMES) {
+      let text
+      try {
+        text = await readFileFn(join(home, name))
+      } catch {
+        continue
+      }
+      const parsed = parseYaml(text)
+      if (isPlainObject(parsed) && isPlainObject(parsed[LEGACY_SECTION])) {
+        documentPath = join(home, name)
+        sections = parsed
+        break
+      }
+    }
+    if (documentPath === undefined) return
+
+    const descriptor = settings
+      .describe({ redactSecrets: true })
+      .find((entry) => entry.ns === MCP_SETTINGS_NAMESPACE)
+    if (!isUntouched(descriptor)) {
+      logger?.info?.(
+        'dsh-mcp-adapter: %s already has written Config; the legacy "mcp" section in %s was left in place',
+        MCP_SETTINGS_NAMESPACE,
+        documentPath,
+      )
+      return
+    }
+
+    // Keep only fields this entry declares; anything else in the legacy
+    // section would make the reloaded entry fail schema validation.
+    const legacy = sections[LEGACY_SECTION]
+    const section = {
+      mcpServers: isPlainObject(legacy.mcpServers) ? legacy.mcpServers : {},
+      ...(typeof legacy.skillInstall === 'string'
+        ? { skillInstall: legacy.skillInstall }
+        : {}),
+    }
+    const resolved = McpConfigSchema(section)
+    validateMcpSettings({
+      mcpServers: resolved.mcpServers.get(),
+      skillInstall: resolved.skillInstall.get(),
+    })
+
+    await settings.update(MCP_SETTINGS_NAMESPACE, section)
+    await writeFileFn(markerPath, `imported the "${LEGACY_SECTION}" section of ${documentPath}\n`)
+    logger?.info?.(
+      'dsh-mcp-adapter: imported the legacy "mcp" settings section from %s into the %s entry',
+      documentPath,
+      MCP_SETTINGS_NAMESPACE,
+    )
+  } catch (error) {
+    logger?.warn?.(
+      'dsh-mcp-adapter: legacy "mcp" settings import failed; copy the "mcp" section into the profile manually: %s',
+      errorMessage(error),
+    )
+  }
+}

package/src/host/settings.js

@@ -1,10 +1,11 @@
 import z from '@deepseek-ai/schemastery'
 
-// The plain namespace string works on both supported harness generations:
-// DSH 0.1.1-rc.2 brands it via the (removed-in-0.1.2-rc.1) `settingsNamespace`
-// export, while 0.1.2-rc.1 validates the raw string inside `register` itself.
-// Branding was type-only, so no runtime behavior changes either way.
-export const MCP_SETTINGS_NAMESPACE = 'mcp'
+import { errorMessage } from './errors.js'
+
+// DSH 0.1.7 replaced the registered-namespace settings model with profile
+// Loader-entry Config: the Adapter's configuration IS its entry Config, so
+// the settings namespace identity is the entry id from cordis.patch.yml.
+export const MCP_SETTINGS_NAMESPACE = 'mcp-adapter'
 
 const optionalString = () => z.string().required(false)
 
@@ -64,14 +65,21 @@ export const McpServerSchema = z
   })
   .description('One configured MCP server.')
 
-export const McpSettingsSchema = z.object({
+// Every Adapter-managed field is volatile: the Loader commits form edits into
+// the running fiber without a restart, and the Settings page / profile editor
+// may only write schema-declared volatile paths. Volatile fields must sit at
+// fixed object paths, so the marks stay on the two top-level fields — server
+// entries inside the dict cannot carry their own volatile marks.
+export const McpConfigSchema = z.object({
   mcpServers: z
     .dict(McpServerSchema)
     .default({})
+    .volatile()
     .description('Global MCP servers, keyed by their unique server name.'),
   skillInstall: z
     .union(['file', 'runtime', 'off'])
     .default('file')
+    .volatile()
     .description(
       'How the bundled mcp-adapter agent skill is installed: file (copy to '
       + '$DSH_HOME/skills/mcp-adapter/ so Settings > Skills lists it; an '
@@ -109,7 +117,9 @@ function rejectUnknownKeys(value, allowed, path) {
 
 /**
  * Cross-field checks that the serializable Schemastery shape cannot express.
- * SettingsProvider runs this after schema validation and before every persist.
+ * The old SettingsProvider ran this before every persist; the 0.1.7 Config
+ * write path validates only the schema, so this runs at Host consumption
+ * instead (the Adapter serves no Servers for a semantically invalid section).
  */
 export function validateMcpSettings(value) {
   rejectUnknownKeys(value, TOP_LEVEL_KEYS, 'mcp')
@@ -181,18 +191,112 @@ export function validateMcpSettings(value) {
   }
 }
 
+// Cosmokit identifies volatile references across library copies through this
+// shared symbol; reading it directly keeps the Host free of a cosmokit import.
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+function unwrapVolatile(value, fallback) {
+  if (typeof value === 'object' && value !== null && VOLATILE_WRITE in value) {
+    return value.get()
+  }
+  return value ?? fallback
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined'
+  const keys = Object.keys(value).sort()
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`
+}
+
+/**
+ * Read the live Adapter Config from the fiber and enforce the cross-field
+ * rules. A section that schemastery accepts but these rules reject fails
+ * closed to an empty server list with one deduplicated warning, so a
+ * hand-edited profile can never brick the connection manager.
+ */
+export function readMcpConfig(config = {}, onInvalid) {
+  const value = {
+    ...config,
+    mcpServers: unwrapVolatile(config.mcpServers, {}),
+    skillInstall: unwrapVolatile(config.skillInstall, 'file'),
+  }
+  try {
+    // Validation sees the whole resolved Config, so unknown fields still
+    // reject the section; the returned value only carries declared fields.
+    validateMcpSettings(value)
+    return { mcpServers: value.mcpServers, skillInstall: value.skillInstall }
+  } catch (error) {
+    onInvalid?.(errorMessage(error))
+    return { mcpServers: {}, skillInstall: 'file' }
+  }
+}
+
 /**
- * Register Config while the optional Host settings service exists. The scope
- * belongs to the injected fiber, so provider reload or Adapter disposal removes
- * the namespace and every watcher cleanly.
+ * Wrap the fiber's volatile entry Config in the scope surface every Adapter
+ * feature consumes (the same { get, watch, update, mutate } the old settings
+ * scope provided):
+ *  - `get()` unwraps the volatile references and fail-closes on invalid data;
+ *  - `watch(listener)` fires `(next, previous)` after committed volatile
+ *    updates (`loader/volatile-update`) whose value actually changed;
+ *  - `update(patch)` / `mutate(ops)` write through the settings service onto
+ *    this entry and throw when no settings service is mounted.
  */
-export function installMcpSettings(ctx, activate) {
-  ctx.inject(['settings'], (settingsCtx) => {
-    const scope = settingsCtx.settings.register(
-      MCP_SETTINGS_NAMESPACE,
-      McpSettingsSchema,
-      { validate: validateMcpSettings },
-    )
-    return activate?.(settingsCtx, scope)
+export function createMcpConfigScope(ctx, options = {}) {
+  const warn = options.warn ?? ((message) => ctx.logger?.warn?.(message))
+  const settingsService = options.settings ?? (() => ctx.get('settings'))
+  const listeners = new Set()
+  let warnedInvalid
+  let last = readCurrent()
+
+  function readCurrent() {
+    return readMcpConfig(ctx.config, (message) => {
+      if (message === warnedInvalid) return
+      warnedInvalid = message
+      warn(`dsh-mcp-adapter: invalid MCP Config, serving no Servers: ${message}`)
+    })
+  }
+
+  const off = ctx.on('loader/volatile-update', () => {
+    const next = readCurrent()
+    if (stableJson(next) === stableJson(last)) return
+    const previous = last
+    last = next
+    for (const listener of [...listeners]) {
+      try {
+        listener(next, previous)
+      } catch {
+        // A stale or failing listener must not break Config notification.
+      }
+    }
   })
+
+  function requireSettings(method) {
+    const settings = settingsService()
+    if (settings === undefined) {
+      throw new Error(
+        `dsh-mcp-adapter: settings ${method} unavailable: the DSH settings service is not `
+        + 'mounted in this profile, so MCP Config cannot be written.',
+      )
+    }
+    return settings
+  }
+
+  return {
+    get: () => readCurrent(),
+    watch(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    update(patch) {
+      return requireSettings('update').update(MCP_SETTINGS_NAMESPACE, patch)
+    },
+    mutate(ops) {
+      return requireSettings('mutate').mutate(MCP_SETTINGS_NAMESPACE, ops)
+    },
+    dispose() {
+      off?.()
+      listeners.clear()
+    },
+  }
 }

package/src/host/workspace-config.js

@@ -2,7 +2,7 @@ import { watch as fsWatch } from 'node:fs'
 import { readFile as fsReadFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-import { McpServerSchema, validateMcpSettings } from './settings.js'
+import { McpServerSchema, stableJson, validateMcpSettings } from './settings.js'
 import { errorMessage } from './errors.js'
 
 function isRecord(value) {
@@ -95,13 +95,6 @@ export function mergeMcpConfigs(globalServers, workspaceServers) {
   return { servers, sources }
 }
 
-function stableJson(value) {
-  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
-  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined'
-  const keys = Object.keys(value).sort()
-  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`
-}
-
 function defaultWatchDirectory(directory, onChange) {
   const watcher = fsWatch(directory, () => onChange())
   watcher.on('error', () => {
@@ -120,7 +113,7 @@ function publicServerSummary(config) {
 }
 
 /**
- * Wrap the registered global Config scope with the workspace layer.
+ * Wrap the entry Config scope with the workspace layer.
  *
  * `get()` returns the merged namespace value and `layerSnapshot()` reports
  * which source each Server came from. Watch listeners see global Config edits
@@ -287,7 +280,7 @@ export function createLayeredScope(globalScope, options = {}) {
 }
 
 /**
- * Register the workspace Config layer on the settings fiber. Disposing the
+ * Register the workspace Config layer on the Adapter fiber. Disposing the
  * fiber stops the global watch and the best-effort `.dsh` directory watch.
  */
 export function installWorkspaceLayer(ctx, scope, options = {}) {