Postman Agent Generator

Workshop slides:

https://drive.google.com/drive/folders/1CQaKkrcuD8Vxam559EEdCByX0z2s-Oxc?usp=sharing

Postman Agent Generator

欢迎使用生成的 Agent！🚀

此项目由 Postman Agent Generator 创建，配置为 Model Context Provider (MCP) 服务输出模式。它为你提供：

• ✅ 一个兼容 MCP 的服务（mcpServer.js）
• ✅ 为每个选定的 Postman API 请求自动生成的 JavaScript 工具

让我们开始设置！

🚦 入门

⚙️ 前提条件

开始之前，请确保已安装：

• Node.js（需要 v16+，推荐 v20+）
• npm（随 Node 一同安装）

📥 安装与设置

1. 安装依赖项

在项目根目录中运行：

npm install

🔐 设置工具环境变量（octocat 和 harry potter api 无需此步骤）

在 .env 文件中，你会看到环境变量占位符，每个占位符对应所选工具所属的一个工作区。例如，如果你选择了来自 2 个工作区（例如 Acme 和 Widgets）的请求，你会看到两个占位符：

ACME_API_KEY=
WIDGETS_API_KEY=

将值更新为各 API 的实际 API 密钥。这些环境变量会在生成的工具中使用，为每个请求设置 API 密钥。你可以查看 tools 目录中的文件，了解其工作方式。

// environment variables are used inside of each tool file
const apiKey = process.env.ACME_API_KEY;

注意： 这可能不适用于所有 API。生成逻辑比较简单——对于每个工作区，我们都会创建一个与工作区 slug 同名的环境变量，然后在属于该工作区的每个工具文件中使用该环境变量。如果这不适合你所选 API 的情况，也没关系！你可以手动更新 .env 文件或工具文件中的任何内容，以准确反映 API 的身份验证方式。

🛠️ 列出可用工具

使用以下命令列出所有生成工具的说明和参数：

node index.js tools

示例：

Available Tools:

Workspace: 6-harry-potter-api-with-magic-visualizations
  Collection: hogwarts-staff.js
    get_hogwarts_staff
      Description: Retrieve all Hogwarts staff characters.
      Parameters:

  Collection: spells.js
    fetch_spells
      Description: Fetch spells from the Harry Potter API.
      Parameters:

  Collection: hogwarts-students.js
    get_hogwarts_students
      Description: Fetch all Hogwarts students from the Harry Potter API.
      Parameters:

  Collection: characters-in-house.js
    get_characters_in_house
      Description: Retrieve characters from a specific Hogwarts house.
      Parameters:
        - house: The name of the Hogwarts house to retrieve characters from.

  Collection: all-characters.js
    get_all_characters
      Description: Retrieve all characters from the Harry Potter API.
      Parameters:


Workspace: 7-git-hub-octodex-postbot
  Collection: build-your-own-octodex-api.js
    fetch_octocats
      Description: Fetch Octocats from the Octodex API.
      Parameters:

🌐 运行 MCP 服务

MCP 服务（mcpServer.js）会向兼容 MCP 的客户端（例如 Claude Desktop 或 Postman Desktop Application）公开自动化 API 工具。

1. 查找 node 路径：

which node

2. 查找 mcpServer.js 路径：

realpath mcpServer.js

A) 🖥️ 使用 Postman 运行

Postman Desktop Application 是运行和测试 MCP 服务的最简单方式。

步骤 1：从 https://www.postman.com/downloads/ 下载最新的 Postman Desktop Application，或安装最新的 Postman Desktop Agent，以便在浏览器中使用 Postman。

步骤 2：Fork 或修改 此处的 Octodex-HP-MCP Server Postman Collection，并调整 Octodex & HP Local Node 服务设置，使其指向本地 MCP 服务：

B) 👩‍💻 使用 Claude Desktop 运行

要与 Claude Desktop 集成：

打开 Claude Desktop → Settings → Developers → Edit Config，然后添加你的服务：

{
  "mcpServers": {
    "octocat-hp-mcp-server-local": {
      "command": "<absolute_path_to_node>",
      "args": ["<absolute_path_to_mcpServer.js>"]
    }
  }
}

例如：

{
  "mcpServers": {
    "octocat-hp-mcp-server-local": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/yourusername/octocat-harry-potter-mcp-server/mcpServer.js"]
    }
  }
}

重启 Claude Desktop 以启用此更改。

C) 🏃‍♂️ 在 VSCode 中运行 MCP 服务

要在 VSCode 中运行本地 MCP 服务，你可以调整并启动 .vscode 文件夹中的 octocat-hp-mcp-server-local 服务。

然后，如果你在 Co-Pilot Chat 中选择 Agent 模式，工具图标应会显示 octocat-hp-mcp-server-local 服务公开的 API 端点（工具）。

其他选项

🐳 Docker 部署（生产环境）

对于生产环境部署，你可以使用 Docker：

1. 构建 Docker 镜像

docker build -t octocat-hp-mcp-server .

在 .env 文件中添加环境变量（API 密钥等）。

在本地测试：

docker run -i --rm --env-file .env octocat-hp-mcp-server

2. Claude Desktop 集成

将 Docker 服务配置添加到 Claude Desktop（Settings → Developers → Edit Config）：

{
  "mcpServers": {
    "octocat-hp-mcp-server-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "octocat-hp-mcp-server"]
    }
  }
}

3. VS Code 集成

要在 VSCode 中运行 Docker MCP 服务，你可以调整并启动 .vscode 文件夹中的 octocat-hp-mcp-server-docker 服务。

然后，如果你在 Co-Pilot Chat 中选择 Agent 模式，工具图标应显示 octocat-hp-mcp-server-docker 服务公开的 API 端点（工具）。

🌐 服务器发送事件（SSE）

要运行支持服务器发送事件（SSE）的服务，请使用 --sse 标志：

node mcpServer.js --sse

要在 Docker 中运行 SSE 并在端口 9000 上公开服务：

docker run  -i --rm  -p 9000:9000 --env-file .env octocat-hp-mcp-server node mcpServer.js --sse

这将在后台启动服务，将主机上的端口 9000 映射到容器中的端口 9000，并启用 SSE 支持。

🐳 Dockerfile（已包含）

项目附带以下最简 Docker 配置：

FROM node:22.12-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

COPY . .

ENTRYPOINT ["node", "mcpServer.js"]

➕ 添加新工具

轻松为 Agent 添加更多工具：

1. 访问 Postman Agent Generator。
2. 选择新的 API 请求，生成一个新 Agent 并下载。
3. 将新生成的工具复制到现有项目的 tools/ 文件夹中。
4. 更新 tools/paths.js 文件，以包含新工具的引用。

示例提示词和可视化

prompts.md 中包含一些示例提示词，可用于测试 MCP 服务的功能，并生成类似这样的可视化结果

💬 问题与支持

访问 Postman Agent Generator 页面，了解更新和新功能。

访问 Postman Community，分享你的作品、提出问题并获取帮助。