mcp-cli-scripts

# MCP CLI Scripts Pattern

**Status**: Production Ready
**Last Updated**: 2026-01-09
**Dependencies**: tsx (dev dependency)
**Current Versions**: [email protected]

---

## Why CLI Scripts Alongside MCP Servers?

When building MCP servers, also create companion CLI scripts that provide the same (and often extended) functionality for use with Claude Code in terminal environments.

| Aspect | Remote MCP (Claude.ai) | CLI Scripts (Claude Code) |
|--------|------------------------|---------------------------|
| Context | Results flow through model context window | Results stay local, only relevant parts shared |
| File System | No access | Full read/write access |
| Batch Operations | One call at a time | Can process files of inputs |
| Caching | Stateless | Can cache results locally |
| Output | JSON to model | JSON, CSV, table, file, or stdout |
| Chaining | Model orchestrates | Scripts can pipe/chain directly |

---

## Directory Structure

mcp-{name}/
├── src/
│   └── index.ts              # MCP server (for Claude.ai, remote clients)
├── scripts/
│   ├── {tool-name}.ts        # One script per tool
│   ├── {another-tool}.ts
│   └── _shared.ts            # Shared auth/config helpers (optional)
├── SCRIPTS.md                # Documents available scripts for Claude Code
├── package.json
└── README.md

---

## The 5 Design Principles

### 1. One Script Per Tool

Each script does one thing well, matching an MCP tool but with extended capabilities.

### 2. JSON Output by Default

Scripts output JSON to stdout for easy parsing. Claude Code can read and use the results.

// Good - structured output
console.log(JSON.stringify({ success: true, data: result }, null, 2));

// Avoid - unstructured text (unless --format text requested)
console.log("Found 5 results:");

### 3. Extended Capabilities for Local Use

CLI scripts can offer features that don't make sense for remote MCP:

// Input/Output files
--input data.csv          // Batch process from file
--output results.json     // Save results to file
--append                  // Append to existing file

// Caching
--cache                   // Use local cache
--cache-ttl 3600          // Cache for 1 hour
--no-cache                // Force fresh request

// Output formats
--format json|csv|table   // Different output formats
--quiet                   // Suppress non-essential output
--verbose                 // Extra debugging info

// Batch operations
--batch                   // Process multiple items
--concurrency 5           // Parallel processing limit

### 4. Consistent Argument Patterns

Use consistent patterns across all scripts:

# Standard patterns
--input <file>            # Read input from file
--output <file>           # Write output to file
--format <type>           # Output format
--profile <name>          # Auth profile (for multi-account)
--verbose                 # Debug output
--help                    # Show usage

### 5. Shebang and Direct Execution

Scripts should be directly executable:

#!/usr/bin/env npx tsx
/**
 * Brief description of what this script does
 *
 * Usage:
 *   npx tsx scripts/tool-name.ts <required-arg>
 *   npx tsx scripts/tool-name.ts --option value
 *
 * Examples:
 *   npx tsx scripts/tool-name.ts 12345
 *   npx tsx scripts/tool-name.ts --input batch.csv --output results.json
 */

---

## Critical Rules

### Always Do

✅ Use #!/usr/bin/env npx tsx shebang (not node or ts-node)
✅ Output JSON to stdout by default
✅ Use consistent argument patterns across all scripts
✅ Document scripts in SCRIPTS.md
✅ Handle errors with structured JSON: { success: false, error: "..." }

### Never Do

❌ Use console.log() for prose output (use structured JSON)
❌ Use different argument patterns per script
❌ Forget to document the script in SCRIPTS.md
❌ Use node or ts-node in shebang (tsx handles ESM+TypeScript)

---

## When to Use Scripts vs MCP

**Use CLI scripts when:**
- Working in terminal/Claude Code environment
- Need to save results to files
- Processing batch inputs from files
- Chaining multiple operations
- Need caching for repeated lookups
- Want richer output formats

**Use MCP tools when:**
- In Claude.ai web interface
- Simple one-off lookups
- No file I/O needed
- Building conversational flows

---

## Shared Code Between MCP and Scripts

If you want to share logic between MCP and scripts, extract to a core module:

src/
├── core/
│   ├── lookup.ts         # Pure function, no I/O assumptions
│   └── index.ts          # Export all core functions
├── mcp/
│   └── index.ts          # MCP handlers, import from core
└── cli/
    └── lookup.ts         # CLI wrapper, import from core

However, keeping them separate is also fine - the scripts may evolve to have capabilities the MCP can't support, and that's okay.

---

## Using Bundled Resources

### Templates (templates/)

**script-template.ts**: Complete TypeScript script template with argument parsing, JSON output, and file I/O patterns.

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/script-template.ts scripts/new-tool.ts

**SCRIPTS-TEMPLATE.md**: Template for documenting available scripts in an MCP server repo.

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/SCRIPTS-TEMPLATE.md SCRIPTS.md

### Rules (rules/)

**mcp-cli-scripts.md**: Correction rules for script files. Copy to .claude/rules/ in projects:

cp ~/.claude/skills/mcp-cli-scripts/rules/mcp-cli-scripts.md .claude/rules/

---

## Dependencies

**Required**:
- [email protected] - TypeScript execution without compilation

Add to package.json:

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

## Official Documentation

- **tsx**: https://github.com/privatenumber/tsx
- **Node.js CLI**: https://nodejs.org/api/cli.html

---

## Package Versions (Verified 2026-01-09)

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

## Complete Setup Checklist

- [ ] Create scripts/ directory in MCP server project
- [ ] Add tsx to devDependencies
- [ ] Create first script from template
- [ ] Create SCRIPTS.md from template
- [ ] Test script: npx tsx scripts/tool-name.ts --help
- [ ] Verify JSON output format
- [ ] Document all scripts in SCRIPTS.md


---

# MCP CLI Scripts Corrections

Apply when editing TypeScript files in scripts/ directories.

## Shebang

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| #!/usr/bin/env node | #!/usr/bin/env npx tsx |
| #!/usr/bin/env ts-node | #!/usr/bin/env npx tsx |
| No shebang | Add #!/usr/bin/env npx tsx at top |

**Why**: tsx handles ESM + TypeScript without compilation. Node requires transpilation. ts-node has compatibility issues.

## Output Format

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| console.log("Found 5 results") | console.log(JSON.stringify({ success: true, count: 5 })) |
| console.log(data) | console.log(JSON.stringify(data, null, 2)) |
| Unstructured text output | Structured JSON output |

**Why**: JSON output is machine-readable. Claude Code can parse and use structured data.

## Error Handling

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| console.error("Error: " + err.message) | console.error(JSON.stringify({ success: false, error: err.message })) |
| throw new Error(...) without catching | Catch and output JSON error |
| process.exit(1) without error output | Output JSON error, then exit |

**Why**: Consistent error format allows Claude Code to detect and handle failures.

## Argument Patterns

Use these standard argument names consistently:

| Pattern | Description |
|---------|-------------|
| --input <file> | Read input from file |
| --output <file> | Write output to file |
| --format <type> | Output format (json/csv/table) |
| --verbose | Debug output |
| --help or -h | Show usage |

**Why**: Consistent patterns reduce cognitive load. Claude can predict script interfaces.

## Verbose Output

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| console.log("Processing...") | if (args.verbose) console.error("Processing...") |
| Status messages to stdout | Status messages to stderr (preserves stdout for data) |

**Why**: Verbose output should go to stderr so stdout contains only the result data.