mcp-cli-scripts

MCP CLI 脚本模式

状态：可用于生产环境 上次更新：2026-01-09 依赖项：tsx（开发依赖） 当前版本：[email protected]

---

为什么要在 MCP 服务旁边创建 CLI 脚本？

构建 MCP 服务时，也要创建配套的 CLI 脚本，提供相同（且通常更丰富）的功能，以便在终端环境中配合 Claude Code 使用。

方面	远程 MCP（Claude.ai）	CLI 脚本（Claude Code）
上下文	结果会经过模型上下文窗口	结果保留在本地，仅分享相关部分
文件系统	无法访问	可完整读写
批量操作	一次一个调用	可处理多个输入文件
缓存	无状态	可在本地缓存结果
输出	JSON 到模型	JSON、CSV、表格、文件或标准输出
链接操作	由模型编排	脚本可直接通过管道或链式调用

---

目录结构

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

---

5 项设计原则

1. 每个工具对应一个脚本

每个脚本专注做好一件事，对应一个 MCP 工具，但具备扩展能力。

2. 默认输出 JSON

脚本将 JSON 输出到标准输出，便于解析。Claude Code 可以读取并使用结果。

// 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. 扩展本地使用能力

CLI 脚本可以提供一些不适用于远程 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. 统一参数模式

在所有脚本中使用统一的参数模式：

# 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 与直接执行

脚本应可直接执行：

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

---

关键规则

务必做到

✅ 使用 #!/usr/bin/env npx tsx shebang（不要使用 node 或 ts-node） ✅ 默认将 JSON 输出到标准输出 ✅ 在所有脚本中使用统一的参数模式 ✅ 在 SCRIPTS.md 中记录脚本 ✅ 使用结构化 JSON 处理错误：{ success: false, error: "..." }

切勿这样做

❌ 使用 console.log() 输出普通文本（应使用结构化 JSON） ❌ 为每个脚本使用不同的参数模式 ❌ 忘记在 SCRIPTS.md 中记录脚本 ❌ 在 shebang 中使用 node 或 ts-node（tsx 可处理 ESM 和 TypeScript）

---

何时使用脚本，何时使用 MCP

使用 CLI 脚本的场景：

• 在终端或 Claude Code 环境中工作
• 需要将结果保存到文件
• 处理来自文件的批量输入
• 链式执行多个操作
• 需要缓存重复查询的结果
• 需要更丰富的输出格式

使用 MCP 工具的场景：

• 在 Claude.ai 网页界面中使用
• 简单的一次性查询
• 不需要文件 I/O
• 构建对话流程

---

MCP 与脚本之间共享代码

如果要在 MCP 与脚本之间共享逻辑，可以将其提取到核心模块中：

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

不过，将它们分开也没问题——脚本可以逐步增加 MCP 不支持的功能，这完全可以接受。

---

使用打包资源

模板（templates/）

script-template.ts：完整的 TypeScript 脚本模板，包含参数解析、JSON 输出和文件 I/O 模式。

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

SCRIPTS-TEMPLATE.md：用于记录 MCP 服务仓库中可用脚本的模板。

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

规则（rules/）

mcp-cli-scripts.md：脚本文件的修正规则。将其复制到项目的 .claude/rules/ 中：

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

---

依赖项

必需项：

• [email protected] - 无需编译即可执行 TypeScript

添加到 package.json：

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

---

官方文档

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

---

软件包版本（已于 2026-01-09 验证）

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

---

完整设置清单

• 在 MCP 服务项目中创建 scripts/ 目录
• 将 tsx 添加到 devDependencies
• 使用模板创建第一个脚本
• 使用模板创建 SCRIPTS.md
• 测试脚本：npx tsx scripts/tool-name.ts --help
• 验证 JSON 输出格式
• 在 SCRIPTS.md 中记录所有脚本