MCP Code Execution Openapi

使用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

为什么这很有效

这种方法展示了 代码执行优先模式:

1. 获取数据 -Curl通过MCPO从GitHub检索多达100个存储库
2. 本地处理 -Bash提取仓库名称，随机化顺序，限制为5个
3. 返回最小结果 -仅返回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脚本的地方。脚本已创建 按需 必要时。

快速工作流程：

1. 查找工具: ./scripts/list_tools.sh --search "keyword"
2. 检查参数: ./scripts/list_tools.sh --detail
3. 复制模板: cp scripts/TEMPLATE.sh workspace/my_script.sh
4. 修改 脚本（设置SERVER_NAME、TOOL_NAME，构建REQUEST_BODY）
5. 跑: 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 以获取完整的文档。