@distributionos/cli 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
   "homepage": "https://distributionos.dev",
   "repository": {

package/src/cli.js

@@ -508,6 +508,8 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
       '- Open this DistributionOS review page now:',
       `  ${reviewUrl}`,
       '- Review the generated Brain Doc and Brain Vault context before asking your agent to keep working.',
+      '- If .mcp.json was created or updated, restart or reconnect your agent session so it can load the DistributionOS MCP server.',
+      '- After reconnecting, ask your agent: "Check DistributionOS connection and tell me today\'s analytics summary."',
       '- After review, come back to this repo and inspect git diff before committing, pushing, or deploying.',
     );
   } else {

package/src/mcp-config.js

@@ -0,0 +1,164 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { MCP_SERVER_URL } from './constants.js';
+import { pathExists } from './detect.js';
+
+export const PROJECT_MCP_CONFIG_PATH = '.mcp.json';
+export const DISTRIBUTIONOS_MCP_SERVER_NAME = 'distributionos';
+
+export async function buildProjectMcpConfigPlan(cwd, serverUrl = MCP_SERVER_URL) {
+  const target = safeResolve(cwd, PROJECT_MCP_CONFIG_PATH);
+  const base = {
+    path: PROJECT_MCP_CONFIG_PATH,
+    serverName: DISTRIBUTIONOS_MCP_SERVER_NAME,
+    serverUrl,
+    authMode: 'oauth',
+    requiresRestart: true,
+    writesSecrets: false,
+    recommendedConfig: recommendedMcpConfig(serverUrl),
+  };
+
+  if (!(await pathExists(target))) {
+    return {
+      ...base,
+      supported: true,
+      action: 'create',
+      reason: 'Create a project-local MCP config with the DistributionOS remote server URL only.',
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(target, 'utf8'));
+  } catch {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json is not valid JSON, so the CLI will not edit it automatically.',
+    };
+  }
+
+  if (!isRecord(parsed)) {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json is not an object, so the CLI will not edit it automatically.',
+    };
+  }
+
+  if (containsSecretLikeConfig(parsed)) {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing .mcp.json appears to contain secret headers, tokens, or env values. The CLI will not rewrite it.',
+    };
+  }
+
+  const servers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
+  const existing = servers[DISTRIBUTIONOS_MCP_SERVER_NAME];
+  const existingUrl = isRecord(existing) && typeof existing.url === 'string'
+    ? existing.url
+    : null;
+
+  if (existingUrl === serverUrl) {
+    return {
+      ...base,
+      supported: true,
+      action: 'none',
+      reason: 'Project-local MCP config already includes the DistributionOS server.',
+    };
+  }
+
+  if (existingUrl) {
+    return {
+      ...base,
+      supported: false,
+      action: 'manual',
+      reason: 'Existing distributionos MCP server points to a different URL. The CLI will not overwrite it automatically.',
+    };
+  }
+
+  return {
+    ...base,
+    supported: true,
+    action: 'update',
+    reason: 'Add the DistributionOS remote MCP server to the existing project-local MCP config.',
+  };
+}
+
+export async function applyProjectMcpConfig(cwd, plan) {
+  if (!plan || plan.action === 'none') {
+    return { type: 'mcp', changed: false, file: plan?.path ?? PROJECT_MCP_CONFIG_PATH, reason: plan?.reason ?? 'No MCP config change planned.' };
+  }
+
+  if (plan.action === 'manual' || !plan.supported) {
+    return { type: 'mcp', changed: false, file: plan.path, reason: plan.reason };
+  }
+
+  const target = safeResolve(cwd, plan.path);
+  let existing = {};
+  if (await pathExists(target)) {
+    existing = JSON.parse(await fs.readFile(target, 'utf8'));
+  }
+  if (!isRecord(existing)) {
+    return { type: 'mcp', changed: false, file: plan.path, reason: 'Existing MCP config was not an object.' };
+  }
+
+  const next = {
+    ...existing,
+    mcpServers: {
+      ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}),
+      [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        url: plan.serverUrl ?? MCP_SERVER_URL,
+      },
+    },
+  };
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return {
+    type: 'mcp',
+    changed: true,
+    file: plan.path,
+    action: plan.action === 'create' ? 'created' : 'updated',
+  };
+}
+
+function recommendedMcpConfig(serverUrl) {
+  return {
+    mcpServers: {
+      [DISTRIBUTIONOS_MCP_SERVER_NAME]: {
+        url: serverUrl,
+      },
+    },
+  };
+}
+
+function containsSecretLikeConfig(value) {
+  if (Array.isArray(value)) return value.some(containsSecretLikeConfig);
+  if (!isRecord(value)) return false;
+  for (const [key, nested] of Object.entries(value)) {
+    if (/authorization|api[-_]?key|token|secret|password|credential|headers|env/i.test(key)) {
+      if (nested !== null && nested !== undefined && nested !== '') return true;
+    }
+    if (containsSecretLikeConfig(nested)) return true;
+  }
+  return false;
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function safeResolve(cwd, relativePath) {
+  const root = path.resolve(cwd);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to write outside repo root: ${relativePath}`);
+  }
+  return target;
+}

package/src/mutate.js

@@ -1,5 +1,6 @@
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { applyProjectMcpConfig } from './mcp-config.js';
 
 const BOOTSTRAP_BLOCK_RE =
   /<!--\s*DISTRIBUTIONOS:START[\s\S]*?DISTRIBUTIONOS:END\s*-->/i;
@@ -17,13 +18,16 @@ export async function applySetupPlan(plan, options = {}) {
   const bootstrap = await applyBootstrap(plan.cwd, plan.bootstrap);
   if (bootstrap.changed) changes.push(bootstrap);
 
-  if (!options.skipAnalytics) {
-    const analytics = await applyAnalytics(plan.cwd, plan.analytics);
-    if (analytics.changed || analytics.reason) changes.push(analytics);
-  }
-
-  return changes;
-}
+  if (!options.skipAnalytics) {
+    const analytics = await applyAnalytics(plan.cwd, plan.analytics);
+    if (analytics.changed || analytics.reason) changes.push(analytics);
+  }
+
+  const mcp = await applyProjectMcpConfig(plan.cwd, plan.mcp);
+  if (mcp.changed || mcp.reason) changes.push(mcp);
+
+  return changes;
+}
 
 async function applyBootstrap(cwd, bootstrap) {
   const targetPath = safeResolve(cwd, bootstrap.target);

package/src/plan.js

@@ -10,10 +10,11 @@ import {
   buildSetupCommand,
   getBootstrapAction,
 } from './bootstrap.js';
-import { scanRepo } from './detect.js';
-import {
-  buildAnalyticsRouteConfigScript,
-  buildAnalyticsRouteConfigSnippet,
+import { scanRepo } from './detect.js';
+import { buildProjectMcpConfigPlan } from './mcp-config.js';
+import {
+  buildAnalyticsRouteConfigScript,
+  buildAnalyticsRouteConfigSnippet,
 } from './privacy.js';
 
 export async function createSetupPlan(options) {
@@ -33,10 +34,11 @@ export async function createSetupPlan(options) {
     remote.instructions?.recommendedBootstrapBlock ??
     buildLocalBootstrapBlock(instructionPackVersion, appId);
   const bootstrap = getBootstrapAction(repo.instructionFiles, recommendedBootstrapBlock);
-  const analyticsContract = remote.analyticsContract;
-  const planRepo = sanitizeRepoForPlan(repo);
-
-  return {
+  const analyticsContract = remote.analyticsContract;
+  const planRepo = sanitizeRepoForPlan(repo);
+  const mcp = await buildProjectMcpConfigPlan(cwd);
+
+  return {
     appId,
     cwd,
     mode: options.apply ? 'apply' : 'review',
@@ -47,15 +49,17 @@ export async function createSetupPlan(options) {
     repo: planRepo,
     remote,
     instructionPackVersion,
-    bootstrap,
-    analytics: buildAnalyticsPlan({ analyticsContract, repo: planRepo, instructionPackVersion }),
+    bootstrap,
+    mcp,
+    analytics: buildAnalyticsPlan({ analyticsContract, repo: planRepo, instructionPackVersion }),
     fallbackInstructions: buildFallbackMcpInstructions(appId),
     warnings: buildWarnings({ repo: planRepo, remote }),
     validation: buildValidationPlan(planRepo),
     deploymentChecklist: [
       'Review this plan and any proposed file edits.',
-      'Apply reviewed bootstrap and analytics changes only.',
-      'Run baseline tests before mutation when the worktree is messy.',
+      'Apply reviewed bootstrap, analytics, and non-secret project MCP config changes only.',
+      'Restart or reconnect your agent if the project-local MCP config changed.',
+      'Run baseline tests before mutation when the worktree is messy.',
       'Run build and test commands after mutation.',
       'Do not deploy until a human reviews the diff.',
       'After deployment, call verify_analytics_install on representative public URLs.',
@@ -113,11 +117,12 @@ export function formatPlanText(plan) {
     ...plan.remote.errors.map(error => `- ${error}`),
     '',
     'Planned changes',
-    `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
-    `   ${plan.bootstrap.reason}`,
-    `2. Agent instructions: ${plan.remote.instructions ? 'use fetched current instruction pack' : 'use fallback MCP/OAuth instructions until authenticated'}`,
-    `3. Analytics: ${analyticsSummary(plan.analytics)}`,
-    '',
+    `1. Agent bootstrap: ${plan.bootstrap.action} ${plan.bootstrap.target}`,
+    `   ${plan.bootstrap.reason}`,
+    `2. Agent instructions: ${plan.remote.instructions ? 'use fetched current instruction pack' : 'use fallback MCP/OAuth instructions until authenticated'}`,
+    `3. Analytics: ${analyticsSummary(plan.analytics)}`,
+    `4. Agent MCP config: ${mcpSummary(plan.mcp)}`,
+    '',
     'Route privacy review',
     `- Allowed public candidates: ${formatList(plan.repo.routePrivacy.allowed, 8)}`,
     `- Blocked private candidates: ${formatList(plan.repo.routePrivacy.blocked, 8)}`,
@@ -128,9 +133,15 @@ export function formatPlanText(plan) {
     `- Test: ${plan.validation.test ?? 'not detected'}`,
     `- Lint: ${plan.validation.lint ?? 'not detected'}`,
     '',
-    'Fallback MCP/OAuth instructions',
-    ...plan.fallbackInstructions.map(item => `- ${item}`),
-    '',
+    'Fallback MCP/OAuth instructions',
+    ...plan.fallbackInstructions.map(item => `- ${item}`),
+    '',
+    'Agent live-data connection',
+    `- Project config: ${plan.mcp.path}`,
+    `- Planned action: ${plan.mcp.action}`,
+    `- Auth mode: ${plan.mcp.authMode}; no API keys or OAuth tokens are written.`,
+    `- ${plan.mcp.reason}`,
+    '',
     'Deployment checklist',
     ...plan.deploymentChecklist.map(item => `- ${item}`),
   ];
@@ -175,7 +186,7 @@ function nextStepLines(plan) {
 
   lines.push(
     '',
-    'DistributionOS expects to edit only the managed agent instruction block and the supported analytics layout. Review git diff before committing or deploying.',
+    'DistributionOS expects to edit only the managed agent instruction block, supported analytics layout, and non-secret project MCP config. Review git diff before committing or deploying.',
   );
 
   return lines;
@@ -307,7 +318,7 @@ function meterText(value) {
   return `${value.used ?? 0}/${limit}`;
 }
 
-function analyticsSummary(analytics) {
+function analyticsSummary(analytics) {
   if (analytics.status === 'enabled') {
     return `contract ${analytics.contractVersion}; install script in ${analytics.layoutTarget ?? 'reviewed shared layout'}`;
   }
@@ -315,7 +326,15 @@ function analyticsSummary(analytics) {
     return 'tracker will be created or fetched during apply before analytics is installed';
   }
   return 'contract not fetched; print manual guidance only';
-}
+}
+
+function mcpSummary(mcp) {
+  if (!mcp) return 'manual instructions only';
+  if (mcp.action === 'none') return `${mcp.path} already includes DistributionOS`;
+  if (mcp.action === 'create') return `create ${mcp.path} with DistributionOS MCP server URL`;
+  if (mcp.action === 'update') return `update ${mcp.path} with DistributionOS MCP server URL`;
+  return `manual setup needed for ${mcp.path}`;
+}
 
 function formatList(values, limit = 5) {
   if (!values || values.length === 0) return 'none';