@aion0/forge 0.10.47 → 0.10.49

package/mcp/tools/_shared.ts

@@ -0,0 +1,103 @@
+/** Shared helpers for management MCP tools. */
+
+/** Wrap a string as an MCP text result. */
+export function text(s: string) {
+  return { content: [{ type: 'text' as const, text: s }] };
+}
+
+/** Wrap an error as an MCP text result flagged is_error. */
+export function fail(s: string) {
+  return { content: [{ type: 'text' as const, text: s }], isError: true };
+}
+
+/** Run a handler, converting thrown errors into a clean is_error result so a
+ *  tool bug never crashes the session. */
+export async function guard(fn: () => Promise<ReturnType<typeof text>> | ReturnType<typeof text>) {
+  try { return await fn(); }
+  catch (e) { return fail(`Error: ${(e as Error).message}`); }
+}
+
+/** Human label for which session a created task attached to. Reflects what
+ *  actually happened — an explicit fresh session, a continued existing one, or a
+ *  fresh start because no prior session was found — rather than over-promising
+ *  "continuing" when there was nothing to continue. */
+export function describeSession(
+  newSession: boolean | undefined,
+  conversationId: string | null | undefined,
+): string {
+  if (newSession) return 'new session';
+  return conversationId ? 'continuing session' : 'no prior session — started fresh';
+}
+
+/** True if a marketplace skill is installed globally or in any project. A
+ *  SkillItem exposes `installedGlobal` / `installedProjects` — there is no
+ *  `installed` field, so reading one silently never matches. */
+export function skillInstalled(e: { installedGlobal?: boolean; installedProjects?: string[] }): boolean {
+  return !!(e.installedGlobal || e.installedProjects?.length);
+}
+
+/** Display status for one connector settings field. Secret-bearing fields NEVER
+ *  echo their (decrypted-at-rest) value — only whether they are set — so listing a
+ *  connector can't leak credentials. This mirrors the codebase's canonical secret
+ *  detection (lib/connectors/registry.ts isSecretField = `secret || password`, and
+ *  the ConnectorsPanel UI), which masks `secret` AND `password` and treats
+ *  `instances` arrays as opaque because each row can carry its own sub-secret (e.g.
+ *  a per-server PAT). Only plain non-secret scalar values are shown (clipped). */
+export function connectorFieldStatus(field: { type: string; required?: boolean }, value: unknown): string {
+  const unset = field.required ? 'UNSET (required)' : 'unset';
+  // secret / password — report set-ness only, never the value.
+  if (field.type === 'secret' || field.type === 'password') return value ? 'set' : unset;
+  // instances — opaque: rows may hold sub-secrets, so never serialize the value.
+  if (field.type === 'instances') {
+    let rows = value;
+    if (typeof rows === 'string') { try { rows = JSON.parse(rows); } catch { /* keep as-is */ } }
+    const n = Array.isArray(rows) ? rows.length : (value ? 1 : 0);
+    return n ? `${n} instance(s) configured` : unset;
+  }
+  if (value !== undefined && value !== '') return `= ${String(JSON.stringify(value)).slice(0, 40)}`;
+  return field.required ? 'MISSING (required)' : 'unset';
+}
+
+/** Human description of a schedule/job trigger from its kind + timing fields. */
+export function describeTiming(s: {
+  schedule_kind?: string | null;
+  schedule_interval_minutes?: number;
+  schedule_cron?: string | null;
+  schedule_at?: string | null;
+}): string {
+  switch (s.schedule_kind) {
+    case 'cron': return `cron "${s.schedule_cron || '?'}"`;
+    case 'once': return `once at ${s.schedule_at || '?'}`;
+    case 'manual': return 'manual only';
+    case 'period': return `every ${s.schedule_interval_minutes ?? '?'}m`;
+    default:
+      // Unknown/absent kind: prefer a real trigger field over mislabelling as an interval.
+      if (s.schedule_cron) return `cron "${s.schedule_cron}"`;
+      if (s.schedule_at) return `once at ${s.schedule_at}`;
+      return s.schedule_interval_minutes != null ? `every ${s.schedule_interval_minutes}m` : 'unknown schedule';
+  }
+}
+
+/** Pure pipeline-summary logic for forge_status: count running across ALL runs
+ *  (not a truncated recent window, which undercounts an older still-running run)
+ *  and surface the 3 newest. */
+export function summarizePipelines(
+  all: { id: string; status: string; workflowName: string; createdAt: string }[],
+): { runningCount: number; recent: string[] } {
+  const runningCount = all.filter((p) => p.status === 'running').length;
+  const recent = [...all]
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+    .slice(0, 3)
+    .map((p) => `${p.id} [${p.status}] ${p.workflowName}`);
+  return { runningCount, recent };
+}
+
+/** Compact token/count formatter: 1234567 → "1.2M", 340000 → "340K", 999 → "999".
+ *  Non-finite input collapses to "0" so a bad row never prints "NaN". */
+export function fmtTokens(n: number): string {
+  if (!Number.isFinite(n)) return '0';
+  const abs = Math.abs(n);
+  if (abs >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (abs >= 1_000) return `${Math.round(n / 1_000)}K`;
+  return String(Math.round(n));
+}

package/mcp/tools/automation.ts

@@ -0,0 +1,244 @@
+/** Automation tools — Forge's two recurring-work engines:
+ *   • Schedules: fire ONE body (pipeline or prompt) on a trigger, optional notify.
+ *   • Jobs:      poll a connector, dedup, and dispatch MANY items to pipelines/chat.
+ *  Schedules have list/create/update/manage; jobs have list/manage. The
+ *  issue-autofix / watch subsystems are deferred to a later phase. In-process lib
+ *  calls; run/cancel mirror the route handlers. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  listSchedules, getSchedule, createSchedule, updateSchedule, deleteSchedule,
+  listScheduleRuns, listInflightForSchedule,
+} from '@/lib/schedules/store';
+import type { UpdateScheduleInput } from '@/lib/schedules/types';
+import { executeSchedule, isScheduleBusy } from '@/lib/schedules/scheduler';
+import {
+  listJobs, getJob, updateJob, deleteJob,
+  listRuns, resetDedup, cancelJobDrain, listJobDispatchedPipelines,
+  seedNextRunAt as seedJobNextRunAt,
+} from '@/lib/jobs/store';
+import { runJob, isJobBusy } from '@/lib/jobs/scheduler';
+import { cancelPipeline, getWorkflow } from '@/lib/pipeline';
+import { cancelTask } from '@/lib/task-manager';
+import { ensureInitialized } from '@/lib/init';
+import { text, fail, guard, describeTiming } from './_shared';
+
+const SCHED_ACTIONS = ['run', 'pause', 'resume', 'cancel', 'delete'] as const;
+const JOB_ACTIONS = ['run', 'pause', 'resume', 'cancel', 'reset_dedup', 'delete'] as const;
+
+export function registerAutomationTools(server: McpServer): void {
+  // ── Schedules ───────────────────────────────────────────────
+  server.tool(
+    'forge_list_schedules',
+    'List Forge schedules (recurring runs of a pipeline or prompt). Pass id for one schedule\'s detail + recent runs. Use forge_manage_schedule to run/pause/resume/cancel/delete.',
+    { id: z.string().optional().describe('A schedule id for full detail + recent runs') },
+    (params) => guard(() => {
+      if (params.id) {
+        const s = getSchedule(params.id);
+        if (!s) return fail(`Schedule not found: ${params.id}`);
+        const busy = isScheduleBusy(s.id);
+        const lines = [
+          `Schedule: ${s.name} (${s.id}) [${s.enabled ? 'enabled' : 'disabled'}${busy.busy ? `, busy: ${busy.reason}` : ''}]`,
+          `Body: ${s.body_kind} → ${s.body_ref}`,
+          `Trigger: ${describeTiming(s)} · Action: ${s.action_kind}`,
+          `Next run: ${s.next_run_at || 'n/a'} · Last run: ${s.last_run_at || 'never'}`,
+        ];
+        const runs = listScheduleRuns(s.id, 5);
+        if (runs.length) {
+          lines.push('Recent runs:');
+          for (const r of runs) lines.push(`  ${r.status} ${r.started_at?.slice(0, 16) || ''}${r.error ? ` — ${r.error}` : ''}`);
+        }
+        return text(lines.join('\n'));
+      }
+      const all = listSchedules();
+      if (!all.length) return text('No schedules.');
+      const lines = all.map((s) =>
+        `• ${s.name} (${s.id}) [${s.enabled ? 'on' : 'off'}] ${s.body_kind}:${s.body_ref} · ${describeTiming(s)} · next ${s.next_run_at?.slice(0, 16) || 'n/a'}`);
+      return text(`${all.length} schedule(s):\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_manage_schedule',
+    'Manage an existing schedule: run (fire now), pause (disable + cancel any in-flight run), resume (enable), cancel (stop in-flight runs — pipeline or prompt-bodied task), or delete.',
+    {
+      id: z.string().describe('Schedule id (from forge_list_schedules)'),
+      action: z.enum(SCHED_ACTIONS).describe('What to do'),
+    },
+    (params) => guard(async () => {
+      const s = getSchedule(params.id);
+      if (!s) return fail(`Schedule not found: ${params.id}`);
+      const cancelInflight = () => {
+        let n = 0;
+        for (const r of listInflightForSchedule(s.id)) {
+          try {
+            // A prompt-bodied run stores target_id = task.id (not a pipeline id),
+            // so cancel the right thing by body kind.
+            const ok = s.body_kind === 'prompt' ? cancelTask(r.target_id) : cancelPipeline(r.target_id);
+            if (ok) n++;
+          } catch { /* best-effort */ }
+        }
+        return n;
+      };
+      switch (params.action) {
+        case 'run': {
+          const busy = isScheduleBusy(s.id);
+          if (busy.busy) return fail(`Schedule is busy: ${busy.reason}. Cancel it first, or wait.`);
+          ensureInitialized();
+          const targetId = await executeSchedule(s, 'manual');
+          return text(`Fired ${s.name} (manual) → ${s.body_kind} ${targetId}. Track with forge_get_pipeline / forge_get_task id=${targetId}.`);
+        }
+        case 'pause': { updateSchedule(s.id, { enabled: false }); const n = cancelInflight(); return text(`Paused ${s.name}${n ? ` and cancelled ${n} inflight run(s)` : ''}.`); }
+        // resume: updateSchedule reseeds next_run_at on enable (schedules store), so no explicit seed (unlike jobs).
+        case 'resume': { updateSchedule(s.id, { enabled: true }); return text(`Resumed ${s.name}.`); }
+        case 'cancel': { const n = cancelInflight(); return text(`Cancelled ${n} inflight run(s) for ${s.name}.`); }
+        case 'delete': { cancelInflight(); deleteSchedule(s.id); return text(`Deleted ${s.name}.`); }
+      }
+    }),
+  );
+
+  server.tool(
+    'forge_upsert_schedule',
+    'Create a schedule, or edit an existing one when id is given. CREATE: name + workflow + exactly one trigger (every_minutes / at / cron) are required. EDIT (id set): every field is optional and only what you pass changes (at most one trigger). Optionally notify on completion via action + action_config.',
+    {
+      id: z.string().optional().describe('Schedule id to EDIT (from forge_list_schedules). Omit to CREATE.'),
+      name: z.string().optional().describe('Schedule name (required on create)'),
+      workflow: z.string().optional().describe('Pipeline workflow name from forge_list_workflows (required on create)'),
+      every_minutes: z.number().int().positive().optional().describe('Interval trigger: run every N minutes'),
+      at: z.string().optional().describe('Once trigger: ISO timestamp to fire at (e.g. "2026-07-01T09:00:00Z")'),
+      cron: z.string().optional().describe('Cron trigger: a 5-field cron expression (e.g. "0 9 * * *")'),
+      input: z.record(z.string(), z.string()).optional().describe('Workflow input variables (replaces existing on edit)'),
+      skills: z.array(z.string()).optional().describe('Extra skill names to load for the run'),
+      enabled: z.boolean().optional().describe('On create: start enabled (default true). Use forge_manage_schedule to enable/disable later.'),
+      action: z.enum(['none', 'chat', 'email', 'telegram']).optional().describe('Notify on completion. Non-none requires action_config.'),
+      action_config: z.record(z.string(), z.string()).optional().describe('Config for action — chat: {session_id}; email: {to}; telegram: {chat_id}.'),
+    },
+    (params) => guard(() => {
+      const triggerCount = [params.every_minutes != null, !!params.at, !!params.cron].filter(Boolean).length;
+      if (params.action && params.action !== 'none' && !(params.action_config && Object.keys(params.action_config).length)) {
+        return fail(`action="${params.action}" needs action_config (chat: session_id; email: to; telegram: chat_id).`);
+      }
+      const kindFrom = () => params.every_minutes != null ? 'period' as const : params.at ? 'once' as const : 'cron' as const;
+      ensureInitialized(); // ensure the scheduler is running so the schedule fires
+
+      if (params.id) { // ── edit ──
+        const s = getSchedule(params.id);
+        if (!s) return fail(`Schedule not found: ${params.id}`);
+        if (triggerCount > 1) return fail('Provide at most one of every_minutes, at, or cron.');
+        const patch: UpdateScheduleInput = {};
+        if (params.name !== undefined) patch.name = params.name;
+        if (params.input !== undefined) patch.input = params.input;
+        if (params.skills !== undefined) patch.skills = params.skills;
+        if (params.action !== undefined) patch.action_kind = params.action;
+        if (params.action_config !== undefined) patch.action_config = params.action_config;
+        if (triggerCount === 1) {
+          const kind = kindFrom();
+          patch.schedule_kind = kind;
+          if (kind === 'period') patch.schedule_interval_minutes = params.every_minutes;
+          else if (kind === 'once') patch.schedule_at = params.at;
+          else patch.schedule_cron = params.cron;
+        }
+        if (Object.keys(patch).length === 0) return fail('Nothing to update — provide name, input, skills, action, or a trigger (every_minutes/at/cron).');
+        updateSchedule(s.id, patch);
+        // updateSchedule reseeds next_run_at internally when the trigger changes.
+        const after = getSchedule(s.id)!;
+        return text(`Updated ${after.name} (${after.id}) — ${describeTiming(after)}. Next run: ${after.next_run_at || 'n/a'}.`);
+      }
+
+      // ── create ──
+      if (!params.name) return fail('name is required to create a schedule (or pass id to edit one).');
+      if (!params.workflow) return fail('workflow is required to create a schedule. Use forge_list_workflows.');
+      if (triggerCount !== 1) return fail('Provide exactly one of every_minutes, at, or cron.');
+      if (!getWorkflow(params.workflow)) return fail(`Workflow not found: ${params.workflow}. Use forge_list_workflows.`);
+      const s = createSchedule({
+        name: params.name,
+        body_kind: 'pipeline',
+        body_ref: params.workflow,
+        input: params.input,
+        skills: params.skills,
+        enabled: params.enabled,
+        schedule_kind: kindFrom(),
+        schedule_interval_minutes: params.every_minutes,
+        schedule_at: params.at ?? null,
+        schedule_cron: params.cron ?? null,
+        action_kind: params.action || 'none',
+        action_config: params.action_config,
+      });
+      return text(`Created schedule ${s.name} (${s.id}) — ${describeTiming(s)} → pipeline ${s.body_ref}. Next run: ${s.next_run_at || 'n/a'}.\nManage with forge_manage_schedule id=${s.id}.`);
+    }),
+  );
+
+  // ── Jobs ────────────────────────────────────────────────────
+  server.tool(
+    'forge_list_jobs',
+    'List Forge jobs (poll a connector on a schedule, dedup results, and dispatch each new item to a pipeline or chat). Pass id for one job\'s detail + recent runs. Use forge_manage_job to run/pause/resume/cancel/reset_dedup/delete.',
+    { id: z.string().optional().describe('A job id for full detail + recent runs') },
+    (params) => guard(() => {
+      if (params.id) {
+        const j = getJob(params.id);
+        if (!j) return fail(`Job not found: ${params.id}`);
+        const busy = isJobBusy(j.id);
+        const wf = j.dispatch_type === 'pipeline' ? ` → ${(j.dispatch_params as { workflow_name?: string }).workflow_name || '?'}` : '';
+        const lines = [
+          `Job: ${j.name} (${j.id}) [${j.enabled ? 'enabled' : 'disabled'}${busy.busy ? `, busy: ${busy.reason}` : ''}]`,
+          `Source: ${j.source_connector}.${j.source_tool} (dedup on "${j.dedup_field}")`,
+          `Dispatch: ${j.dispatch_type}${wf} · max ${j.max_per_tick}/tick · ${j.concurrency_mode}`,
+          `Trigger: ${describeTiming(j)} · Next run: ${j.next_run_at || 'n/a'} · Last: ${j.last_run_at || 'never'}`,
+        ];
+        const runs = listRuns(j.id, 5);
+        if (runs.length) {
+          lines.push('Recent runs:');
+          for (const r of runs) lines.push(`  ${r.status} seen=${r.items_seen} new=${r.items_new} dispatched=${r.items_dispatched} ${r.started_at?.slice(0, 16) || ''}${r.error ? ` — ${r.error}` : ''}`);
+        }
+        return text(lines.join('\n'));
+      }
+      const all = listJobs();
+      if (!all.length) return text('No jobs.');
+      const lines = all.map((j) =>
+        `• ${j.name} (${j.id}) [${j.enabled ? 'on' : 'off'}] ${j.source_connector}.${j.source_tool} → ${j.dispatch_type} · ${describeTiming(j)} · next ${j.next_run_at?.slice(0, 16) || 'n/a'}`);
+      return text(`${all.length} job(s):\n${lines.join('\n')}`);
+    }),
+  );
+
+  server.tool(
+    'forge_manage_job',
+    'Manage an existing job: run (fire now), pause (disable + stop drain), resume (enable), cancel (stop drain + cancel inflight dispatched pipelines), reset_dedup (re-process all items next run), or delete.',
+    {
+      id: z.string().describe('Job id (from forge_list_jobs)'),
+      action: z.enum(JOB_ACTIONS).describe('What to do'),
+    },
+    (params) => guard(async () => {
+      const j = getJob(params.id);
+      if (!j) return fail(`Job not found: ${params.id}`);
+      switch (params.action) {
+        case 'run': {
+          const busy = isJobBusy(j.id);
+          if (busy.busy) return fail(`Job is busy: ${busy.reason}. Cancel it first, or wait.`);
+          ensureInitialized();
+          const runId = await runJob(j.id, 'manual');
+          return text(`Ran ${j.name} (manual) → run ${runId}. Inspect with forge_list_jobs id=${j.id}.`);
+        }
+        case 'pause': { updateJob(j.id, { enabled: false }); cancelJobDrain(j.id); return text(`Paused ${j.name} (drain stopped).`); }
+        case 'resume': {
+          updateJob(j.id, { enabled: true });
+          // reseed next_run_at: pause (cancelJobDrain) nulled it, NULL = due now.
+          if (j.schedule_kind !== 'manual') seedJobNextRunAt(j.id);
+          return text(`Resumed ${j.name}.`);
+        }
+        case 'cancel': {
+          cancelJobDrain(j.id);
+          let n = 0;
+          for (const p of listJobDispatchedPipelines(j.id, 50)) {
+            if (p.pipeline_status === 'running' || p.pipeline_status === 'pending') {
+              try { if (cancelPipeline(p.pipeline_id)) n++; } catch { /* best-effort */ }
+            }
+          }
+          return text(`Stopped drain for ${j.name}${n ? `, cancelled ${n} inflight pipeline(s)` : ''}.`);
+        }
+        case 'reset_dedup': { const c = resetDedup(j.id); return text(`Reset dedup for ${j.name} (${c} key(s) cleared) — next run re-processes all items.`); }
+        case 'delete': { cancelJobDrain(j.id); deleteJob(j.id); return text(`Deleted ${j.name}.`); }
+      }
+    }),
+  );
+}

package/mcp/tools/connectors.ts

@@ -0,0 +1,83 @@
+/** Connector config tools — inspect and configure installed connectors (the
+ *  external-system tool bundles: GitLab, Jenkins, Mantis, …). Installing comes
+ *  from the marketplace (forge_marketplace_install); this is the post-install
+ *  config surface: see settings + status, set settings, enable/disable, test.
+ *
+ *  Secret fields are stored encrypted at rest; this tool masks them on display
+ *  (only "set"/"unset") and relies on the store to encrypt any secret values it
+ *  writes. In-process lib calls. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  listInstalledConnectors, getInstalledConnector,
+  setConnectorConfig, setConnectorEnabled,
+} from '@/lib/connectors/registry';
+import { runConnectorTest } from '@/lib/connectors/test-runner';
+import { text, fail, guard, connectorFieldStatus } from './_shared';
+
+export function registerConnectorTools(server: McpServer): void {
+  server.tool(
+    'forge_list_connectors',
+    'List installed connectors (external-system tool bundles) and their enabled state. Pass id for one connector\'s settings schema + which fields are set/missing (secret values are masked). Configure with forge_configure_connector.',
+    { id: z.string().optional().describe('A connector id for its settings detail') },
+    (params) => guard(() => {
+      if (params.id) {
+        const inst = getInstalledConnector(params.id);
+        if (!inst) return fail(`Connector not installed: ${params.id}. Find one with forge_marketplace_search kind="connector".`);
+        const def = inst.definition;
+        const lines = [
+          `Connector: ${def.name} (${def.id}) [${inst.enabled ? 'enabled' : 'disabled'}] v${inst.installed_version}`,
+        ];
+        const fields = Object.entries(def.settings || {});
+        if (fields.length) {
+          lines.push('Settings:');
+          for (const [k, f] of fields) lines.push(`  • ${k} [${f.type}${f.required ? ', required' : ''}] ${connectorFieldStatus(f, inst.config[k])}`);
+        } else {
+          lines.push('Settings: none.');
+        }
+        lines.push(`Configure: forge_configure_connector id="${def.id}" settings={…} enable=true test=true.`);
+        return text(lines.join('\n'));
+      }
+      const all = listInstalledConnectors();
+      if (!all.length) return text('No connectors installed. Find one with forge_marketplace_search kind="connector", then forge_marketplace_install.');
+      const lines = all.map((c) => `• ${c.definition.id} (${c.definition.name}) [${c.enabled ? 'enabled' : 'disabled'}] v${c.installed_version}`);
+      return text(`${all.length} connector(s):\n${lines.join('\n')}\n\nDetail: forge_list_connectors id="…".`);
+    }),
+  );
+
+  server.tool(
+    'forge_configure_connector',
+    'Configure an installed connector: set one or more settings (secret fields are encrypted at rest), enable/disable it, and/or run its connection test. Provide at least one of settings, enable, or test.',
+    {
+      id: z.string().describe('Connector id (from forge_list_connectors)'),
+      settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+        .describe('Field → value to set (merged over current config). See the schema via forge_list_connectors id=…'),
+      enable: z.boolean().optional().describe('Enable (true) or disable (false) the connector'),
+      test: z.boolean().optional().describe('Run the connector\'s connection test after applying changes'),
+    },
+    (params) => guard(async () => {
+      const inst = getInstalledConnector(params.id);
+      if (!inst) return fail(`Connector not installed: ${params.id}.`);
+      const hasSettings = params.settings && Object.keys(params.settings).length > 0;
+      if (!hasSettings && params.enable === undefined && !params.test) {
+        return fail('Nothing to do — provide settings, enable, and/or test.');
+      }
+      const done: string[] = [];
+      if (hasSettings) {
+        setConnectorConfig(params.id, { ...inst.config, ...params.settings });
+        done.push(`updated ${Object.keys(params.settings!).join(', ')}`);
+      }
+      if (params.enable !== undefined) {
+        setConnectorEnabled(params.id, params.enable);
+        done.push(params.enable ? 'enabled' : 'disabled');
+      }
+      let testLine = '';
+      if (params.test) {
+        const r = await runConnectorTest(params.id);
+        testLine = `\nTest: ${r.ok ? 'OK' : `FAILED — ${r.error || 'unknown error'}`}`;
+      }
+      return text(`${inst.definition.name}: ${done.join('; ') || 'no changes'}.${testLine}`);
+    }),
+  );
+}

package/mcp/tools/help.ts

@@ -0,0 +1,50 @@
+/** Help tool — answers conceptual questions ("what's a pipeline?", "how do I
+ *  install Forge?") from the bundled help docs, so the client can explain Forge
+ *  without the user opening the UI. Reads lib/help-docs (synced to <dataDir>/help). */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '@/lib/dirs';
+import { text, fail, guard } from './_shared';
+
+/** Resolve the help-docs directory: the synced runtime copy, else the repo source. */
+function helpDir(): string | null {
+  const synced = join(getDataDir(), 'help');
+  if (existsSync(synced)) return synced;
+  const src = join(process.cwd(), 'lib', 'help-docs');
+  if (existsSync(src)) return src;
+  return null;
+}
+
+/** "05-pipelines.md" → "pipelines" */
+const slug = (file: string) => file.replace(/\.md$/, '').replace(/^\d+-/, '');
+
+export function registerHelpTools(server: McpServer): void {
+  server.tool(
+    'forge_help',
+    'Explain a Forge concept or feature from the official docs (e.g. topic "pipelines", "connectors", "tasks", "workspace", "overview" for install/setup). Call with no topic to list available topics.',
+    { topic: z.string().optional().describe('Doc topic, e.g. "pipelines", "install", "connectors"') },
+    (params) => guard(() => {
+      const dir = helpDir();
+      if (!dir) return fail('Help docs not found.');
+      const files = readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'CLAUDE.md');
+      if (!params.topic) {
+        const topics = files.map(slug).sort();
+        return text(`Available help topics:\n${topics.map((t) => `• ${t}`).join('\n')}\n\nCall forge_help with one of these, e.g. topic="pipelines".`);
+      }
+      const q = params.topic.toLowerCase().replace(/[\s-]+/g, '');
+      const aliases: Record<string, string> = { install: 'overview', setup: 'overview', model: 'settings', agent: 'settings', marketplace: 'skills' };
+      const wanted = aliases[q] || q;
+      const match = files.find((f) => slug(f).replace(/-/g, '').includes(wanted))
+        || files.find((f) => slug(f).replace(/-/g, '').includes(q));
+      if (!match) {
+        return fail(`No help topic matches "${params.topic}". Try: ${files.map(slug).join(', ')}.`);
+      }
+      const body = readFileSync(join(dir, match), 'utf-8');
+      const clipped = body.length > 6000 ? body.slice(0, 6000) + '\n\n…(truncated)' : body;
+      return text(clipped);
+    }),
+  );
+}

package/mcp/tools/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Tool registry for the Forge Management MCP.
+ *
+ * Each tool is an INTENT (not a 1:1 REST passthrough). Handlers call `lib/`
+ * functions in-process — never SQL from the client, never self-HTTP. The one
+ * exception is workspace mutations, which go through the workspace daemon HTTP
+ * API per the single-writer rule (see workspace.ts).
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ManagementContext } from '../server';
+import { registerProjectTools } from './projects';
+import { registerTaskTools } from './tasks';
+import { registerLogTools } from './logs';
+import { registerIntegrationTools } from './integrations';
+import { registerHelpTools } from './help';
+import { registerPipelineTools } from './pipelines';
+import { registerMarketplaceTools } from './marketplace';
+import { registerWorkspaceTools } from './workspace';
+import { registerObservabilityTools } from './observability';
+import { registerAutomationTools } from './automation';
+import { registerConnectorTools } from './connectors';
+
+export function registerTools(server: McpServer, _ctx: ManagementContext): void {
+  registerProjectTools(server);     // forge_list_projects, forge_register_project, forge_unregister_project
+  registerTaskTools(server);        // forge_{list,get,create,cancel}_task(s)
+  registerLogTools(server);         // forge_tail_logs
+  registerIntegrationTools(server); // forge_list_agents, forge_set_default_agent, forge_set_agent_model
+  registerHelpTools(server);        // forge_help
+  registerPipelineTools(server);    // forge_{list_workflows,run_pipeline,get_pipeline,cancel_pipeline,list_pipeline_runs,create_pipeline}
+  registerMarketplaceTools(server); // forge_marketplace_search, forge_marketplace_install
+  registerWorkspaceTools(server);   // forge_list_workspace_agents, forge_add_workspace_agent
+  registerObservabilityTools(server); // forge_status, forge_get_usage
+  registerAutomationTools(server);  // forge_{list,upsert,manage}_schedule, forge_{list,manage}_job
+  registerConnectorTools(server);   // forge_list_connectors, forge_configure_connector
+
+  // ── TODO v1b (needs additive endpoints) ──
+  // forge_stream_logs (SSE) · forge_setup_key
+}

package/mcp/tools/integrations.ts

@@ -0,0 +1,97 @@
+/** Integration tools — the CLI coding agents Forge wraps (claude code, codex,
+ *  aider …): which are installed, which is the default, and per-component model
+ *  overrides. "Is Claude integrated? Set it as default. Use different models for
+ *  different components."
+ *
+ *  NOTE: these are CLI *agents* (settings.agents / defaultAgent), distinct from
+ *  workspace agents/smiths (see workspace.ts). Settings writes go load → mutate →
+ *  saveSettings, then clearAgentCache() so resolvers don't serve stale adapters. */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { listAgents, getDefaultAgentId, clearAgentCache } from '@/lib/agents';
+import type { AgentConfig } from '@/lib/agents/types';
+import { loadSettings, saveSettings } from '@/lib/settings';
+import { text, fail, guard } from './_shared';
+
+const SCENES = ['terminal', 'task', 'telegram', 'help', 'mobile'] as const;
+
+/** Fuzzy-resolve a user-typed agent name ("claude", "claude code", "Codex") to a
+ *  real agent. Matches id, then cliType/name (whitespace/hyphen-insensitive). */
+function resolveAgent(input: string): AgentConfig | undefined {
+  const agents = listAgents();
+  const norm = (s: string) => s.toLowerCase().replace(/[\s-]+/g, '');
+  const q = norm(input);
+  return agents.find((a) => a.id.toLowerCase() === input.toLowerCase())
+    || agents.find((a) => norm(a.id) === q)
+    || agents.find((a) => norm(a.cliType || '') === q || norm(a.name) === q)
+    || agents.find((a) => norm(a.name).includes(q) || norm(a.cliType || '').includes(q));
+}
+
+/** The settings.agents `tool` discriminator for a (possibly built-in) agent. */
+function toolFor(a: AgentConfig): 'claude' | 'codex' | 'aider' | 'opencode' {
+  if (['claude', 'codex', 'aider', 'opencode'].includes(a.id)) return a.id as 'claude';
+  if (a.cliType === 'claude-code') return 'claude';
+  if (a.cliType === 'codex') return 'codex';
+  if (a.cliType === 'aider') return 'aider';
+  return 'claude';
+}
+
+export function registerIntegrationTools(server: McpServer): void {
+  server.tool(
+    'forge_list_agents',
+    'List the CLI coding agents Forge can drive (claude code, codex, aider, and any custom profiles): whether each is installed and enabled, which is the current default, and any per-component model overrides. Use this to answer "is Claude integrated?".',
+    {},
+    () => guard(() => {
+      const agents = listAgents();
+      const def = getDefaultAgentId();
+      const settings = loadSettings();
+      const lines = agents.map((a) => {
+        const installed = a.path ? `installed` : 'NOT installed';
+        const models = settings.agents?.[a.id]?.models || {};
+        const modelStr = Object.entries(models).filter(([, v]) => v).map(([k, v]) => `${k}=${v}`).join(', ');
+        return `• ${a.id} (${a.name}) [${a.cliType || a.type}] — ${installed}, ${a.enabled ? 'enabled' : 'disabled'}${a.id === def ? '  ⭐ DEFAULT' : ''}`
+          + (modelStr ? `\n    models: ${modelStr}` : '');
+      });
+      return text(`CLI agents (default = ${def}):\n${lines.join('\n')}\n\nSet the default with forge_set_default_agent; set a component's model with forge_set_agent_model.`);
+    }),
+  );
+
+  server.tool(
+    'forge_set_default_agent',
+    'Set the default CLI coding agent Forge uses for tasks and pipelines (e.g. "claude" / "claude code", "codex"). Accepts a fuzzy name and validates it exists.',
+    { agent: z.string().describe('Agent name or id, e.g. "claude", "claude code", "codex"') },
+    (params) => guard(() => {
+      const match = resolveAgent(params.agent);
+      if (!match) return fail(`No agent matches "${params.agent}". Available: ${listAgents().map((a) => a.id).join(', ')}.`);
+      const s = loadSettings();
+      s.defaultAgent = match.id;
+      saveSettings(s);
+      clearAgentCache();
+      const warn = match.path ? '' : `\n(Note: ${match.id} is not currently installed — install it for tasks to run.)`;
+      return text(`Default agent set to ${match.id} (${match.name}).${warn}`);
+    }),
+  );
+
+  server.tool(
+    'forge_set_agent_model',
+    'Set the model an agent uses for a specific component/scene — this is how Forge runs different models for different components. Scenes: task, terminal, telegram, help, mobile. Use model "default" to clear an override.',
+    {
+      agent: z.string().describe('Agent name or id (e.g. "claude")'),
+      scene: z.enum(SCENES).describe('Which component the model applies to'),
+      model: z.string().describe('Model id (e.g. "claude-opus-4-8"), or "default" to clear'),
+    },
+    (params) => guard(() => {
+      const match = resolveAgent(params.agent);
+      if (!match) return fail(`No agent matches "${params.agent}". Available: ${listAgents().map((a) => a.id).join(', ')}.`);
+      const s = loadSettings();
+      const entry = s.agents?.[match.id] ? { ...s.agents[match.id] } : { tool: toolFor(match) };
+      if (!entry.tool) entry.tool = toolFor(match);
+      entry.models = { ...(entry.models || {}), [params.scene]: params.model };
+      s.agents = { ...(s.agents || {}), [match.id]: entry };
+      saveSettings(s);
+      clearAgentCache();
+      return text(`Set ${match.id} ${params.scene} model to "${params.model}".`);
+    }),
+  );
+}