使用MCP执行代码-Bash第一工作流
此存储库演示了 代码执行优先工作流 用于使用MCP（模型上下文协议）服务器的AI代理。代理不通过直接的协议调用公开MCP工具，而是使用curl和jq通过简单的bash脚本与MCP服务器进行交互，从而降低复杂性并实现透明的API交互。
关键创新： 使用MCPO（MCP到OpenAPI代理）将MCP服务器作为HTTP REST API公开，然后编写调用这些API的bash脚本。这使得AI代理能够通过HTTP获取数据，在bash中本地处理数据，并返回最小的结果——大大减少了令牌的使用并提高了性能。
先决条件
标准工具（适用于大多数系统）：
- bash -Shell脚本
- 卷曲 -HTTP客户端
- jq -JSON处理器
附加要求：
- uvx （从 uv包管理器)-用于运行MCPO
如果需要，安装紫外线：
curl -LsSf https://astral.sh/uv/install.sh | sh设置
1.配置MCP服务器
复制示例配置：
cp mcp_config.example.json mcp_config.json编辑 mcp_config.json 配置您的MCP服务器（git、GitHub、fetch等）。
2.启动MCPO服务器
在专用终端中，启动MCP到OpenAPI代理服务器：
./scripts/run_mcpo.sh这将所有配置的MCP服务器作为HTTP端点暴露在 http://localhost:8000.
访问API：
- Swagger用户界面:
- OpenAPI规范:
工作时让这个终端保持运行。
3.下载OpenAPI规范
在第二个终端中，下载OpenAPI规范：
./scripts/download_openapi.sh这将JSON规范下载到 servers/ 对于所有配置的MCP服务器（例如。， servers/git-openapi.json, servers/github-openapi.json).
现在，您已经准备好创建工作区脚本了！
示例演练：获取随机GitHub仓库
让我们通过创建一个从GitHub组织中获取5个随机存储库的脚本来演示完整的工作流程。
第一步：发现可用工具
使用令牌高效注册表界面查找相关工具：
./scripts/list_tools.sh --search "repo"这表明 github/search_repositories 可用。
步骤2：检查刀具参数
获取有关该工具的详细信息：
./scripts/list_tools.sh --detail github search_repositories输出显示：
- 必需:
query - 可选的:
perPage,minimal_output,sort,order,page - 端点:
POST http://localhost:8000/github/search_repositories
步骤3：创建脚本
复制模板并创建新的工作区脚本：
cp scripts/TEMPLATE.sh workspace/github_random_repos.sh编辑 workspace/github_random_repos.sh:
#!/usr/bin/env bash
set -euo pipefail
# Configuration
MCPO_BASE_URL="${MCPO_BASE_URL:-http://localhost:8000}"
SERVER_NAME="github"
TOOL_NAME="search_repositories"
ENDPOINT_URL="${MCPO_BASE_URL}/${SERVER_NAME}/${TOOL_NAME}"
# Parse arguments
ORG_NAME="${1:-}"
COUNT="${2:-5}"
# Validate arguments
if [[ -z "$ORG_NAME" ]]; then
echo "Usage: $0 [count]"
echo "Example: $0 ipdelete 5"
exit 1
fi
# Build request body - search for repos in the org
REQUEST_BODY=$(jq -n \
--arg query "org:${ORG_NAME}" \
--argjson perPage 100 \
'{
query: $query,
perPage: $perPage,
minimal_output: false
}'
)
# Make API call
RESPONSE=$(curl -sf -X POST "$ENDPOINT_URL" \
-H "Content-Type: application/json" \
-d "$REQUEST_BODY" 2>/dev/null)
if [[ $? -ne 0 ]]; then
echo "Error: Failed to call API at $ENDPOINT_URL"
echo "Make sure MCPO is running: ./scripts/run_mcpo.sh"
exit 1
fi
# Process response: extract repo names and randomly select COUNT repos
# Code-execution-first: process data locally, return minimal results
echo "$RESPONSE" | jq -r '.items[]? | .full_name' | sort -R | head -n "$COUNT"步骤4：运行脚本
使其可执行并运行：
chmod +x workspace/github_random_repos.sh
./workspace/github_random_repos.sh ipdelete 5输出：
ipdelete/az-nextcloud
ipdelete/psychic_rag_doe
ipdelete/prompt_injection
ipdelete/demigod
ipdelete/csharp-df-counter为什么这很有效
这种方法展示了 代码执行优先模式:
- 获取数据 -Curl通过MCPO从GitHub检索多达100个存储库
- 本地处理 -Bash提取仓库名称，随机化顺序，限制为5个
- 返回最小结果 -仅返回5个回购名称（不是100个完整的回购对象）
代币节省： 我们返回约200字节的文本，而不是向AI模型返回约50KB的JSON数据。代币减少了约250倍！
目录结构
.
├── scripts/ # System scripts (infrastructure)
│ ├── run_mcpo.sh # Start MCPO server
│ ├── download_openapi.sh # Download OpenAPI specs
│ ├── generate_registry.sh # Generate token-efficient registry
│ ├── list_tools.sh # Interactive tool browser
│ └── TEMPLATE.sh # Template for workspace scripts
├── workspace/ # Your bash scripts using curl (PUT YOUR SCRIPTS HERE)
│ ├── git_status.sh # Example: Git status
│ ├── git_diff.sh # Example: Git diff
│ └── github_random_repos.sh # Example: Fetch random repos
├── servers/ # Downloaded OpenAPI specs (DO NOT EDIT)
│ ├── git-openapi.json
│ ├── github-openapi.json
│ └── fetch-openapi.json
├── registry/ # Token-efficient tool registry (auto-generated)
│ └── registry.json # Compact index of all MCP tools
├── mcp_config.json # MCP server configurations
└── docs/ # Design documentation
├── code-execution-with-mcp.md
└── using-registry.md发现可用工具
始终使用 ./scripts/list_tools.sh 作为工具发现的主要接口：
# List all servers and tool counts
./scripts/list_tools.sh
# List tools for a specific server
./scripts/list_tools.sh --server github
# Search tools by keyword
./scripts/list_tools.sh --search "branch"
# Get detailed tool information with parameters
./scripts/list_tools.sh --detail github search_repositories
# Show registry statistics
./scripts/list_tools.sh --stats与直接读取OpenAPI规范相比，此接口可节省约27%的令牌。
创建工作区脚本
这 workspace/ 目录是您编写调用MCP工具的bash脚本的地方。脚本已创建 按需 必要时。
快速工作流程：
- 查找工具:
./scripts/list_tools.sh --search "keyword" - 检查参数:
./scripts/list_tools.sh --detail - 复制模板:
cp scripts/TEMPLATE.sh workspace/my_script.sh - 修改 脚本（设置SERVER_NAME、TOOL_NAME，构建REQUEST_BODY）
- 跑:
chmod +x workspace/my_script.sh && ./workspace/my_script.sh
基于约定的配置
所有脚本都遵循以下约定：
- OpenAPI规范:
servers/{server-name}-openapi.json - MCPO基本URL:
http://localhost:8000（用覆盖MCPO_BASE_URL任何人） - 端点模式:
POST {base_url}/{server_name}/{tool_name} - 请求格式：JSON主体构造如下
jq - 响应格式：JSON解析如下
jq
为什么选择Bash而不是Python客户端？
bash+curl方法具有显著的优势：
- 更快：无需生成代码——只需下载JSON规范
- 更简单：除了标准工具（curl、jq）之外没有依赖关系
- 透明：直接HTTP调用易于理解和调试
- 灵活的：根据需要按需创建脚本
- 便携的：适用于curl和jq可用的任何地方
- 代币高效：在返回AI模型之前，在本地处理数据
关键资源
- 工具发现:
./scripts/list_tools.sh（始终使用此界面） - 脚本模板:
scripts/TEMPLATE.sh（复制此内容以创建新脚本） - 注册表文件:
docs/using-registry.md - 图案说明:
docs/code-execution-with-mcp.md - 存储库指南:
CLAUDE.md
高级：使用注册表
注册表系统为所有MCP工具提供了一个令牌高效索引：
- 自动生成 通过OpenAPI规范
./scripts/generate_registry.sh - 减小约27% 比单个OpenAPI规范
- 从不直接阅读--始终使用
./scripts/list_tools.sh接口 - 下载OpenAPI规范时自动重新生成
看 docs/using-registry.md 以获取完整的文档。