@juancr11/sibu 0.7.0 → 0.9.0

package/README.md

@@ -42,6 +42,95 @@ Use `sibu skills list` to list available workflow skills and see which selectabl
 
 Use `sibu skills stop <file>` to stop managing an Sibu-tracked workflow file. The file is marked as `unmanaged` in `.sibu/state.json`, removed from the selected skill state when applicable, and the CLI asks whether to keep or delete the local file.
 
+## MCP server setup
+
+Sibu can generate MCP server configuration for supported agents. The first supported server is GitHub's official MCP server.
+
+Sibu only writes and tracks MCP config files. Runtime prerequisites, credentials, and provider authentication remain user-owned.
+
+### 1. Confirm available MCP servers
+
+From a Sibu-managed project, run:
+
+```sh
+sibu mcp list
+```
+
+This shows each available MCP server and whether it is already selected for the project.
+
+### 2. Configure the GitHub MCP server
+
+You can select GitHub during `sibu init`, or add it later:
+
+```sh
+sibu mcp use github
+```
+
+Sibu writes the relevant config for the agents selected in the project:
+
+- Codex: `.codex/config.toml`
+- Claude: `.mcp.json`
+- Gemini: `.gemini/settings.json`
+
+All supported agents use GitHub's hosted MCP endpoint instead of requiring Docker. Codex uses Codex's native bearer-token environment variable setting:
+
+```toml
+[mcp_servers.github]
+url = "https://api.githubcopilot.com/mcp/"
+bearer_token_env_var = "GITHUB_PERSONAL_ACCESS_TOKEN"
+```
+
+Claude uses HTTP MCP config with an authorization header:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Gemini uses streamable HTTP config with an authorization header:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "httpUrl": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### 3. Provide GitHub credentials
+
+Create a GitHub personal access token with the repository permissions your agent should have, then expose it as an environment variable before launching the agent:
+
+```sh
+export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
+```
+
+Do not commit tokens or write them into Sibu-managed config files. The generated configs read `GITHUB_PERSONAL_ACCESS_TOKEN` from the environment so credentials can stay outside the repository.
+
+### 4. Stop managing the GitHub MCP server
+
+To remove GitHub from Sibu's selected MCP server state, run:
+
+```sh
+sibu mcp stop github
+```
+
+Sibu updates generated agent config where possible and asks whether to keep or delete MCP-only config files.
+
 ## Release notes and changelog
 
 For every Sibu release, update both release-note locations:

package/bin/entrypoints/cli/create-program.js

@@ -29,5 +29,18 @@ export function createProgram() {
         .command('stop <skill_name>')
         .description('Stop managing one selected Sibu skill')
         .action((skillName) => executeCliCommand({ type: 'skills:stop', skillName }));
+    const mcp = cli.command('mcp').description('Manage Sibu MCP server configuration');
+    mcp
+        .command('list')
+        .description('List available MCP servers')
+        .action(() => executeCliCommand({ type: 'mcp:list' }));
+    mcp
+        .command('use <mcp_server_id>')
+        .description('Add one available MCP server to a clean Sibu workflow')
+        .action((serverId) => executeCliCommand({ type: 'mcp:use', serverId }));
+    mcp
+        .command('stop <mcp_server_id>')
+        .description('Stop managing one selected MCP server')
+        .action((serverId) => executeCliCommand({ type: 'mcp:stop', serverId }));
     return cli;
 }

package/bin/entrypoints/cli/execute-command.js

@@ -1,5 +1,6 @@
 import { handleDoctorProject } from '../../modules/workflow-health-diagnosis/index.js';
 import { handleInitProject } from '../../modules/project-adoption/index.js';
+import { handleListMcpServers, handleStopMcpServer, handleUseMcpServer } from '../../modules/mcp-server-selection-management/index.js';
 import { handleListSkills } from '../../modules/skill-selection-management/index.js';
 import { handleStopManagingFile } from '../../modules/skill-selection-management/index.js';
 import { handleSyncProject } from '../../modules/sync-review/index.js';
@@ -24,5 +25,14 @@ export async function executeCliCommand(command) {
         case 'skills:use':
             await handleUseSkill(command);
             return;
+        case 'mcp:list':
+            await handleListMcpServers(command);
+            return;
+        case 'mcp:use':
+            await handleUseMcpServer(command);
+            return;
+        case 'mcp:stop':
+            await handleStopMcpServer(command);
+            return;
     }
 }

package/bin/modules/interactive-guidance/index.js

@@ -1 +1 @@
-export { askForArchitectureSkill, askForFrameworkSkills, askForLanguageSkills, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';
+export { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, MCP_SERVER_SELECTION_MESSAGE, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';

package/bin/modules/interactive-guidance/prompts.js

@@ -3,8 +3,9 @@ import { cancel, isCancel, multiselect, select, text } from '@clack/prompts';
 import gradient from 'gradient-string';
 import { Box, Text, render, useApp } from 'ink';
 import { useEffect } from 'react';
-import { SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS } from '../workflow-target-planning/index.js';
+import { SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_MCP_SERVERS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, } from '../workflow-target-planning/index.js';
 const NONE_OPTION_ID = 'none';
+export const MCP_SERVER_SELECTION_MESSAGE = 'Select optional MCP servers to configure. Sibu writes config files only; you own prerequisites and authentication.';
 export async function renderIntro() {
     console.log(gradient(['#39ff14', '#00e5ff', '#9b5de5']).multiline('⧖  S I B U  ⧖'));
     const app = render(_jsx(IntroPanel, {}));
@@ -56,6 +57,38 @@ export async function askForFrameworkSkills() {
         cancelMessage: 'Initialization cancelled.',
     });
 }
+export async function askForDatabaseSkills() {
+    const selectedDatabaseSkillIds = await multiselect({
+        message: 'Select the database skills this project should support.',
+        required: false,
+        options: SELECTABLE_DATABASE_SKILLS.map((skill) => ({
+            value: skill.id,
+            label: skill.name,
+            hint: skill.description,
+        })),
+    });
+    if (isCancel(selectedDatabaseSkillIds)) {
+        cancel('Initialization cancelled.');
+        process.exit(0);
+    }
+    return SELECTABLE_DATABASE_SKILLS.filter((skill) => selectedDatabaseSkillIds.includes(skill.id));
+}
+export async function askForMcpServers() {
+    const selectedMcpServerIds = await multiselect({
+        message: MCP_SERVER_SELECTION_MESSAGE,
+        required: false,
+        options: SELECTABLE_MCP_SERVERS.map((server) => ({
+            value: server.id,
+            label: server.name,
+            hint: server.description,
+        })),
+    });
+    if (isCancel(selectedMcpServerIds)) {
+        cancel('Initialization cancelled.');
+        process.exit(0);
+    }
+    return SELECTABLE_MCP_SERVERS.filter((server) => selectedMcpServerIds.includes(server.id));
+}
 async function askForFrameworkSkillSelection({ message, cancelMessage, }) {
     const selectedFrameworkSkillIds = await multiselect({
         message,

package/bin/modules/mcp-server-selection-management/index.js

@@ -0,0 +1,3 @@
+export { getMcpServerListItems, handleListMcpServers } from './list-mcp-servers/handler.js';
+export { getNextMcpSelection, handleUseMcpServer } from './use-mcp-server/handler.js';
+export { applyStoppedMcpFileDeleteDecision, getNextStoppedMcpSelection, handleStopMcpServer, stopSelectedMcpServer } from './stop-mcp-server/handler.js';

package/bin/modules/mcp-server-selection-management/list-mcp-servers/command.js

@@ -0,0 +1 @@
+export {};

package/bin/modules/mcp-server-selection-management/list-mcp-servers/handler.js

@@ -0,0 +1,46 @@
+import { intro, log, outro } from '@clack/prompts';
+import chalk from 'chalk';
+import { SELECTABLE_MCP_SERVERS } from '../../workflow-target-planning/index.js';
+import { getProjectContext } from '../../../shared/paths.js';
+import { renderIntro } from '../../interactive-guidance/index.js';
+import { readStateForDoctor } from '../../workflow-state-registry/index.js';
+const defaultDependencies = {
+    renderIntro,
+    intro,
+    logMessage: log.message,
+    logWarn: log.warn,
+    logInfo: log.info,
+    outro,
+    getStatePath: () => getProjectContext().statePath,
+    readState: readStateForDoctor,
+};
+export async function handleListMcpServers(_command, dependencies = defaultDependencies) {
+    await dependencies.renderIntro();
+    dependencies.intro(chalk.cyan('Available MCP servers'));
+    const statePath = dependencies.getStatePath();
+    const stateResult = dependencies.readState(statePath);
+    const state = stateResult.ok ? stateResult.state : undefined;
+    if (!stateResult.ok) {
+        dependencies.logWarn(`${stateResult.message} Showing available MCP servers without project state.`);
+        dependencies.logInfo('Run `sibu init` before selecting project MCP servers.');
+    }
+    dependencies.logInfo('Sibu configures MCP files only; prerequisites, credentials, and provider authentication remain user-owned.');
+    dependencies.logMessage(chalk.bold('MCP servers'));
+    for (const server of getMcpServerListItems(state)) {
+        const marker = server.selected ? chalk.green('● selected') : chalk.dim('○ available');
+        console.log(`  ${marker} ${chalk.bold(server.name)} ${chalk.dim(`(${server.id})`)}`);
+        console.log(`    ${chalk.dim(server.description)}`);
+        console.log(`    ${chalk.dim(`Source: ${server.source}`)}`);
+    }
+    dependencies.outro(chalk.green('MCP server list ready.'));
+}
+export function getMcpServerListItems(state) {
+    const selectedServerIds = new Set(state?.selectedMcpServers ?? []);
+    return SELECTABLE_MCP_SERVERS.map((server) => ({
+        name: server.name,
+        id: server.id,
+        description: server.description,
+        source: server.source,
+        selected: selectedServerIds.has(server.id),
+    }));
+}

package/bin/modules/mcp-server-selection-management/stop-mcp-server/command.js

@@ -0,0 +1 @@
+export {};

package/bin/modules/mcp-server-selection-management/stop-mcp-server/handler.js

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cancel, isCancel, log, select } from '@clack/prompts';
+import { STATE_RELATIVE_PATH } from '../../../shared/catalog.js';
+import { readFileHashIfPresent, sha256 } from '../../../shared/hash.js';
+import { removeUndefinedFields } from '../../../shared/object.js';
+import { getProjectContext } from '../../../shared/paths.js';
+import { renderMissingWorkflowFiles, resolveSelectableMcpServerById } from '../../workflow-target-planning/index.js';
+import { getWorkflowMutationReadiness } from '../../workflow-mutation-readiness/index.js';
+import { getTemplateVersion, readTemplateManifest } from '../../template-catalog-rendering/index.js';
+import { cloneState, writeStateFile } from '../../workflow-state-registry/index.js';
+import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, } from '../../workflow-target-planning/index.js';
+export async function handleStopMcpServer(command) {
+    const { rootPath, statePath } = getProjectContext();
+    const readiness = getWorkflowMutationReadiness({ rootPath, statePath });
+    if (!readiness.ok) {
+        log.error(readiness.message);
+        log.info(readiness.hint);
+        for (const preview of readiness.actionablePreviews?.slice(0, 3) ?? []) {
+            log.info(`${preview.relativePath}: ${preview.status}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const result = stopSelectedMcpServer({ rootPath, state: readiness.state, serverId: command.serverId });
+    switch (result.status) {
+        case 'blocked':
+            log.error(result.message);
+            if (result.hint) {
+                log.info(result.hint);
+            }
+            process.exitCode = 1;
+            return;
+        case 'noop':
+            log.success(result.message);
+            log.info('No files changed.');
+            return;
+        case 'stopped':
+            writeStateFile(statePath, result.state);
+            log.success(`Updated ${STATE_RELATIVE_PATH}`);
+            log.success(`Stopped ${result.serverName}.`);
+            for (const [index, stoppedPath] of result.stoppedPaths.entries()) {
+                await askToDeleteStoppedMcpFile(stoppedPath, result.stoppedFiles[index]);
+            }
+            return;
+    }
+}
+export function getNextStoppedMcpSelection(state, serverId) {
+    const resolution = resolveSelectableMcpServerById(serverId);
+    if (!resolution.ok) {
+        return { status: 'blocked', message: resolution.message };
+    }
+    const selectedMcpServerIds = [...(state.selectedMcpServers ?? [])];
+    if (!selectedMcpServerIds.includes(resolution.resolved.server.id)) {
+        return { status: 'noop', message: `${resolution.resolved.server.name} is not selected.` };
+    }
+    return {
+        status: 'selected',
+        serverName: resolution.resolved.server.name,
+        remainingMcpServers: selectedMcpServerIds.filter((selectedServerId) => selectedServerId !== resolution.resolved.server.id).map(getMcpServerById),
+    };
+}
+export function stopSelectedMcpServer({ rootPath, state, serverId }) {
+    const selectionResult = getNextStoppedMcpSelection(state, serverId);
+    if (selectionResult.status !== 'selected') {
+        return selectionResult;
+    }
+    const selectedAgents = getSelectedAgentsFromState(state);
+    const selectedLanguageSkills = getSelectedLanguageSkillsFromState(state);
+    const selectedFrameworkSkills = getSelectedFrameworkSkillsFromState(state);
+    const selectedArchitectureSkill = getSelectedArchitectureSkillFromState(state);
+    const selectedWorkflowSkills = getSelectedWorkflowSkillsFromState(state);
+    const selectedDatabaseSkills = getSelectedDatabaseSkillsFromState(state);
+    const previousTargets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, getSelectedMcpServersFromState(state));
+    const nextTargets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectionResult.remainingMcpServers);
+    const manifest = readTemplateManifest();
+    const nextState = cloneState(state);
+    const nextTargetsByPath = new Map(nextTargets.map((target) => [target.targetPath, target]));
+    const stoppedPaths = [];
+    const stoppedFiles = [];
+    nextState.selectedMcpServers = selectionResult.remainingMcpServers.map((server) => server.id);
+    nextState.templateVersion = manifest.templateVersion;
+    nextState.updatedAt = new Date().toISOString();
+    for (const previousTarget of previousTargets.filter((target) => target.mcpConfigAgentId)) {
+        const relativePath = path.relative(rootPath, previousTarget.targetPath);
+        const managedFile = nextState.managedFiles[relativePath];
+        if (!managedFile) {
+            return {
+                status: 'blocked',
+                message: `${relativePath} is not recorded in ${STATE_RELATIVE_PATH}.`,
+                hint: 'Run `sibu sync` to review workflow state before stopping this MCP server.',
+            };
+        }
+        const nextTarget = nextTargetsByPath.get(previousTarget.targetPath);
+        if (nextTarget) {
+            const [file] = renderMissingWorkflowFiles({
+                missingTargets: [nextTarget],
+                selectedLanguageSkills,
+                selectedFrameworkSkills,
+                selectedArchitectureSkill,
+                selectedWorkflowSkills,
+                selectedDatabaseSkills,
+                selectedMcpServers: selectionResult.remainingMcpServers,
+            });
+            fs.mkdirSync(path.dirname(file.targetPath), { recursive: true });
+            fs.writeFileSync(file.targetPath, file.contents, 'utf8');
+            nextState.managedFiles[relativePath] = removeUndefinedFields({
+                ...managedFile,
+                templateVersion: getTemplateVersion(manifest, managedFile.template),
+                sha256: sha256(file.contents),
+                status: managedFile.status ?? 'managed',
+            });
+            continue;
+        }
+        const stoppedFile = removeUndefinedFields({
+            ...managedFile,
+            templateVersion: getTemplateVersion(manifest, managedFile.template),
+            sha256: readFileHashIfPresent(previousTarget.targetPath) ?? managedFile.sha256,
+            status: 'unmanaged',
+            reason: 'Stopped by `sibu mcp stop`.',
+        });
+        nextState.managedFiles[relativePath] = stoppedFile;
+        stoppedPaths.push({ relativePath, absolutePath: previousTarget.targetPath });
+        stoppedFiles.push(stoppedFile);
+    }
+    return { status: 'stopped', state: nextState, stoppedPaths, stoppedFiles, serverName: selectionResult.serverName };
+}
+export async function askToDeleteStoppedMcpFile(managedPath, managedFile) {
+    if (!fs.existsSync(managedPath.absolutePath)) {
+        log.info(`${managedPath.relativePath} does not exist locally, so there is nothing to delete.`);
+        return;
+    }
+    if (!fs.lstatSync(managedPath.absolutePath).isFile()) {
+        log.warn(`${managedPath.relativePath} is not a regular file. I will not delete it.`);
+        return;
+    }
+    const deleteAction = await select({
+        message: `Do you also want to delete ${managedPath.relativePath} for good?`,
+        options: [
+            { value: 'keep', label: 'Keep file', hint: 'Recommended. Leave the local MCP config file unchanged.' },
+            { value: 'delete', label: 'Delete file', hint: 'Permanently remove this file from the project.' },
+        ],
+    });
+    if (isCancel(deleteAction)) {
+        cancel('Delete prompt cancelled. The file is no longer managed, but it was not deleted.');
+        process.exit(0);
+    }
+    const confirmDelete = deleteAction === 'delete' && hasLocalEdits(managedPath.absolutePath, managedFile) ? await askToConfirmEditedDelete(managedPath) : undefined;
+    applyStoppedMcpFileDeleteDecision({ managedPath, managedFile, deleteAction, confirmDelete });
+}
+export function applyStoppedMcpFileDeleteDecision({ managedPath, managedFile, deleteAction, confirmDelete, }) {
+    if (!fs.existsSync(managedPath.absolutePath)) {
+        log.info(`${managedPath.relativePath} does not exist locally, so there is nothing to delete.`);
+        return;
+    }
+    if (!fs.lstatSync(managedPath.absolutePath).isFile()) {
+        log.warn(`${managedPath.relativePath} is not a regular file. I will not delete it.`);
+        return;
+    }
+    if (deleteAction === 'keep') {
+        log.info(`Kept ${managedPath.relativePath}.`);
+        return;
+    }
+    if (hasLocalEdits(managedPath.absolutePath, managedFile) && confirmDelete !== 'delete') {
+        log.info(`Kept ${managedPath.relativePath}.`);
+        return;
+    }
+    fs.unlinkSync(managedPath.absolutePath);
+    log.success(`Deleted ${managedPath.relativePath}.`);
+}
+async function askToConfirmEditedDelete(managedPath) {
+    const confirmDelete = await select({
+        message: `${managedPath.relativePath} differs from the last Sibu-recorded hash. Delete it anyway?`,
+        options: [
+            { value: 'keep', label: 'Keep file', hint: 'Recommended. Preserve local edits.' },
+            { value: 'delete', label: 'Delete anyway', hint: 'Permanently remove the edited file.' },
+        ],
+    });
+    if (isCancel(confirmDelete)) {
+        cancel('Delete prompt cancelled. The file is no longer managed, but it was not deleted.');
+        process.exit(0);
+    }
+    return confirmDelete;
+}
+function hasLocalEdits(filePath, managedFile) {
+    return readFileHashIfPresent(filePath) !== managedFile.sha256;
+}
+function getMcpServerById(serverId) {
+    const resolution = resolveSelectableMcpServerById(serverId);
+    if (!resolution.ok) {
+        throw new Error(`Unsupported MCP server in state: ${serverId}`);
+    }
+    return resolution.resolved.server;
+}

package/bin/modules/mcp-server-selection-management/use-mcp-server/command.js

@@ -0,0 +1 @@
+export {};

package/bin/modules/mcp-server-selection-management/use-mcp-server/handler.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { log } from '@clack/prompts';
+import { STATE_RELATIVE_PATH } from '../../../shared/catalog.js';
+import { getProjectContext } from '../../../shared/paths.js';
+import { getWorkflowMutationReadiness } from '../../workflow-mutation-readiness/index.js';
+import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, renderMissingWorkflowFiles, resolveSelectableMcpServerById, writeSibuState, } from '../../workflow-target-planning/index.js';
+export async function handleUseMcpServer(command) {
+    const { rootPath, statePath } = getProjectContext();
+    const readiness = getWorkflowMutationReadiness({ rootPath, statePath });
+    if (!readiness.ok) {
+        log.error(readiness.message);
+        log.info(readiness.hint);
+        for (const preview of readiness.actionablePreviews?.slice(0, 3) ?? []) {
+            log.info(`${preview.relativePath}: ${preview.status}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const selectionResult = getNextMcpSelection(readiness.state, command.serverId);
+    switch (selectionResult.status) {
+        case 'noop':
+            log.success(selectionResult.message);
+            log.info('No files changed.');
+            return;
+        case 'blocked':
+            log.error(selectionResult.message);
+            if (selectionResult.hint) {
+                log.info(selectionResult.hint);
+            }
+            process.exitCode = 1;
+            return;
+        case 'selected':
+            applySelectedMcpServer({ rootPath, statePath, state: readiness.state, selectionResult });
+            return;
+    }
+}
+export function getNextMcpSelection(state, serverId) {
+    const resolution = resolveSelectableMcpServerById(serverId);
+    if (!resolution.ok) {
+        return { status: 'blocked', message: resolution.message };
+    }
+    const selectedMcpServerIds = [...(state.selectedMcpServers ?? [])];
+    if (selectedMcpServerIds.includes(resolution.resolved.server.id)) {
+        return { status: 'noop', message: `${resolution.resolved.server.name} is already selected.` };
+    }
+    return {
+        status: 'selected',
+        serverName: resolution.resolved.server.name,
+        selectedMcpServers: [...selectedMcpServerIds, resolution.resolved.server.id].map(getMcpServerById),
+    };
+}
+function applySelectedMcpServer({ rootPath, statePath, state, selectionResult, }) {
+    const selectedAgents = getSelectedAgentsFromState(state);
+    const selectedLanguageSkills = getSelectedLanguageSkillsFromState(state);
+    const selectedFrameworkSkills = getSelectedFrameworkSkillsFromState(state);
+    const selectedArchitectureSkill = getSelectedArchitectureSkillFromState(state);
+    const selectedWorkflowSkills = getSelectedWorkflowSkillsFromState(state);
+    const selectedDatabaseSkills = getSelectedDatabaseSkillsFromState(state);
+    const previousTargets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, getSelectedMcpServersFromState(state));
+    const targets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectionResult.selectedMcpServers);
+    const affectedTargets = getAffectedMcpTargets(previousTargets, targets);
+    const preflightError = getMcpUsePreflightError({ rootPath, state, affectedTargets, previousTargets });
+    if (preflightError) {
+        log.error(preflightError);
+        log.info('Run `sibu sync` to review workflow state before selecting an MCP server.');
+        process.exitCode = 1;
+        return;
+    }
+    const files = renderMissingWorkflowFiles({
+        missingTargets: affectedTargets,
+        selectedLanguageSkills,
+        selectedFrameworkSkills,
+        selectedArchitectureSkill,
+        selectedWorkflowSkills,
+        selectedDatabaseSkills,
+        selectedMcpServers: selectionResult.selectedMcpServers,
+    });
+    for (const file of files) {
+        const fileAlreadyExists = fs.existsSync(file.targetPath);
+        fs.mkdirSync(path.dirname(file.targetPath), { recursive: true });
+        fs.writeFileSync(file.targetPath, file.contents, 'utf8');
+        log.success(`${fileAlreadyExists ? 'Updated' : 'Created'} ${file.label}`);
+    }
+    writeSibuState({
+        rootPath,
+        statePath,
+        selectedAgents,
+        selectedLanguageSkills,
+        selectedFrameworkSkills,
+        selectedArchitectureSkill,
+        selectedWorkflowSkills,
+        selectedDatabaseSkills,
+        selectedMcpServers: selectionResult.selectedMcpServers,
+        targets,
+    });
+    log.success(`Updated ${STATE_RELATIVE_PATH}`);
+    log.success(`Added ${selectionResult.serverName}.`);
+    log.info('Sibu configured MCP files only; prerequisites, credentials, and provider authentication remain user-owned.');
+}
+function getAffectedMcpTargets(previousTargets, targets) {
+    const previousTargetPaths = new Set(previousTargets.map((target) => target.targetPath));
+    return targets.filter((target) => target.mcpConfigAgentId || (!previousTargetPaths.has(target.targetPath) && target.targetKind === 'mcp-config'));
+}
+function getMcpUsePreflightError({ rootPath, state, affectedTargets, previousTargets, }) {
+    const previousTargetPaths = new Set(previousTargets.map((target) => target.targetPath));
+    for (const target of affectedTargets) {
+        const relativePath = path.relative(rootPath, target.targetPath);
+        if (previousTargetPaths.has(target.targetPath)) {
+            if (!state.managedFiles[relativePath]) {
+                return `${relativePath} is not recorded in ${STATE_RELATIVE_PATH}.`;
+            }
+            continue;
+        }
+        if (fs.existsSync(target.targetPath)) {
+            return `${relativePath} already exists but is not recorded for this MCP selection.`;
+        }
+    }
+    return undefined;
+}
+function getMcpServerById(serverId) {
+    const resolution = resolveSelectableMcpServerById(serverId);
+    if (!resolution.ok) {
+        throw new Error(`Unsupported MCP server in state: ${serverId}`);
+    }
+    return resolution.resolved.server;
+}

package/bin/modules/project-adoption/handler.js

@@ -4,11 +4,22 @@ import { intro, log, outro } from '@clack/prompts';
 import chalk from 'chalk';
 import { STATE_RELATIVE_PATH } from '../../shared/catalog.js';
 import { getProjectContext } from '../../shared/paths.js';
-import { askForArchitectureSkill, askForFrameworkSkills, askForLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, renderIntro } from '../interactive-guidance/index.js';
+import { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, renderIntro, } from '../interactive-guidance/index.js';
 import { readStateForDoctor } from '../workflow-state-registry/index.js';
 import { getWorkflowTargets, renderMissingWorkflowFiles, writeSibuState } from '../workflow-target-planning/index.js';
-export async function handleInitProject(_command) {
-    await renderIntro();
+const defaultDependencies = {
+    renderIntro,
+    askForSupportedAgents,
+    askForMcpServers,
+    askForLanguageSkills,
+    askForFrameworkSkills,
+    askForDatabaseSkills,
+    askForArchitectureSkill,
+    askForWorkflowSkills,
+    askForProjectOverview,
+};
+export async function handleInitProject(_command, dependencies = defaultDependencies) {
+    await dependencies.renderIntro();
     intro(chalk.cyan('Setting up Sibu'));
     const { rootPath, statePath } = getProjectContext();
     if (fs.existsSync(statePath)) {
@@ -27,12 +38,14 @@ export async function handleInitProject(_command) {
         process.exitCode = 1;
         return;
     }
-    const selectedAgents = await askForSupportedAgents();
-    const selectedLanguageSkills = await askForLanguageSkills();
-    const selectedFrameworkSkills = await askForFrameworkSkills();
-    const selectedArchitectureSkill = await askForArchitectureSkill();
-    const selectedWorkflowSkills = await askForWorkflowSkills();
-    const targets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills);
+    const selectedAgents = await dependencies.askForSupportedAgents();
+    const selectedMcpServers = await dependencies.askForMcpServers();
+    const selectedLanguageSkills = await dependencies.askForLanguageSkills();
+    const selectedFrameworkSkills = await dependencies.askForFrameworkSkills();
+    const selectedDatabaseSkills = await dependencies.askForDatabaseSkills();
+    const selectedArchitectureSkill = await dependencies.askForArchitectureSkill();
+    const selectedWorkflowSkills = await dependencies.askForWorkflowSkills();
+    const targets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectedMcpServers);
     const missingTargets = targets.filter((target) => !fs.existsSync(target.targetPath));
     log.message('I will create this project’s initial AI workflow files.');
     for (const target of targets) {
@@ -45,7 +58,7 @@ export async function handleInitProject(_command) {
     }
     log.info(`${STATE_RELATIVE_PATH} is missing. I will create it.`);
     const shouldAskForOverview = missingTargets.some((target) => target.requiresProjectOverview);
-    const overview = shouldAskForOverview ? await askForProjectOverview() : undefined;
+    const overview = shouldAskForOverview ? await dependencies.askForProjectOverview() : undefined;
     const files = renderMissingWorkflowFiles({
         missingTargets,
         overview,
@@ -53,13 +66,26 @@ export async function handleInitProject(_command) {
         selectedFrameworkSkills,
         selectedArchitectureSkill,
         selectedWorkflowSkills,
+        selectedDatabaseSkills,
+        selectedMcpServers,
     });
     for (const file of files) {
         fs.mkdirSync(path.dirname(file.targetPath), { recursive: true });
         fs.writeFileSync(file.targetPath, file.contents, { encoding: 'utf8', flag: 'wx' });
         log.success(`Created ${file.label}`);
     }
-    writeSibuState({ rootPath, statePath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, targets });
+    writeSibuState({
+        rootPath,
+        statePath,
+        selectedAgents,
+        selectedLanguageSkills,
+        selectedFrameworkSkills,
+        selectedArchitectureSkill,
+        selectedWorkflowSkills,
+        selectedDatabaseSkills,
+        selectedMcpServers,
+        targets,
+    });
     log.success(`Created ${STATE_RELATIVE_PATH}`);
     outro(chalk.green('Setup complete.'));
 }