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

// 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:");

// 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

# 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

#!/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
 */

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

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

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

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

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

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