@juancr11/sibu 0.8.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, askForDatabaseSkills, 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_DATABASE_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, {}));
@@ -72,6 +73,22 @@ export async function askForDatabaseSkills() {
     }
     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, askForDatabaseSkills, 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,13 +38,14 @@ export async function handleInitProject(_command) {
         process.exitCode = 1;
         return;
     }
-    const selectedAgents = await askForSupportedAgents();
-    const selectedLanguageSkills = await askForLanguageSkills();
-    const selectedFrameworkSkills = await askForFrameworkSkills();
-    const selectedDatabaseSkills = await askForDatabaseSkills();
-    const selectedArchitectureSkill = await askForArchitectureSkill();
-    const selectedWorkflowSkills = await askForWorkflowSkills();
-    const targets = getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills);
+    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) {
@@ -46,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,
@@ -55,13 +67,25 @@ export async function handleInitProject(_command) {
         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, selectedDatabaseSkills, targets });
+    writeSibuState({
+        rootPath,
+        statePath,
+        selectedAgents,
+        selectedLanguageSkills,
+        selectedFrameworkSkills,
+        selectedArchitectureSkill,
+        selectedWorkflowSkills,
+        selectedDatabaseSkills,
+        selectedMcpServers,
+        targets,
+    });
     log.success(`Created ${STATE_RELATIVE_PATH}`);
     outro(chalk.green('Setup complete.'));
 }

package/bin/modules/sync-review/apply-action.js

@@ -5,7 +5,7 @@ import { sha256 } from '../../shared/hash.js';
 import { getSideTemplatePath } from '../../shared/paths.js';
 import { cloneState } from '../workflow-state-registry/index.js';
 import { getTemplateVersion, renderTemplateForSync } from '../template-catalog-rendering/index.js';
-import { getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedWorkflowSkillsFromState, } from '../workflow-target-planning/index.js';
+import { getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, } from '../workflow-target-planning/index.js';
 export function applySyncAction({ rootPath, state, manifest, preview, action, }) {
     const nextState = cloneState(state);
     const managedFile = nextState.managedFiles[preview.relativePath] ?? preview.managedFile;
@@ -21,6 +21,7 @@ export function applySyncAction({ rootPath, state, manifest, preview, action, })
                 selectedArchitectureSkill: getSelectedArchitectureSkillFromState(nextState),
                 selectedWorkflowSkills: getSelectedWorkflowSkillsFromState(nextState),
                 selectedDatabaseSkills: getSelectedDatabaseSkillsFromState(nextState),
+                selectedMcpServers: getSelectedMcpServersFromState(nextState),
             });
             fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             fs.writeFileSync(targetPath, contents, 'utf8');
@@ -58,6 +59,7 @@ export function applySyncAction({ rootPath, state, manifest, preview, action, })
                 selectedArchitectureSkill: getSelectedArchitectureSkillFromState(state),
                 selectedWorkflowSkills: getSelectedWorkflowSkillsFromState(state),
                 selectedDatabaseSkills: getSelectedDatabaseSkillsFromState(state),
+                selectedMcpServers: getSelectedMcpServersFromState(state),
             });
             fs.mkdirSync(path.dirname(sideTemplatePath), { recursive: true });
             fs.writeFileSync(sideTemplatePath, contents, 'utf8');

package/bin/modules/sync-review/sync-preview.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { sha256 } from '../../shared/hash.js';
 import { hasReviewedTemplateVersion } from '../workflow-state-registry/index.js';
 import { renderTemplateForSync } from '../template-catalog-rendering/index.js';
-import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, } from '../workflow-target-planning/index.js';
+import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, } from '../workflow-target-planning/index.js';
 const ACTIONABLE_SYNC_PREVIEW_STATUSES = new Set([
     'new-template',
     'missing',
@@ -31,6 +31,7 @@ export function getSyncPreviews({ rootPath, state, manifest }) {
     const selectedArchitectureSkill = getSelectedArchitectureSkillFromState(state);
     const selectedWorkflowSkills = getSelectedWorkflowSkillsFromState(state);
     const selectedDatabaseSkills = getSelectedDatabaseSkillsFromState(state);
+    const selectedMcpServers = getSelectedMcpServersFromState(state);
     const previews = Object.entries(state.managedFiles).map(([relativePath, managedFile]) => getManagedFileSyncPreview({
         rootPath,
         manifest,
@@ -41,8 +42,9 @@ export function getSyncPreviews({ rootPath, state, manifest }) {
         selectedArchitectureSkill,
         selectedWorkflowSkills,
         selectedDatabaseSkills,
+        selectedMcpServers,
     }));
-    const expectedTargets = getWorkflowTargets(rootPath, getSelectedAgentsFromState(state), selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills);
+    const expectedTargets = getWorkflowTargets(rootPath, getSelectedAgentsFromState(state), selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectedMcpServers);
     for (const target of expectedTargets) {
         const relativePath = path.relative(rootPath, target.targetPath);
         if (state.managedFiles[relativePath]) {
@@ -79,7 +81,7 @@ export function getSyncPreviews({ rootPath, state, manifest }) {
     }
     return previews;
 }
-function getManagedFileSyncPreview({ rootPath, manifest, relativePath, managedFile, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, }) {
+function getManagedFileSyncPreview({ rootPath, manifest, relativePath, managedFile, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectedMcpServers, }) {
     if (managedFile.status === 'unmanaged') {
         return { relativePath, managedFile, status: 'unmanaged', recordedTemplateVersion: managedFile.templateVersion, changes: [] };
     }
@@ -100,9 +102,10 @@ function getManagedFileSyncPreview({ rootPath, manifest, relativePath, managedFi
         selectedArchitectureSkill,
         selectedWorkflowSkills,
         selectedDatabaseSkills,
+        selectedMcpServers,
     });
     const hasUpdate = hasTemplateUpdate || hasSelectionUpdate;
-    const changes = hasTemplateUpdate ? template.changes : ['Refreshes generated skill routing for the current selected skills.'];
+    const changes = hasTemplateUpdate ? template.changes : [getSelectionRefreshChange(managedFile.template)];
     if (!hasLocalFile) {
         return {
             relativePath,
@@ -157,8 +160,14 @@ function getManagedFileSyncPreview({ rootPath, manifest, relativePath, managedFi
         hasLocalFile,
     };
 }
-function hasRenderedSelectionUpdate({ relativePath, currentPath, managedFile, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, }) {
-    if (relativePath !== 'AGENTS.md') {
+function getSelectionRefreshChange(templateRelativePath) {
+    if (templateRelativePath === '.codex/config.toml' || templateRelativePath === 'mcp/claude/.mcp.json' || templateRelativePath === 'mcp/gemini/settings.json') {
+        return 'Refreshes generated MCP configuration for the current selected MCP servers.';
+    }
+    return 'Refreshes generated skill routing for the current selected skills.';
+}
+function hasRenderedSelectionUpdate({ relativePath, currentPath, managedFile, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills, selectedDatabaseSkills, selectedMcpServers, }) {
+    if (relativePath !== 'AGENTS.md' && selectedMcpServers.length === 0) {
         return false;
     }
     const renderedContents = renderTemplateForSync({
@@ -169,6 +178,7 @@ function hasRenderedSelectionUpdate({ relativePath, currentPath, managedFile, se
         selectedArchitectureSkill,
         selectedWorkflowSkills,
         selectedDatabaseSkills,
+        selectedMcpServers,
     });
     return sha256(renderedContents) !== managedFile.sha256;
 }

package/bin/modules/template-catalog-rendering/index.js

@@ -1 +1 @@
-export { extractProjectOverview, getTemplateVersion, readTemplate, readTemplateManifest, renderSkillRouting, renderTemplateForSync, } from './templates.js';
+export { extractProjectOverview, getTemplateVersion, readTemplate, readTemplateManifest, renderMcpConfig, renderSkillRouting, renderTemplateForSync, } from './templates.js';

package/bin/modules/template-catalog-rendering/templates.js

@@ -18,8 +18,12 @@ export function getTemplateVersion(manifest, templateRelativePath) {
     }
     return template.version;
 }
-export function renderTemplateForSync({ templateRelativePath, currentPath, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], }) {
+export function renderTemplateForSync({ templateRelativePath, currentPath, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers = [], }) {
     let contents = readTemplate(templateRelativePath);
+    const mcpConfigAgentId = getMcpConfigAgentId(templateRelativePath);
+    if (mcpConfigAgentId) {
+        return renderMcpConfig({ agentId: mcpConfigAgentId, baseContents: contents, selectedMcpServers });
+    }
     if (contents.includes('{{PROJECT_OVERVIEW}}')) {
         contents = contents.replace('{{PROJECT_OVERVIEW}}', extractProjectOverview(currentPath) ?? 'Describe this project.');
     }
@@ -34,6 +38,18 @@ export function renderSkillRouting(contents, selectedLanguageSkills, selectedFra
         .join('\n');
     return contents.replace('{{OPTIONAL_SKILL_ROUTING}}', optionalRouting);
 }
+export function renderMcpConfig({ agentId, baseContents, selectedMcpServers, }) {
+    const githubServer = selectedMcpServers.find((server) => server.id === 'github');
+    if (!githubServer) {
+        return baseContents ?? renderJsonMcpConfig({});
+    }
+    if (agentId === 'codex') {
+        return renderCodexGithubMcpConfig(baseContents ?? '');
+    }
+    return renderJsonMcpConfig({
+        github: buildGithubMcpServerConfig(agentId),
+    });
+}
 export function extractProjectOverview(filePath) {
     if (!fs.existsSync(filePath)) {
         return undefined;
@@ -43,6 +59,45 @@ export function extractProjectOverview(filePath) {
     const overview = match?.[1]?.trim();
     return overview || undefined;
 }
+function renderCodexGithubMcpConfig(baseContents) {
+    const trimmedBaseContents = baseContents.trimEnd();
+    const separator = trimmedBaseContents ? '\n\n' : '';
+    return `${trimmedBaseContents}${separator}[mcp_servers.github]
+url = "https://api.githubcopilot.com/mcp/"
+bearer_token_env_var = "GITHUB_PERSONAL_ACCESS_TOKEN"
+`;
+}
+function getMcpConfigAgentId(templateRelativePath) {
+    if (templateRelativePath === '.codex/config.toml') {
+        return 'codex';
+    }
+    if (templateRelativePath === 'mcp/claude/.mcp.json') {
+        return 'claude';
+    }
+    if (templateRelativePath === 'mcp/gemini/settings.json') {
+        return 'gemini';
+    }
+    return undefined;
+}
+function buildGithubMcpServerConfig(agentId) {
+    const headers = {
+        Authorization: 'Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}',
+    };
+    if (agentId === 'gemini') {
+        return {
+            httpUrl: 'https://api.githubcopilot.com/mcp/',
+            headers,
+        };
+    }
+    return {
+        type: 'http',
+        url: 'https://api.githubcopilot.com/mcp/',
+        headers,
+    };
+}
+function renderJsonMcpConfig(mcpServers) {
+    return `${JSON.stringify({ mcpServers }, null, 2)}\n`;
+}
 function isTemplateManifest(value) {
     if (!value || typeof value !== 'object') {
         return false;

package/bin/modules/workflow-health-diagnosis/handler.js

@@ -3,14 +3,14 @@ import path from 'node:path';
 import { intro, log, outro } from '@clack/prompts';
 import chalk from 'chalk';
 import { STATE_RELATIVE_PATH } from '../../shared/catalog.js';
-import { SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_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, SUPPORTED_AGENTS } from '../workflow-target-planning/index.js';
 import { sha256 } from '../../shared/hash.js';
 import { checkForLatestSibuVersion } from '../version-advisory/index.js';
 import { getProjectContext } from '../../shared/paths.js';
 import { renderIntro } from '../interactive-guidance/index.js';
 import { hasReviewedTemplateVersion, readStateForDoctor } from '../workflow-state-registry/index.js';
 import { getTemplateVersion, readTemplateManifest } from '../template-catalog-rendering/index.js';
-import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, } from '../workflow-target-planning/index.js';
+import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, } from '../workflow-target-planning/index.js';
 export async function handleDoctorProject(_command) {
     await renderIntro();
     intro(chalk.cyan('Checking workflow state'));
@@ -122,6 +122,11 @@ function addUnsupportedSelectionIssues(state, issues) {
             issues.push({ severity: 'warning', message: `State references unsupported database skill: ${selectedDatabaseSkill}.` });
         }
     }
+    for (const selectedMcpServer of state.selectedMcpServers ?? []) {
+        if (!SELECTABLE_MCP_SERVERS.some((server) => server.id === selectedMcpServer)) {
+            issues.push({ severity: 'warning', message: `State references unsupported MCP server: ${selectedMcpServer}.` });
+        }
+    }
     for (const reviewedArchitectureSkill of state.reviewedArchitectureSkills ?? []) {
         if (!SELECTABLE_ARCHITECTURE_SKILLS.some((skill) => skill.id === reviewedArchitectureSkill)) {
             issues.push({ severity: 'warning', message: `State references unsupported reviewed architecture skill: ${reviewedArchitectureSkill}.` });
@@ -130,7 +135,7 @@ function addUnsupportedSelectionIssues(state, issues) {
 }
 function addExpectedTargetIssues(rootPath, state, issues) {
     const reportedMissingPaths = new Set();
-    const expectedTargets = getWorkflowTargets(rootPath, getSelectedAgentsFromState(state), getSelectedLanguageSkillsFromState(state), getSelectedFrameworkSkillsFromState(state), getSelectedArchitectureSkillFromState(state), getSelectedWorkflowSkillsFromState(state), getSelectedDatabaseSkillsFromState(state));
+    const expectedTargets = getWorkflowTargets(rootPath, getSelectedAgentsFromState(state), getSelectedLanguageSkillsFromState(state), getSelectedFrameworkSkillsFromState(state), getSelectedArchitectureSkillFromState(state), getSelectedWorkflowSkillsFromState(state), getSelectedDatabaseSkillsFromState(state), getSelectedMcpServersFromState(state));
     for (const target of expectedTargets) {
         const relativePath = path.relative(rootPath, target.targetPath);
         const managedFile = state.managedFiles[relativePath];

package/bin/modules/workflow-state-registry/state.js

@@ -59,6 +59,8 @@ function isSibuState(value) {
             (Array.isArray(state.selectedWorkflowSkills) && state.selectedWorkflowSkills.every((skill) => typeof skill === 'string'))) &&
         (state.selectedDatabaseSkills === undefined ||
             (Array.isArray(state.selectedDatabaseSkills) && state.selectedDatabaseSkills.every((skill) => typeof skill === 'string'))) &&
+        (state.selectedMcpServers === undefined ||
+            (Array.isArray(state.selectedMcpServers) && state.selectedMcpServers.every((server) => typeof server === 'string'))) &&
         (state.reviewedArchitectureSkills === undefined ||
             (Array.isArray(state.reviewedArchitectureSkills) && state.reviewedArchitectureSkills.every((skill) => typeof skill === 'string'))) &&
         !!state.managedFiles &&

package/bin/modules/workflow-target-planning/catalog.js

@@ -199,6 +199,14 @@ export const SELECTABLE_WORKFLOW_SKILLS = [
         },
     },
 ];
+export const SELECTABLE_MCP_SERVERS = [
+    {
+        id: 'github',
+        name: 'GitHub MCP Server',
+        description: "Configure GitHub's official MCP server; Sibu writes config only, while prerequisites, runtime availability, credentials, and authentication remain user-owned",
+        source: 'github/github-mcp-server',
+    },
+];
 export const SUPPORTED_AGENTS = [
     {
         id: 'codex',
@@ -227,6 +235,13 @@ export const SUPPORTED_AGENTS = [
         description: 'Use root AGENTS.md and shared .agents/skills/ discovery',
     },
 ];
+export function resolveSelectableMcpServerById(serverId) {
+    const server = SELECTABLE_MCP_SERVERS.find((selectableServer) => selectableServer.id === serverId);
+    if (server) {
+        return { ok: true, resolved: { server } };
+    }
+    return { ok: false, message: `Unknown MCP server \`${serverId}\`. Run \`sibu mcp list\` to see available MCP servers.` };
+}
 export function resolveSelectableSkillById(skillId) {
     const languageSkill = SELECTABLE_LANGUAGE_SKILLS.find((skill) => skill.id === skillId);
     if (languageSkill) {

package/bin/modules/workflow-target-planning/index.js

@@ -1,2 +1,2 @@
-export { MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, resolveSelectableSkillById, } from './catalog.js';
-export { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedSkillTargetsForAgents, getSelectedWorkflowSkillsFromState, getWorkflowTargets, renderMissingWorkflowFiles, writeSibuState, } from './workflow-targets.js';
+export { MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_MCP_SERVERS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, resolveSelectableMcpServerById, resolveSelectableSkillById, } from './catalog.js';
+export { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedMcpTargetsForAgents, getSelectedSkillTargetsForAgents, getSelectedWorkflowSkillsFromState, getWorkflowTargets, renderMissingWorkflowFiles, writeSibuState, } from './workflow-targets.js';

package/bin/modules/workflow-target-planning/workflow-targets.js

@@ -1,11 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { SIBU_VERSION } from '../version-advisory/index.js';
-import { MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, } from './index.js';
+import { MANDATORY_SKILLS, SELECTABLE_ARCHITECTURE_SKILLS, SELECTABLE_DATABASE_SKILLS, SELECTABLE_FRAMEWORK_SKILLS, SELECTABLE_LANGUAGE_SKILLS, SELECTABLE_MCP_SERVERS, SELECTABLE_WORKFLOW_SKILLS, SUPPORTED_AGENTS, } from './index.js';
 import { sha256 } from '../../shared/hash.js';
 import { removeUndefinedFields } from '../../shared/object.js';
 import { readExistingState } from '../workflow-state-registry/index.js';
-import { getTemplateVersion, readTemplate, readTemplateManifest, renderSkillRouting } from '../template-catalog-rendering/index.js';
+import { getTemplateVersion, readTemplate, readTemplateManifest, renderMcpConfig, renderSkillRouting } from '../template-catalog-rendering/index.js';
 export function getSelectedLanguageSkillsFromState(state) {
     return SELECTABLE_LANGUAGE_SKILLS.filter((skill) => state.selectedLanguageSkills?.includes(skill.id));
 }
@@ -21,6 +21,9 @@ export function getSelectedWorkflowSkillsFromState(state) {
 export function getSelectedDatabaseSkillsFromState(state) {
     return SELECTABLE_DATABASE_SKILLS.filter((skill) => state.selectedDatabaseSkills?.includes(skill.id));
 }
+export function getSelectedMcpServersFromState(state) {
+    return SELECTABLE_MCP_SERVERS.filter((server) => state.selectedMcpServers?.includes(server.id));
+}
 export function getSelectedSkillTargetsForAgents(selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = []) {
     const skillTargets = new Map();
     const selectedSkills = [
@@ -45,13 +48,49 @@ export function getSelectedSkillTargetsForAgents(selectedAgents, selectedLanguag
     }
     return [...skillTargets.values()];
 }
-export function getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills = [], selectedFrameworkSkills = [], selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = []) {
-    return [
+export function getSelectedMcpTargetsForAgents(selectedAgents, selectedMcpServers) {
+    if (!selectedMcpServers.some((server) => server.id === 'github')) {
+        return [];
+    }
+    return selectedAgents.flatMap((agent) => {
+        if (agent.id === 'codex') {
+            return [
+                {
+                    targetRelativePath: '.codex/config.toml',
+                    templateRelativePath: '.codex/config.toml',
+                    agentId: 'codex',
+                },
+            ];
+        }
+        if (agent.id === 'claude') {
+            return [
+                {
+                    targetRelativePath: '.mcp.json',
+                    templateRelativePath: 'mcp/claude/.mcp.json',
+                    agentId: 'claude',
+                },
+            ];
+        }
+        if (agent.id === 'gemini') {
+            return [
+                {
+                    targetRelativePath: '.gemini/settings.json',
+                    templateRelativePath: 'mcp/gemini/settings.json',
+                    agentId: 'gemini',
+                },
+            ];
+        }
+        return [];
+    });
+}
+export function getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSkills = [], selectedFrameworkSkills = [], selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers = []) {
+    const targets = [
         {
             label: 'AGENTS.md',
             targetPath: path.join(rootPath, 'AGENTS.md'),
             templateRelativePath: 'AGENTS.md',
             requiresProjectOverview: true,
+            targetKind: 'agent-support',
         },
         ...selectedAgents.flatMap((agent) => {
             if (!agent.targetRelativePath || !agent.templateRelativePath) {
@@ -63,6 +102,7 @@ export function getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSki
                     targetPath: path.join(rootPath, agent.targetRelativePath),
                     templateRelativePath: agent.templateRelativePath,
                     requiresProjectOverview: false,
+                    targetKind: 'agent-support',
                 },
             ];
         }),
@@ -71,12 +111,39 @@ export function getWorkflowTargets(rootPath, selectedAgents, selectedLanguageSki
             targetPath: path.join(rootPath, skillTarget.targetRelativePath),
             templateRelativePath: skillTarget.templateRelativePath,
             requiresProjectOverview: false,
+            targetKind: 'skill',
         })),
     ];
+    for (const mcpTarget of getSelectedMcpTargetsForAgents(selectedAgents, selectedMcpServers)) {
+        const targetPath = path.join(rootPath, mcpTarget.targetRelativePath);
+        const existingTarget = targets.find((target) => target.targetPath === targetPath);
+        if (existingTarget) {
+            existingTarget.selectedMcpServers = selectedMcpServers;
+            existingTarget.mcpConfigAgentId = mcpTarget.agentId;
+            continue;
+        }
+        targets.push({
+            label: mcpTarget.targetRelativePath,
+            targetPath,
+            templateRelativePath: mcpTarget.templateRelativePath,
+            requiresProjectOverview: false,
+            targetKind: 'mcp-config',
+            mcpConfigAgentId: mcpTarget.agentId,
+            selectedMcpServers,
+        });
+    }
+    return targets;
 }
-export function renderMissingWorkflowFiles({ missingTargets, overview, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], }) {
+export function renderMissingWorkflowFiles({ missingTargets, overview, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers = [], }) {
     return missingTargets.map((target) => {
         let contents = readTemplate(target.templateRelativePath);
+        if (target.mcpConfigAgentId && (target.selectedMcpServers?.length || selectedMcpServers.length)) {
+            contents = renderMcpConfig({
+                agentId: target.mcpConfigAgentId,
+                baseContents: contents,
+                selectedMcpServers: target.selectedMcpServers ?? selectedMcpServers,
+            });
+        }
         if (target.requiresProjectOverview) {
             if (!overview?.trim()) {
                 throw new Error('Project overview is required to create AGENTS.md.');
@@ -91,7 +158,7 @@ export function renderMissingWorkflowFiles({ missingTargets, overview, selectedL
         };
     });
 }
-export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], targets, }) {
+export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers, targets, }) {
     const previousState = readExistingState(statePath);
     const now = new Date().toISOString();
     const manifest = readTemplateManifest();
@@ -106,6 +173,7 @@ export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLa
         selectedArchitectureSkill: selectedArchitectureSkill?.id,
         selectedWorkflowSkills: selectedWorkflowSkills.map((skill) => skill.id),
         selectedDatabaseSkills: selectedDatabaseSkills.map((skill) => skill.id),
+        ...(selectedMcpServers !== undefined ? { selectedMcpServers: selectedMcpServers.map((server) => server.id) } : {}),
         managedFiles: Object.fromEntries(targets
             .filter((target) => fs.existsSync(target.targetPath))
             .map((target) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "70",
+  "templateVersion": "74",
   "templates": {
     "AGENTS.md": {
       "version": "25",
@@ -9,10 +9,10 @@
       ]
     },
     ".codex/config.toml": {
-      "version": "1",
-      "description": "Codex configuration pointing to AGENTS.md.",
+      "version": "2",
+      "description": "Codex configuration pointing to AGENTS.md and rendering selected MCP servers with Codex-compatible settings.",
       "changes": [
-        "Configures Codex to use the root AGENTS.md instructions file."
+        "Updates Codex GitHub MCP rendering to use the hosted HTTPS endpoint with bearer_token_env_var instead of Docker command arguments."
       ]
     },
     "GEMINI.md": {
@@ -29,6 +29,20 @@
         "Delegates Claude project instructions to AGENTS.md as the source of truth."
       ]
     },
+    "mcp/claude/.mcp.json": {
+      "version": "2",
+      "description": "Claude MCP configuration template managed when selectable MCP servers are selected.",
+      "changes": [
+        "Updates Claude GitHub MCP rendering to use the hosted HTTPS endpoint with an Authorization header instead of Docker."
+      ]
+    },
+    "mcp/gemini/settings.json": {
+      "version": "2",
+      "description": "Gemini MCP configuration template managed when selectable MCP servers are selected.",
+      "changes": [
+        "Updates Gemini GitHub MCP rendering to use the hosted streamable HTTP endpoint with an Authorization header instead of Docker."
+      ]
+    },
     "skills/clean-code/SKILL.md": {
       "version": "4",
       "description": "Mandatory clean-code skill installed once at the shared .agents/skills workspace path.",
@@ -116,10 +130,10 @@
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {
-      "version": "7",
+      "version": "8",
       "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
       "changes": [
-        "Updates Scrum planning guidance to preserve Deep Module implementation boundaries from technical designs."
+        "Adds optional GitHub issue export guidance after Scrum planning when GitHub MCP tools are available."
       ]
     },
     "skills/ai-implementation-planner/SKILL.md": {

package/templates/mcp/claude/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/templates/mcp/gemini/settings.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/templates/skills/scrum-master-planner/SKILL.md

@@ -210,6 +210,28 @@ Before finishing, verify:
 - no Story adds scope that is absent from the feature brief or technical design
 - acceptance criteria are testable enough for a reviewer
 
+### 6. Optionally export planning artifacts to GitHub Issues
+
+After all local Epic and User Story files are written, check whether GitHub MCP tools are available for issue creation, label creation, and native sub-issue mutation.
+
+If any required GitHub MCP capability is unavailable, do not offer GitHub export. Finish with the normal local planning response.
+
+If the required GitHub MCP capabilities are available:
+
+1. Resolve the target repository from the current local repo's GitHub `origin` remote only. Do not ask for or use another repository.
+2. Ask one explicit opt-in question before any GitHub mutation: "GitHub MCP is available. Create GitHub Issues for these Epics and User Stories in the current repo?"
+3. If the user declines, perform no GitHub mutation.
+4. If the user accepts, create a fresh issue set every time. Do not search for duplicates or update existing issues.
+5. Create missing labels before creating issues: `epic`, `user-story`, and `sibu-generated`.
+6. Create one issue per Epic with labels `epic` and `sibu-generated`.
+7. Create one issue per User Story with labels `user-story` and `sibu-generated`.
+8. Attach each User Story issue as a native GitHub sub-issue of its parent Epic issue.
+9. Report created issue numbers or URLs.
+
+Keep issue bodies concise and source-grounded. Include the source local doc path and relevant summary, scope, acceptance criteria, or validation notes. Do not modify local Markdown files with GitHub URLs.
+
+Native sub-issues are required for this export. Preserve each created User Story issue's GitHub issue `id` because native sub-issue APIs need the child issue ID, not only its issue number. If label creation, issue creation, issue ID access, or native sub-issue attachment fails or is unavailable, fail clearly and do not fall back to Markdown checklists, loose links, GitHub Projects, milestones, assignees, or status tracking.
+
 ## Final response behavior
 
 After writing files, final-answer with only: