@nicolasmondain/cli-agent 3.0.2 → 3.0.4

package/README.md

@@ -2,20 +2,35 @@
 
 > Turn your scripts into AI-powered tools
 
-cli-agent is an MCP server that lets AI assistants like Claude execute your scripts through natural language.
+`cli-agent` is an MCP server that lets AI assistants execute your scripts (JavaScript, TypeScript, or shell) through natural language.
+
+## Why cli-agent?
+
+`cli-agent` turns your scripts into AI-powered tools without writing MCP boilerplate. Instead of manually registering each script as an MCP tool with its own schema, argument parsing, and error handling, you define them once in a simple JSON config (and both CLI and MCP interfaces are generated automatically). The more scripts you have, the more time you save: one config file replaces dozens of lines of repetitive TypeScript per command.
 
 ## How it works
 
 1. You define your scripts in `.cli-agent.json`
-2. cli-agent exposes them as MCP tools
-3. Claude understands what they do and runs them when needed
+2. `cli-agent` exposes them as MCP tools
+3. Your AI assistant understands what they do and runs them when needed
+
+```mermaid
+graph TD
+    subgraph User
+        A[AI assistant, deploy to staging]
+    end
+
+    subgraph MCP_cli-agent[MCP cli-agent]
+        B[matches intent]
+        C[run the script]
+    end
+
+    D[results]
+
+    A --> B
+    B --> C
+    C --> D
 
-```
-User: "Deploy to staging"
-  ↓
-Claude matches intent → deploy --env staging
-  ↓
-Your script runs → Result returned to Claude
 ```
 
 ## Quick Start
@@ -23,44 +38,48 @@ Your script runs → Result returned to Claude
 ### 1. Install
 
 ```bash
-npm install -g @nicolasmondain/cli-agent
+npm install -d @nicolasmondain/cli-agent
 ```
-
 ### 2. Create `.cli-agent.json`
+`cli-agent` looks for configuration in this order:
+
+1. `--config <path>` flag
+2. `.cli-agent.json` in current directory (prefered)
+3. `cli-agent` field in `package.json`
+4. `~/.cli-agent.json` (global)
 
 ```json
 {
   "name": "cli-agent",
   "commands": [
     {
-      "name": "deploy",
-      "description": "Deploy the app to staging or production",
-      "script": "./scripts/deploy.sh",
+      "name": "command-name",
+      "description": "What this command does (helps AI assistants understand when to use it) by giving clear descriptions of arguments and options. You can also provide examples of usage.",
+      "script": "./path/to/script.js",
+      "arguments": [
+        { "name": "arg", "description": "Positional argument", "required": true }
+      ],
       "options": [
-        { "flags": "-e, --env <env>", "choices": ["staging", "production"] }
+        { "flags": "-o, --option <value>", "description": "Named option", "default": "value" }
       ]
     }
   ]
 }
 ```
 
-### 3. Configure Claude Code
-
-Add to your Claude Code MCP settings: `.claude/mcp.json`
+### 3. Configure your MCP settings
 
 ```json
 {
   "mcpServers": {
     "cli-agent": {
       "command": "npx",
-      "args": ["cli-agent", "mcp:serve"]
+      "args": ["@nicolasmondain/cli-agent", "mcp:serve"]
     }
   }
 }
 ```
 
-For Zed, add to your settings:
-
 ```json
 {
   "context_servers": {
@@ -72,72 +91,6 @@ For Zed, add to your settings:
 }
 ```
 
-Done. Claude can now run your scripts.
-
-## Writing Scripts
-
-Scripts can be JavaScript, TypeScript, or shell scripts.
-
-### JavaScript (.js)
-
-```javascript
-export default async function(context) {
-  const env = context.options.env;
-  // your logic here
-  return { success: true, message: `Deployed to ${env}` };
-}
-```
-
-### TypeScript (.ts)
-
-```typescript
-import type { ScriptContext, CommandResult } from '@nicolasmondain/cli-agent';
-
-export default async function(context: ScriptContext): Promise<CommandResult> {
-  const env = context.options.env as string;
-  return { success: true, message: `Deployed to ${env}` };
-}
-```
-
-### Shell (.sh)
-
-```bash
-#!/bin/bash
-ENV="${CLI_AGENT_OPT_ENV}"
-echo "Deploying to $ENV..."
-echo '{"success": true}'
-```
-
-## Configuration
-
-```json
-{
-  "name": "cli-agent",
-  "commands": [
-    {
-      "name": "command-name",
-      "description": "What this command does (helps Claude understand when to use it)",
-      "script": "./path/to/script.js",
-      "arguments": [
-        { "name": "arg", "description": "Positional argument", "required": true }
-      ],
-      "options": [
-        { "flags": "-o, --option <value>", "description": "Named option", "default": "value" }
-      ]
-    }
-  ]
-}
-```
-
-### Configuration locations
-
-cli-agent looks for configuration in this order:
-
-1. `--config <path>` flag
-2. `.cli-agent.json` in current directory
-3. `cli-agent` field in `package.json`
-4. `~/.cli-agent.json` (global)
-
 ## CLI Usage
 
 ```bash
@@ -154,30 +107,6 @@ cli-agent deploy --env staging
 cli-agent deploy --env staging --format json
 ```
 
-## Script Context
-
-Scripts receive a context object with:
-
-```typescript
-interface ScriptContext {
-  args: Record<string, unknown>;    // Positional arguments
-  options: Record<string, unknown>; // Named options
-  cwd: string;                      // Current working directory
-  format: 'human' | 'json';         // Output format
-}
-```
-
-Scripts must return:
-
-```typescript
-interface CommandResult {
-  success: boolean;
-  message?: string;  // Human-readable message
-  data?: unknown;    // Structured data
-  error?: string;    // Error message if success is false
-}
-```
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicolasmondain/cli-agent",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "MCP server that turns your scripts into AI-powered tools for Claude and other AI assistants",
   "type": "module",
   "main": "./dist/index.js",