cortex-agents 5.0.0 → 5.0.1

package/dist/cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "url";
 import prompts from "prompts";
 import { PRIMARY_AGENTS, SUBAGENTS, ALL_AGENTS, DISABLED_BUILTIN_AGENTS, STALE_AGENT_FILES, getPrimaryChoices, getSubagentChoices, } from "./registry.js";
 import { CortexEngine } from "./engine/index.js";
+import { startMCPServer } from "./mcp-server.js";
 const PLUGIN_NAME = "cortex-agents";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -729,6 +730,16 @@ function status() {
     }
     console.log();
 }
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+async function mcp() {
+    try {
+        await startMCPServer();
+    }
+    catch (error) {
+        console.error("MCP server error:", error);
+        process.exit(1);
+    }
+}
 function help() {
     console.log(`${PLUGIN_NAME} v${VERSION}
 
@@ -747,6 +758,7 @@ COMMANDS:
   configure --reset               Reset model configuration to defaults
   uninstall                       Remove plugin, agents, skills, and model config
   status                          Show installation, DB stats, and model configuration
+  mcp                             Start MCP server on stdio (for Gemini, Codex, Claude CLIs)
   help                            Show this help message
 
 EXAMPLES:
@@ -759,6 +771,7 @@ EXAMPLES:
   npx ${PLUGIN_NAME} configure                  # Global model selection
   npx ${PLUGIN_NAME} configure --project        # Per-project models
   npx ${PLUGIN_NAME} status                     # Check status + DB stats
+  npx ${PLUGIN_NAME} mcp                        # Start MCP server (stdio)
 
 AGENTS:
   Primary (architect, implement, fix):
@@ -815,6 +828,12 @@ switch (command) {
     case "status":
         status();
         break;
+    case "mcp":
+        mcp().catch((err) => {
+            console.error("MCP server failed:", err.message);
+            process.exit(1);
+        });
+        break;
     case "help":
     case "--help":
     case "-h":

package/dist/mcp-server.d.ts

@@ -0,0 +1,2 @@
+export declare function startMCPServer(): Promise<void>;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AA4iBA,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAsDpD"}

package/dist/mcp-server.js

@@ -0,0 +1,555 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { exec } from "./utils/shell.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Get package version for server identification
+const VERSION = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8")).version;
+// ─── Tool Implementations ─────────────────────────────────────────────────────
+// These are stub implementations that demonstrate MCP functionality
+// In production, they would wrap the actual tool implementations from src/tools/
+const TOOL_REGISTRY = {
+    // Cortex tools
+    cortex_init: {
+        description: "Initialize .cortex directory in project root for plan storage, session history, and configuration",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            const cortexPath = path.join(context.worktree, ".cortex");
+            try {
+                if (!fs.existsSync(cortexPath)) {
+                    fs.mkdirSync(cortexPath, { recursive: true });
+                    fs.mkdirSync(path.join(cortexPath, "plans"), { recursive: true });
+                    fs.mkdirSync(path.join(cortexPath, "sessions"), { recursive: true });
+                    return `✓ Initialized .cortex directory at ${cortexPath}`;
+                }
+                else {
+                    return `✓ .cortex directory already exists at ${cortexPath}`;
+                }
+            }
+            catch (error) {
+                return `✗ Error initializing .cortex: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    cortex_status: {
+        description: "Check .cortex directory status - whether it exists, plan count, session count",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            const cortexPath = path.join(context.worktree, ".cortex");
+            if (!fs.existsSync(cortexPath)) {
+                return `✗ .cortex directory not found at ${cortexPath}\n\nRun cortex_init to initialize.`;
+            }
+            const plansPath = path.join(cortexPath, "plans");
+            const sessionsPath = path.join(cortexPath, "sessions");
+            const planCount = fs.existsSync(plansPath)
+                ? fs.readdirSync(plansPath).filter((f) => f.endsWith(".md")).length
+                : 0;
+            const sessionCount = fs.existsSync(sessionsPath)
+                ? fs.readdirSync(sessionsPath).filter((f) => f.endsWith(".md")).length
+                : 0;
+            return `✓ .cortex directory status
+
+Location: ${cortexPath}
+Plans: ${planCount}
+Sessions: ${sessionCount}`;
+        },
+    },
+    cortex_configure: {
+        description: "Configure AI models for this project (primary agents and subagents)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                scope: {
+                    type: "string",
+                    enum: ["project", "global"],
+                    description: "Configuration scope: project-specific or global",
+                },
+                primaryModel: {
+                    type: "string",
+                    description: "Model ID for primary agents",
+                },
+                subagentModel: {
+                    type: "string",
+                    description: "Model ID for subagents",
+                },
+            },
+            required: ["scope", "primaryModel", "subagentModel"],
+        },
+        handler: async (args) => {
+            return `✓ Configured models\n\nScope: ${args.scope}\nPrimary: ${args.primaryModel}\nSubagent: ${args.subagentModel}`;
+        },
+    },
+    // Worktree tools
+    worktree_list: {
+        description: "List all git worktrees for the repository",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            try {
+                const result = await exec("git", ["worktree", "list"], { cwd: context.worktree, nothrow: true });
+                if (result.exitCode === 0) {
+                    return `✓ Git worktrees:\n\n${result.stdout}`;
+                }
+                else {
+                    return `✗ Not a git repository or git worktree list failed`;
+                }
+            }
+            catch (error) {
+                return `✗ Error listing worktrees: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    worktree_open: {
+        description: "Open a git worktree in the default editor or file explorer",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Worktree name to open",
+                },
+            },
+            required: ["name"],
+        },
+        handler: async (args, context) => {
+            const worktreeName = args.name;
+            const worktreePath = path.join(context.worktree, "..", worktreeName);
+            if (fs.existsSync(worktreePath)) {
+                return `✓ Worktree path: ${worktreePath}`;
+            }
+            else {
+                return `✗ Worktree not found at ${worktreePath}`;
+            }
+        },
+    },
+    // Branch tools
+    branch_status: {
+        description: "Get current git branch status",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            try {
+                const result = await exec("git", ["branch", "--show-current"], { cwd: context.worktree, nothrow: true });
+                if (result.exitCode === 0) {
+                    const branch = result.stdout.trim();
+                    return `✓ Current branch: ${branch}`;
+                }
+                else {
+                    return `✗ Failed to get branch status`;
+                }
+            }
+            catch (error) {
+                return `✗ Error: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    branch_switch: {
+        description: "Switch to an existing git branch",
+        inputSchema: {
+            type: "object",
+            properties: {
+                branch: {
+                    type: "string",
+                    description: "Branch name to switch to",
+                },
+            },
+            required: ["branch"],
+        },
+        handler: async (args, context) => {
+            const branch = args.branch;
+            try {
+                const result = await exec("git", ["checkout", branch], { cwd: context.worktree, nothrow: true });
+                if (result.exitCode === 0) {
+                    return `✓ Switched to branch: ${branch}`;
+                }
+                else {
+                    return `✗ Failed to switch branch: ${result.stderr}`;
+                }
+            }
+            catch (error) {
+                return `✗ Error: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    // Plan tools
+    plan_list: {
+        description: "List all plans in .cortex/plans/ with preview",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of plans to return",
+                },
+            },
+            required: [],
+        },
+        handler: async (args, context) => {
+            const plansPath = path.join(context.worktree, ".cortex", "plans");
+            if (!fs.existsSync(plansPath)) {
+                return `No plans found. Run cortex_init to initialize.`;
+            }
+            const files = fs.readdirSync(plansPath).filter((f) => f.endsWith(".md")).sort().reverse();
+            const limit = args.limit || 10;
+            const limited = files.slice(0, Math.min(limit, files.length));
+            if (limited.length === 0) {
+                return `No plans saved in .cortex/plans/`;
+            }
+            let output = `✓ Plans (showing ${limited.length}):\n\n`;
+            for (const file of limited) {
+                output += `  • ${file}\n`;
+            }
+            return output;
+        },
+    },
+    plan_load: {
+        description: "Load a full plan by filename",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: {
+                    type: "string",
+                    description: "Plan filename from .cortex/plans/",
+                },
+            },
+            required: ["filename"],
+        },
+        handler: async (args, context) => {
+            const filename = args.filename;
+            const filepath = path.join(context.worktree, ".cortex", "plans", filename);
+            if (!fs.existsSync(filepath)) {
+                return `✗ Plan not found: ${filename}`;
+            }
+            try {
+                const content = fs.readFileSync(filepath, "utf-8");
+                return `✓ Plan: ${filename}\n\n${content}`;
+            }
+            catch (error) {
+                return `✗ Error loading plan: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    plan_save: {
+        description: "Save an implementation plan to .cortex/plans/ with mermaid diagram support",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Plan title",
+                },
+                type: {
+                    type: "string",
+                    enum: ["feature", "bugfix", "refactor", "architecture", "spike", "docs"],
+                    description: "Plan type",
+                },
+                content: {
+                    type: "string",
+                    description: "Full plan content in markdown",
+                },
+            },
+            required: ["title", "type", "content"],
+        },
+        handler: async (args, context) => {
+            const { title, type, content } = args;
+            const plansPath = path.join(context.worktree, ".cortex", "plans");
+            try {
+                fs.mkdirSync(plansPath, { recursive: true });
+                const date = new Date().toISOString().split("T")[0];
+                const slug = title.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-");
+                const filename = `${date}-${type}-${slug}.md`;
+                const filepath = path.join(plansPath, filename);
+                fs.writeFileSync(filepath, `# ${title}\n\n${content}`);
+                return `✓ Plan saved: ${filename}`;
+            }
+            catch (error) {
+                return `✗ Error saving plan: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    plan_delete: {
+        description: "Delete a plan file",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: {
+                    type: "string",
+                    description: "Plan filename to delete",
+                },
+            },
+            required: ["filename"],
+        },
+        handler: async (args, context) => {
+            const filename = args.filename;
+            const filepath = path.join(context.worktree, ".cortex", "plans", filename);
+            if (!fs.existsSync(filepath)) {
+                return `✗ Plan not found: ${filename}`;
+            }
+            try {
+                fs.unlinkSync(filepath);
+                return `✓ Deleted plan: ${filename}`;
+            }
+            catch (error) {
+                return `✗ Error deleting plan: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    // Session tools
+    session_list: {
+        description: "List recent session summaries from .cortex/sessions/",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of sessions to return",
+                },
+            },
+            required: [],
+        },
+        handler: async (args, context) => {
+            const sessionsPath = path.join(context.worktree, ".cortex", "sessions");
+            if (!fs.existsSync(sessionsPath)) {
+                return `No sessions found. Sessions are created when you use session_save.`;
+            }
+            const files = fs.readdirSync(sessionsPath).filter((f) => f.endsWith(".md")).sort().reverse();
+            const limit = args.limit || 10;
+            const limited = files.slice(0, Math.min(limit, files.length));
+            if (limited.length === 0) {
+                return `No session summaries found in .cortex/sessions/`;
+            }
+            let output = `✓ Recent Sessions (showing ${limited.length}):\n\n`;
+            for (const file of limited) {
+                output += `  • ${file}\n`;
+            }
+            return output;
+        },
+    },
+    session_load: {
+        description: "Load a session summary by filename",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: {
+                    type: "string",
+                    description: "Session filename",
+                },
+            },
+            required: ["filename"],
+        },
+        handler: async (args, context) => {
+            const filename = args.filename;
+            const filepath = path.join(context.worktree, ".cortex", "sessions", filename);
+            if (!fs.existsSync(filepath)) {
+                return `✗ Session not found: ${filename}`;
+            }
+            try {
+                const content = fs.readFileSync(filepath, "utf-8");
+                return `✓ Session: ${filename}\n\n${content}`;
+            }
+            catch (error) {
+                return `✗ Error loading session: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    session_save: {
+        description: "Save a session summary with key decisions to .cortex/sessions/",
+        inputSchema: {
+            type: "object",
+            properties: {
+                summary: {
+                    type: "string",
+                    description: "Brief summary of what was accomplished",
+                },
+                decisions: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "List of key decisions made",
+                },
+            },
+            required: ["summary", "decisions"],
+        },
+        handler: async (args, context) => {
+            const { summary, decisions } = args;
+            const sessionsPath = path.join(context.worktree, ".cortex", "sessions");
+            try {
+                fs.mkdirSync(sessionsPath, { recursive: true });
+                const date = new Date().toISOString().split("T")[0];
+                const sessionId = Math.random().toString(36).substring(2, 10);
+                const filename = `${date}-${sessionId}.md`;
+                const filepath = path.join(sessionsPath, filename);
+                const content = `# Session Summary\n\n${summary}\n\n## Key Decisions\n\n${decisions.map((d) => `- ${d}`).join("\n")}`;
+                fs.writeFileSync(filepath, content);
+                return `✓ Session saved: ${filename}`;
+            }
+            catch (error) {
+                return `✗ Error saving session: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    // Documentation tools
+    docs_init: {
+        description: "Initialize docs directory with decision/feature/flow subdirectories",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            const docsPath = path.join(context.worktree, "docs");
+            try {
+                fs.mkdirSync(path.join(docsPath, "decisions"), { recursive: true });
+                fs.mkdirSync(path.join(docsPath, "features"), { recursive: true });
+                fs.mkdirSync(path.join(docsPath, "flows"), { recursive: true });
+                return `✓ Initialized docs directory at ${docsPath}`;
+            }
+            catch (error) {
+                return `✗ Error initializing docs: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+    docs_list: {
+        description: "List all documentation files organized by type",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            const docsPath = path.join(context.worktree, "docs");
+            if (!fs.existsSync(docsPath)) {
+                return `No docs found. Run docs_init to initialize.`;
+            }
+            const types = ["decisions", "features", "flows"];
+            let output = `✓ Documentation:\n\n`;
+            for (const type of types) {
+                const typePath = path.join(docsPath, type);
+                if (fs.existsSync(typePath)) {
+                    const files = fs.readdirSync(typePath).filter((f) => f.endsWith(".md"));
+                    output += `**${type}:** ${files.length} files\n`;
+                }
+            }
+            return output;
+        },
+    },
+    // GitHub tools
+    github_status: {
+        description: "Check GitHub CLI availability and authentication",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        handler: async (_args, context) => {
+            try {
+                const result = await exec("gh", ["auth", "status"], { cwd: context.worktree, nothrow: true });
+                if (result.exitCode === 0) {
+                    return `✓ GitHub CLI authenticated`;
+                }
+                else {
+                    return `✗ GitHub CLI not authenticated. Run: gh auth login`;
+                }
+            }
+            catch (error) {
+                return `✗ GitHub CLI not installed. Install from https://cli.github.com/`;
+            }
+        },
+    },
+    // Task tools
+    task_finalize: {
+        description: "Finalize implementation - commit, push, and create pull request",
+        inputSchema: {
+            type: "object",
+            properties: {
+                commitMessage: {
+                    type: "string",
+                    description: "Commit message",
+                },
+            },
+            required: ["commitMessage"],
+        },
+        handler: async (args, context) => {
+            const message = args.commitMessage;
+            try {
+                await exec("git", ["add", "-A"], { cwd: context.worktree, nothrow: true });
+                const result = await exec("git", ["commit", "-m", message], { cwd: context.worktree, nothrow: true });
+                if (result.exitCode === 0) {
+                    return `✓ Committed: ${message.substring(0, 50)}...`;
+                }
+                else {
+                    return `✗ Commit failed: ${result.stderr}`;
+                }
+            }
+            catch (error) {
+                return `✗ Error: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    },
+};
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+export async function startMCPServer() {
+    const mcpServer = new McpServer({
+        name: "cortex-agents",
+        version: VERSION,
+    });
+    // Get the current working directory as the worktree root
+    const worktree = process.cwd();
+    // Register all tools
+    for (const [toolName, spec] of Object.entries(TOOL_REGISTRY)) {
+        mcpServer.registerTool(toolName, {
+            description: spec.description,
+            inputSchema: spec.inputSchema,
+        }, async (args) => {
+            try {
+                const context = {
+                    worktree,
+                    directory: worktree,
+                    sessionID: "mcp-session",
+                    messageID: "mcp-message",
+                    agent: "mcp",
+                };
+                const result = await spec.handler(args, context);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // Start server on stdio
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+}

package/dist/tools/branch.d.ts

@@ -12,15 +12,15 @@ export declare function createCreate(client: Client): {
             refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
-            hotfix: "hotfix";
             docs: "docs";
+            hotfix: "hotfix";
             test: "test";
             chore: "chore";
         }>;
     };
     execute(args: {
         name: string;
-        type: "refactor" | "feature" | "bugfix" | "hotfix" | "docs" | "test" | "chore";
+        type: "refactor" | "feature" | "bugfix" | "docs" | "hotfix" | "test" | "chore";
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const status: {

package/dist/tools/plan.d.ts

@@ -8,9 +8,9 @@ export declare const save: {
             refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
+            architecture: "architecture";
             spike: "spike";
             docs: "docs";
-            architecture: "architecture";
         }>;
         content: import("zod").ZodString;
         tasks: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -18,7 +18,7 @@ export declare const save: {
     };
     execute(args: {
         title: string;
-        type: "refactor" | "feature" | "bugfix" | "spike" | "docs" | "architecture";
+        type: "refactor" | "feature" | "bugfix" | "architecture" | "spike" | "docs";
         content: string;
         tasks?: string[] | undefined;
         branch?: string | undefined;
@@ -31,14 +31,14 @@ export declare const list: {
             refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
+            architecture: "architecture";
             spike: "spike";
             docs: "docs";
-            architecture: "architecture";
             all: "all";
         }>>;
     };
     execute(args: {
-        type?: "refactor" | "feature" | "bugfix" | "spike" | "docs" | "architecture" | "all" | undefined;
+        type?: "refactor" | "feature" | "bugfix" | "architecture" | "spike" | "docs" | "all" | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const load: {

package/dist/tools/worktree.d.ts

@@ -12,16 +12,16 @@ export declare function createCreate(client: Client): {
             refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
-            hotfix: "hotfix";
             spike: "spike";
             docs: "docs";
+            hotfix: "hotfix";
             test: "test";
         }>;
         fromBranch: import("zod").ZodOptional<import("zod").ZodString>;
     };
     execute(args: {
         name: string;
-        type: "refactor" | "feature" | "bugfix" | "hotfix" | "spike" | "docs" | "test";
+        type: "refactor" | "feature" | "bugfix" | "spike" | "docs" | "hotfix" | "test";
         fromBranch?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortex-agents",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Structured AI development workflows for OpenCode and Claude Code — plan, build, ship with discipline",
   "type": "module",
   "main": "dist/index.js",
@@ -63,6 +63,7 @@
   },
   "dependencies": {
     "better-sqlite3": "^12.6.2",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "@modelcontextprotocol/sdk": "^1.0.0"
   }
 }