cognitive-modules-cli 1.1.0 → 1.3.0

package/README.md

@@ -1,162 +1,94 @@
-# Cognitive Runtime
+# Cognitive Modules CLI (Node.js)
 
-**Structured AI Task Execution**
+[![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Cognitive Runtime is the next-generation execution engine for Cognitive Modules. It provides a clean, provider-agnostic runtime that treats LLMs as interchangeable backends.
+Node.js/TypeScript 版本的 Cognitive Modules CLI。
 
-## Philosophy
+> 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
-Following the **Cognitive Runtime + Provider** architecture:
-
-```
-┌─────────────────────────────────────┐
-│         Cognitive Runtime           │
-│  ┌────────────────────────────────┐ │
-│  │     Module System              │ │
-│  │  (load, parse, validate)       │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Execution Engine           │ │
-│  │  (prompt, schema, contract)    │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Provider Abstraction       │ │
-│  │  (gemini, openai, anthropic,   │ │
-│  │   deepseek, minimax, qwen...)  │ │
-│  └────────────────────────────────┘ │
-└─────────────────────────────────────┘
-```
-
-## Installation
+## 安装
 
 ```bash
-npm install -g cognitive-runtime
-```
-
-Or run directly:
+# 全局安装（推荐）
+npm install -g cogn
 
-```bash
-npx cognitive-runtime --help
+# 或使用 npx 零安装
+npx cogn --help
 ```
 
-## Usage
-
-### Run a Module
+## 快速开始
 
 ```bash
-cog run code-reviewer --args "def foo(): pass"
-```
+# 配置 LLM
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
 
-### List Modules
+# 运行模块
+cog run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')"
 
-```bash
+# 列出模块
 cog list
-```
-
-### Pipe Mode (stdin/stdout)
 
-```bash
+# 管道模式
 echo "review this code" | cog pipe --module code-reviewer
 ```
 
-### Check Configuration
-
-```bash
-cog doctor
-```
-
-## Module Formats
-
-### v2 (Recommended)
-
-```
-my-module/
-├── module.yaml      # Machine-readable manifest
-├── prompt.md        # Human-readable prompt
-├── schema.json      # IO contract
-└── tests/
-    ├── case1.input.json
-    └── case1.expected.json
-```
-
-**module.yaml**:
-```yaml
-name: my-module
-version: 2.0.0
-responsibility: What this module does
-constraints:
-  no_network: true
-  no_side_effects: true
-output:
-  mode: json_strict
-  require_confidence: true
-  require_rationale: true
-  require_behavior_equivalence: true
-tools:
-  allowed: []
-```
-
-### v1 (Legacy, still supported)
+## 与 Python 版的功能对比
 
-```
-my-module/
-├── MODULE.md        # Frontmatter + prompt combined
-└── schema.json
-```
-
-## Providers
-
-| Provider   | Environment Variable   | Default Model        |
-|------------|------------------------|----------------------|
-| Gemini     | `GEMINI_API_KEY`       | `gemini-3-flash`     |
-| OpenAI     | `OPENAI_API_KEY`       | `gpt-5.2`            |
-| Anthropic  | `ANTHROPIC_API_KEY`    | `claude-sonnet-4.5`  |
-| DeepSeek   | `DEEPSEEK_API_KEY`     | `deepseek-v3.2`      |
-| MiniMax    | `MINIMAX_API_KEY`      | `MiniMax-M2.1`       |
-| Moonshot   | `MOONSHOT_API_KEY`     | `kimi-k2.5`          |
-| Qwen       | `DASHSCOPE_API_KEY`    | `qwen3-max`          |
-| Ollama     | `OLLAMA_HOST`          | `llama4` (local)     |
+| 功能 | Python (`cogn`) | Node.js (`cog`) |
+|------|----------------|-----------------|
+| 包名 | `cognitive-modules` | `cogn` / `cognitive-modules-cli` |
+| 安装 | `pip install` | `npm install -g` |
+| 子代理 | ✅ `@call:module` | ✅ `@call:module` |
+| MCP Server | ✅ | ✅ |
+| HTTP Server | ✅ | ✅ |
+| v2.2 Envelope | ✅ | ✅ |
 
-### Provider Aliases
+两个版本功能完全一致，共享相同的模块格式和 v2.2 规范。
 
-- `kimi` → Moonshot
-- `tongyi` / `dashscope` → Qwen
-- `local` → Ollama
+**推荐使用 Node.js 版**：零安装快速体验 `npx cogn run ...`
 
-## Module Search Paths
+## 支持的 Provider
 
-Modules are searched in order:
+| Provider | 环境变量 | 别名 |
+|----------|----------|------|
+| OpenAI | `OPENAI_API_KEY` | - |
+| Anthropic | `ANTHROPIC_API_KEY` | - |
+| Gemini | `GEMINI_API_KEY` | - |
+| DeepSeek | `DEEPSEEK_API_KEY` | - |
+| MiniMax | `MINIMAX_API_KEY` | - |
+| Moonshot | `MOONSHOT_API_KEY` | `kimi` |
+| Qwen | `DASHSCOPE_API_KEY` | `tongyi` |
+| Ollama | `OLLAMA_HOST` | `local` |
 
-1. `./cognitive/modules/` (project-local)
-2. `./.cognitive/modules/` (project-local, hidden)
-3. `~/.cognitive/modules/` (user-global)
+## 命令
 
-## Programmatic API
-
-```typescript
-import { getProvider, findModule, runModule } from 'cognitive-runtime';
-
-const provider = getProvider('gemini');
-const module = await findModule('code-reviewer', ['./cognitive/modules']);
-
-if (module) {
-  const result = await runModule(module, provider, {
-    args: 'def foo(): pass',
-  });
-  console.log(result.output);
-}
+```bash
+# 模块操作
+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 serve --port 8000         # 启动 HTTP API 服务
+cog mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 ```
 
-## Development
+## 开发
 
 ```bash
-# Install dependencies
+# 安装依赖
 npm install
 
-# Build
+# 构建
 npm run build
 
-# Run in development
+# 开发模式运行
 npm run dev -- run code-reviewer --args "..."
 ```
 

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';