cognitive-modules-cli 1.2.0 → 1.3.0

package/README.md

@@ -33,17 +33,20 @@ cog list
 echo "review this code" | cog pipe --module code-reviewer
 ```
 
-## 与 Python 版的区别
+## 与 Python 版的功能对比
 
 | 功能 | Python (`cogn`) | Node.js (`cog`) |
 |------|----------------|-----------------|
-| 包名 | `cognitive-modules` | `cognitive-modules-cli` |
+| 包名 | `cognitive-modules` | `cogn` / `cognitive-modules-cli` |
 | 安装 | `pip install` | `npm install -g` |
-| 子代理 | ✅ `@call:module` | ❌ 暂不支持 |
-| MCP Server | ✅ | ❌ 暂不支持 |
-| HTTP Server | ✅ | ❌ 暂不支持 |
+| 子代理 | ✅ `@call:module` | ✅ `@call:module` |
+| MCP Server | ✅ | ✅ |
+| HTTP Server | ✅ | ✅ |
+| v2.2 Envelope | ✅ | ✅ |
 
-两个版本共享相同的模块格式和 v2.2 规范。
+两个版本功能完全一致，共享相同的模块格式和 v2.2 规范。
+
+**推荐使用 Node.js 版**：零安装快速体验 `npx cogn run ...`
 
 ## 支持的 Provider
 
@@ -61,14 +64,19 @@ echo "review this code" | cog pipe --module code-reviewer
 ## 命令
 
 ```bash
-cog list                    # 列出模块
+# 模块操作
+cog list                      # 列出模块
 cog run <module> --args "..." # 运行模块
-cog add <url> -m <module>   # 从 GitHub 添加模块
-cog update <module>         # 更新模块
-cog remove <module>         # 删除模块
-cog versions <url>          # 查看可用版本
-cog init <name>             # 创建新模块
-cog pipe --module <name>    # 管道模式
+cog add <url> -m <module>     # 从 GitHub 添加模块
+cog update <module>           # 更新模块
+cog remove <module>           # 删除模块
+cog versions <url>            # 查看可用版本
+cog init <name>               # 创建新模块
+cog pipe --module <name>      # 管道模式
+
+# 服务器
+cog serve --port 8000         # 启动 HTTP API 服务
+cog mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 ```
 
 ## 开发

package/dist/cli.js

@@ -16,7 +16,7 @@
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init, add, update, remove, versions } from './commands/index.js';
-const VERSION = '1.0.1';
+const VERSION = '1.3.0';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -45,6 +45,9 @@ async function main() {
             tag: { type: 'string', short: 't' },
             branch: { type: 'string', short: 'b' },
             limit: { type: 'string', short: 'l' },
+            // Server options
+            host: { type: 'string', short: 'H' },
+            port: { type: 'string', short: 'P' },
         },
         allowPositionals: true,
     });
@@ -249,6 +252,29 @@ async function main() {
                 }
                 break;
             }
+            case 'serve': {
+                const { serve } = await import('./server/http.js');
+                const port = values.port ? parseInt(values.port, 10) : 8000;
+                const host = values.host || '0.0.0.0';
+                console.log('Starting Cognitive Modules HTTP Server...');
+                await serve({ host, port, cwd: ctx.cwd });
+                break;
+            }
+            case 'mcp': {
+                try {
+                    const { serve: serveMcp } = await import('./mcp/server.js');
+                    await serveMcp();
+                }
+                catch (e) {
+                    if (e instanceof Error && e.message.includes('Cannot find module')) {
+                        console.error('MCP dependencies not installed.');
+                        console.error('Install with: npm install @modelcontextprotocol/sdk');
+                        process.exit(1);
+                    }
+                    throw e;
+                }
+                break;
+            }
             default:
                 console.error(`Unknown command: ${command}`);
                 console.error('Run "cog --help" for usage.');
@@ -280,6 +306,8 @@ COMMANDS:
   versions <url>    List available versions
   pipe              Pipe mode (stdin/stdout)
   init [name]       Initialize project or create module
+  serve             Start HTTP API server
+  mcp               Start MCP server (for Claude Code, Cursor)
   doctor            Check configuration
 
 OPTIONS:
@@ -294,6 +322,8 @@ OPTIONS:
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
+  -H, --host <host>     Server host (default: 0.0.0.0)
+  -P, --port <port>     Server port (default: 8000)
   -v, --version         Show version
   -h, --help            Show this help
 
@@ -312,6 +342,10 @@ EXAMPLES:
   cog run code-reviewer --provider openai --model gpt-4o --args "..."
   cog list
 
+  # Servers
+  cog serve --port 8080
+  cog mcp
+
   # Other
   echo "review this code" | cog pipe --module code-reviewer
   cog init my-module

package/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * MCP Server - Re-export all MCP functionality
+ */
+export { serve } from './server.js';

package/dist/mcp/index.js

@@ -0,0 +1,4 @@
+/**
+ * MCP Server - Re-export all MCP functionality
+ */
+export { serve } from './server.js';

package/dist/mcp/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Cognitive Modules MCP Server
+ *
+ * Provides MCP (Model Context Protocol) interface for Claude Code, Cursor, etc.
+ *
+ * Start with:
+ *   cog mcp
+ */
+export declare function serve(): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,344 @@
+/**
+ * Cognitive Modules MCP Server
+ *
+ * Provides MCP (Model Context Protocol) interface for Claude Code, Cursor, etc.
+ *
+ * Start with:
+ *   cog mcp
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { findModule, listModules, getDefaultSearchPaths } from '../modules/loader.js';
+import { runModule } from '../modules/runner.js';
+import { getProvider } from '../providers/index.js';
+// =============================================================================
+// Server Setup
+// =============================================================================
+const server = new Server({
+    name: 'cognitive-modules',
+    version: '1.2.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+    },
+});
+const cwd = process.cwd();
+const searchPaths = getDefaultSearchPaths(cwd);
+// =============================================================================
+// Tools
+// =============================================================================
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'cognitive_run',
+                description: 'Run a Cognitive Module to get structured AI analysis results',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        module: {
+                            type: 'string',
+                            description: 'Module name, e.g. "code-reviewer", "task-prioritizer"',
+                        },
+                        args: {
+                            type: 'string',
+                            description: 'Input arguments, e.g. code snippet or task list',
+                        },
+                        provider: {
+                            type: 'string',
+                            description: 'LLM provider (optional), e.g. "openai", "anthropic"',
+                        },
+                        model: {
+                            type: 'string',
+                            description: 'Model name (optional), e.g. "gpt-4o", "claude-3-5-sonnet"',
+                        },
+                    },
+                    required: ['module', 'args'],
+                },
+            },
+            {
+                name: 'cognitive_list',
+                description: 'List all installed Cognitive Modules',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'cognitive_info',
+                description: 'Get detailed information about a Cognitive Module',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        module: {
+                            type: 'string',
+                            description: 'Module name',
+                        },
+                    },
+                    required: ['module'],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'cognitive_run': {
+                const { module: moduleName, args: inputArgs, provider: providerName, model } = args;
+                // Find module
+                const moduleData = await findModule(moduleName, searchPaths);
+                if (!moduleData) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
+                            },
+                        ],
+                    };
+                }
+                // Create provider
+                const provider = getProvider(providerName, model);
+                // Run module
+                const result = await runModule(moduleData, provider, {
+                    input: { query: inputArgs, code: inputArgs },
+                    useV22: true,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'cognitive_list': {
+                const modules = await listModules(searchPaths);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                modules: modules.map((m) => ({
+                                    name: m.name,
+                                    location: m.location,
+                                    format: m.format,
+                                    tier: m.tier,
+                                })),
+                                count: modules.length,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'cognitive_info': {
+                const { module: moduleName } = args;
+                const moduleData = await findModule(moduleName, searchPaths);
+                if (!moduleData) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({ ok: false, error: `Module '${moduleName}' not found` }),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: true,
+                                name: moduleData.name,
+                                version: moduleData.version,
+                                responsibility: moduleData.responsibility,
+                                tier: moduleData.tier,
+                                format: moduleData.format,
+                                inputSchema: moduleData.inputSchema,
+                                outputSchema: moduleData.outputSchema,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ ok: false, error: `Unknown tool: ${name}` }),
+                        },
+                    ],
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        ok: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    }),
+                },
+            ],
+        };
+    }
+});
+// =============================================================================
+// Resources
+// =============================================================================
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const modules = await listModules(searchPaths);
+    return {
+        resources: [
+            {
+                uri: 'cognitive://modules',
+                name: 'All Modules',
+                description: 'List of all installed Cognitive Modules',
+                mimeType: 'application/json',
+            },
+            ...modules.map((m) => ({
+                uri: `cognitive://module/${m.name}`,
+                name: m.name,
+                description: m.responsibility || `Cognitive Module: ${m.name}`,
+                mimeType: 'text/markdown',
+            })),
+        ],
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (uri === 'cognitive://modules') {
+        const modules = await listModules(searchPaths);
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(modules.map((m) => m.name), null, 2),
+                },
+            ],
+        };
+    }
+    const match = uri.match(/^cognitive:\/\/module\/(.+)$/);
+    if (match) {
+        const moduleName = match[1];
+        const moduleData = await findModule(moduleName, searchPaths);
+        if (!moduleData) {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/plain',
+                        text: `Module '${moduleName}' not found`,
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/markdown',
+                    text: moduleData.prompt,
+                },
+            ],
+        };
+    }
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'text/plain',
+                text: `Unknown resource: ${uri}`,
+            },
+        ],
+    };
+});
+// =============================================================================
+// Prompts
+// =============================================================================
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: 'code_review',
+                description: 'Generate a code review prompt',
+                arguments: [
+                    {
+                        name: 'code',
+                        description: 'The code to review',
+                        required: true,
+                    },
+                ],
+            },
+            {
+                name: 'task_prioritize',
+                description: 'Generate a task prioritization prompt',
+                arguments: [
+                    {
+                        name: 'tasks',
+                        description: 'The tasks to prioritize',
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case 'code_review': {
+            const code = args?.code ?? '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Please use the cognitive_run tool to review the following code:\n\n\`\`\`\n${code}\n\`\`\`\n\nCall: cognitive_run("code-reviewer", "${code.slice(0, 100)}...")`,
+                        },
+                    },
+                ],
+            };
+        }
+        case 'task_prioritize': {
+            const tasks = args?.tasks ?? '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Please use the cognitive_run tool to prioritize the following tasks:\n\n${tasks}\n\nCall: cognitive_run("task-prioritizer", "${tasks}")`,
+                        },
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown prompt: ${name}`);
+    }
+});
+// =============================================================================
+// Server Start
+// =============================================================================
+export async function serve() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Cognitive Modules MCP Server started');
+}
+// Allow running directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    serve().catch(console.error);
+}

package/dist/modules/index.d.ts

@@ -3,3 +3,4 @@
  */
 export * from './loader.js';
 export * from './runner.js';
+export * from './subagent.js';

package/dist/modules/index.js

@@ -3,3 +3,4 @@
  */
 export * from './loader.js';
 export * from './runner.js';
+export * from './subagent.js';

package/dist/modules/loader.js

@@ -103,11 +103,16 @@ async function loadModuleV2(modulePath) {
         runtime_auto_wrap: compatRaw.runtime_auto_wrap ?? true,
         schema_output_alias: compatRaw.schema_output_alias ?? 'data'
     };
-    // Parse meta config (including risk_rule)
+    // Parse meta config (including risk_rule) with validation
     const metaRaw = manifest.meta || {};
+    const rawRiskRule = metaRaw.risk_rule;
+    const validRiskRules = ['max_changes_risk', 'max_issues_risk', 'explicit'];
+    const validatedRiskRule = rawRiskRule && validRiskRules.includes(rawRiskRule)
+        ? rawRiskRule
+        : undefined;
     const metaConfig = {
         required: metaRaw.required,
-        risk_rule: metaRaw.risk_rule,
+        risk_rule: validatedRiskRule,
     };
     return {
         name: manifest.name || path.basename(modulePath),

package/dist/modules/runner.js

@@ -34,9 +34,14 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
     if (!meta.risk) {
         meta.risk = aggregateRisk(data, riskRule);
     }
-    // Trim whitespace only (lossless), do NOT invent new values
+    // Trim whitespace only (lossless), validate is valid RiskLevel
     if (typeof meta.risk === 'string') {
-        meta.risk = meta.risk.trim().toLowerCase();
+        const trimmedRisk = meta.risk.trim().toLowerCase();
+        const validRisks = ['none', 'low', 'medium', 'high'];
+        meta.risk = validRisks.includes(trimmedRisk) ? trimmedRisk : 'medium';
+    }
+    else {
+        meta.risk = 'medium'; // Default for invalid type
     }
     // Repair explain
     if (typeof meta.explain !== 'string') {

package/dist/modules/subagent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Subagent - Orchestrate module calls with isolated execution contexts.
+ *
+ * Supports:
+ * - @call:module-name - Call another module
+ * - @call:module-name(args) - Call with arguments
+ * - context: fork - Isolated execution (no shared state)
+ * - context: main - Shared execution (default)
+ */
+import type { ModuleResult, ModuleInput, Provider } from '../types.js';
+export interface SubagentContext {
+    parentId: string | null;
+    depth: number;
+    maxDepth: number;
+    results: Record<string, unknown>;
+    isolated: boolean;
+}
+export interface CallDirective {
+    module: string;
+    args: string;
+    match: string;
+}
+export interface SubagentRunOptions {
+    input?: ModuleInput;
+    validateInput?: boolean;
+    validateOutput?: boolean;
+    maxDepth?: number;
+}
+/**
+ * Create a new root context
+ */
+export declare function createContext(maxDepth?: number): SubagentContext;
+/**
+ * Fork context (isolated - no inherited results)
+ */
+export declare function forkContext(ctx: SubagentContext, moduleName: string): SubagentContext;
+/**
+ * Extend context (shared - inherits results)
+ */
+export declare function extendContext(ctx: SubagentContext, moduleName: string): SubagentContext;
+/**
+ * Parse @call directives from text
+ */
+export declare function parseCalls(text: string): CallDirective[];
+/**
+ * Replace @call directives with their results
+ */
+export declare function substituteCallResults(text: string, callResults: Record<string, unknown>): string;
+export declare class SubagentOrchestrator {
+    private provider;
+    private running;
+    private cwd;
+    constructor(provider: Provider, cwd?: string);
+    /**
+     * Run a module with subagent support.
+     * Recursively resolves @call directives before final execution.
+     */
+    run(moduleName: string, options?: SubagentRunOptions, context?: SubagentContext): Promise<ModuleResult>;
+}
+/**
+ * Convenience function to run a module with subagent support
+ */
+export declare function runWithSubagents(moduleName: string, provider: Provider, options?: SubagentRunOptions & {
+    cwd?: string;
+}): Promise<ModuleResult>;