promptpilot-mcp-server

v1.0.2

Published

10 months ago

MCP Server for Prompt Improvement using AgentPilot SDK

0High
0Medium
0Low

kookliu

mcp prompt ai claude agentpilot prompt-engineering

PromptPilot MCP Server

一个基于 Model Context Protocol (MCP) 的智能提示词优化服务器，集成了 AgentPilot SDK 的强大功能。

🚀 AgentPilot SDK 简介

AgentPilot SDK 是一个强大的 AI 代理开发工具包，为开发者提供工具、接口和资源，简化应用开发流程，帮助开发者在构建 Agent 时，以低侵入、灵活的方式集成 PromptPilot 的核心功能。

通过 AgentPilot SDK，开发者可以：

多模型支持：集成多种主流 AI 模型，包括 GPT、Claude、通义千问等
智能提示词优化：自动分析和改进提示词质量，提升 AI 响应效果
代码生成辅助：生成高质量的代码提示词，加速开发流程
模板管理：提供丰富的提示词模板库，覆盖各种应用场景
质量分析：深度分析提示词质量，提供专业的改进建议

📦 安装方式

方式一：使用 npx（推荐）

通过 npx 可以直接运行最新版本，无需本地安装：

npx promptpilot-mcp-server

方式二：全局安装

npm install -g promptpilot-mcp-server
promptpilot-mcp-server

方式三：本地开发

git clone <repository-url>
cd promptpilot-mcp-server
pip install -r requirements.txt
python mcp_server.py

🚀 TRAE AI IDE 配置

TRAE AI IDE 是一个支持 Model Context Protocol (MCP) 的智能开发环境 1，支持 stdio、SSE 和 Streamable HTTP 三种传输协议。

系统环境准备

在配置 MCP 服务器之前，请确保已安装以下依赖 1：

Node.js 18+：用于运行 npx 命令
Python 3.8+ 和 uvx：用于运行 Python 工具
Docker（可选）：用于容器化部署

配置方法

方法一：从 MCP 市场添加（推荐）

打开 MCP 设置
- 在侧边聊天框右上角点击设置图标
- 从菜单中选择 "MCP"
添加 MCP 服务器
- 点击 "+ Add MCP Servers" 按钮
- 或点击 "+ Add" 按钮并选择 "Add from Marketplace"
配置 PromptPilot MCP Server
- 在市场中搜索或手动添加 PromptPilot 配置
- 填写 JSON 配置信息：

{
  "name": "promptpilot",
  "command": ["npx", "promptpilot-mcp-server"],
  "env": {
    "AGENTPILOT_API_KEY": "your_agentpilot_api_key",
    "ARK_API_KEY": "your_ark_api_key",
    "AGENTPILOT_API_URL": "https://agentpilot.bytedance.com",
    "DEFAULT_MODEL": "Deepseek-R1-250528",
    "LOG_LEVEL": "INFO"
  }
}

确认配置
- 将环境变量信息替换为真实的 API 密钥
- 点击 "Confirm" 按钮完成配置

方法二：手动添加配置

如果在市场中找不到 PromptPilot 或需要自定义配置：

打开手动配置
- 在 MCP 设置页面点击 "+ Add" 按钮
- 选择 "Add Manually" 选项
配置文件位置
- 项目级配置：.trae/mcp.json
添加配置内容

{
  "mcpServers": [
    {
      "name": "promptpilot",
      "command": ["npx", "promptpilot-mcp-server"],
      "env": {
        "AGENTPILOT_API_KEY": "your_agentpilot_api_key",
        "ARK_API_KEY": "your_ark_api_key",
        "AGENTPILOT_API_URL": "https://agentpilot.bytedance.com",
        "DEFAULT_MODEL": "Deepseek-R1-250528",
        "LOG_LEVEL": "INFO"
      }
    }
  ]
}

方法三：使用 SSE 传输协议

对于远程部署或高级配置需求，可以使用 SSE 传输协议 1：

启动 SSE 服务器

# 设置环境变量并启动 SSE 服务器
AGENTPILOT_API_KEY="your_agentpilot_api_key" \
ARK_API_KEY="your_ark_api_key" \
AGENTPILOT_API_URL="https://agentpilot.bytedance.com" \
DEFAULT_MODEL="Deepseek-R1-250528" \
LOG_LEVEL="INFO" \
npx promptpilot-mcp-server --transport sse --port 8000

配置 SSE 连接

{
  "mcpServers": [
    {
      "name": "promptpilot",
      "url": "http://localhost:8000/sse",
      "type": "sse"
    }
  ]
}

在 TRAE 中使用

配置完成后，PromptPilot 的工具将自动集成到 TRAE 的 AI Agent 中：

自动工具调用
- AI Agent 会根据上下文自动选择合适的工具
- 支持智能提示词优化、代码生成等功能
手动工具调用
- 可以通过 / 命令手动调用特定工具
- 例如：/improve_prompt 或 /generate_code_prompt
示例对话

请帮我优化这个提示词：写一个关于机器学习的文章

生成一个 Python 数据分析的代码提示词

TRAE 特色功能

TRAE AI IDE 还支持以下特色功能 4：

.rules 配置文件：定义 Agent 行为规则，构建长期上下文记忆
多模型支持：集成多种 AI 模型，提供灵活的选择
VS Code 插件兼容：支持现有的 VS Code 扩展生态

故障排除

MCP 服务器连接失败
- 检查 Node.js 和 npx 是否正确安装
- 确认环境变量配置是否正确
- 查看 TRAE 的 MCP 日志输出
权限问题
- 确保有足够的权限执行 npx 命令
- 检查网络连接是否正常

⚙️ Claude Desktop 配置

配置文件位置

Claude Desktop 的配置文件位于：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

配置方法

方法一：使用 npx（推荐）

在 claude_desktop_config.json 中添加以下配置：

{
  "mcpServers": {
    "promptpilot": {
      "command": "npx",
      "args": ["promptpilot-mcp-server"],
      "env": {
        "AGENTPILOT_API_KEY": "your_agentpilot_api_key",
        "ARK_API_KEY": "your_ark_api_key",
        "AGENTPILOT_API_URL": "https://agentpilot.bytedance.com",
        "DEFAULT_MODEL": "Deepseek-R1-250528",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

方法二：使用启动脚本

创建启动脚本 start_mcp_with_env.sh：

#!/bin/bash
export AGENTPILOT_API_KEY="your_agentpilot_api_key"
export ARK_API_KEY="your_ark_api_key"
export AGENTPILOT_API_URL="https://agentpilot.bytedance.com"
export DEFAULT_MODEL="Deepseek-R1-250528"
export LOG_LEVEL="INFO"
exec npx promptpilot-mcp-server

在 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "promptpilot": {
      "command": "/path/to/start_mcp_with_env.sh",
      "args": []
    }
  }
}

方法三：内联环境变量

{
  "mcpServers": {
    "promptpilot": {
      "command": "sh",
      "args": [
        "-c",
        "AGENTPILOT_API_KEY=your_agentpilot_api_key ARK_API_KEY=your_ark_api_key AGENTPILOT_API_URL=https://agentpilot.bytedance.com DEFAULT_MODEL=Deepseek-R1-250528 LOG_LEVEL=INFO npx promptpilot-mcp-server"
      ]
    }
  }
}

🎯 Cursor IDE 配置

Cursor IDE 内置了对 Model Context Protocol (MCP) 的支持 1，可以通过以下方式配置 PromptPilot MCP Server。

配置步骤

方法一：全局 MCP 配置（推荐）

打开 Cursor 设置
- 使用快捷键 Ctrl+Shift+J（Windows/Linux）或 Cmd+Shift+J（macOS）
- 或者通过菜单：Settings → Cursor Settings
启用 MCP 功能
- 在设置中找到 "Features" → "Model Context Protocol"
- 启用 MCP 服务器支持
添加 MCP 服务器
- 点击 "Add new global MCP server"
- 在打开的 JSON 配置文件中添加以下配置：

{
  "mcpServers": {
    "promptpilot": {
      "command": "npx",
      "args": ["promptpilot-mcp-server"],
      "env": {
        "AGENTPILOT_API_KEY": "your_agentpilot_api_key",
        "ARK_API_KEY": "your_ark_api_key",
        "AGENTPILOT_API_URL": "https://agentpilot.bytedance.com",
        "DEFAULT_MODEL": "Deepseek-R1-250528",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

保存并刷新
- 保存配置文件
- 点击刷新图标重新加载 MCP 服务器
- 确认出现绿色圆点表示服务器运行正常

方法二：使用 SSE 传输协议

如果需要远程部署或更高级的配置，可以使用 Server-Sent Events (SSE) 传输协议 1：

启动 MCP 服务器（SSE 模式）

# 设置环境变量并启动 SSE 服务器
AGENTPILOT_API_KEY="your_agentpilot_api_key" \
ARK_API_KEY="your_ark_api_key" \
AGENTPILOT_API_URL="https://agentpilot.bytedance.com" \
DEFAULT_MODEL="Deepseek-R1-250528" \
LOG_LEVEL="INFO" \
npx promptpilot-mcp-server --transport sse --port 8000

在 Cursor 中配置 SSE 连接

{
  "mcpServers": {
    "promptpilot": {
      "url": "http://localhost:8000/sse"
    }
  }
}

在 Cursor 中使用

配置完成后，你可以在 Cursor 的 Agent 模式中使用 PromptPilot 功能：

切换到 Agent 模式
- 在聊天面板中选择 "Agent" 模式
- 确保 PromptPilot 工具在 "Available Tools" 列表中显示
使用工具
- 工具会在相关时自动调用
- 也可以通过名称明确请求特定工具
- 点击工具名称可以启用/禁用特定工具
示例对话

请帮我优化这个提示词：写一个关于机器学习的文章

生成一个 Python 数据分析的代码提示词

工具审批和自动运行

工具审批：默认情况下，Agent 使用 MCP 工具前会请求批准 1
自动运行：可以启用 "auto-run" 模式让 Agent 自动使用工具，类似终端命令的 YOLO 模式

查看 MCP 日志

如果遇到问题，可以查看 MCP 日志进行调试 1：

打开输出面板：Ctrl+Shift+U（Windows/Linux）或 Cmd+Shift+U（macOS）
从下拉菜单中选择 "MCP Logs"
检查连接错误、认证问题或服务器崩溃信息

🔧 环境变量配置

| 变量名 | 描述 | 默认值 | 必需 | |--------|------|--------|------| | AGENTPILOT_API_KEY | AgentPilot API 密钥 | - | ✅ | | ARK_API_KEY | ARK API 密钥 | - | ✅ | | AGENTPILOT_API_URL | AgentPilot API 地址 | https://agentpilot.bytedance.com | ❌ | | DEFAULT_MODEL | 默认使用的模型 | Deepseek-R1-250528 | ❌ | | LOG_LEVEL | 日志级别 | INFO | ❌ |

🛠️ 可用工具

PromptPilot MCP Server 提供以下四个核心工具：

1. improve_prompt

功能：智能优化提示词

输入：原始提示词文本
输出：优化后的提示词和改进建议
用途：提升提示词的清晰度、准确性和效果

2. generate_code_prompt

功能：生成代码相关的提示词

输入：编程语言、功能描述、代码类型
输出：专业的代码生成提示词
用途：辅助代码开发和自动化编程

3. analyze_prompt_quality

功能：分析提示词质量

输入：待分析的提示词
输出：详细的质量评估报告
用途：评估提示词的有效性和改进空间

4. get_prompt_templates

功能：获取提示词模板

输入：模板类型或应用场景
输出：相关的提示词模板集合
用途：快速获取标准化的提示词模板

📚 使用示例

在 Claude Desktop 中使用

配置完成后，重启 Claude Desktop，你就可以在对话中使用以下功能：

请帮我优化这个提示词：写一个关于机器学习的文章

请生成一个 Python 数据分析的代码提示词

分析一下这个提示词的质量：请详细解释深度学习的原理

给我一些写作类的提示词模板

🔗 相关链接

npx 官方文档: 1
npm 官方文档: 2
Node.js npm 包管理器介绍: 3
Model Context Protocol: https://modelcontextprotocol.io/
Claude Desktop: https://claude.ai/desktop
Cursor IDE MCP 文档: 1
Cursor MCP 服务器目录: 4
TRAE AI IDE MCP 文档: 1
TRAE AI IDE 官网: https://traeide.com/
AgentPilot SDK 官方文档: https://www.volcengine.com/docs/82379/1587837

🐛 故障排除

常见问题

Claude Desktop 无法连接到 MCP Server
- 检查 JSON 配置文件格式是否正确
- 确认环境变量是否正确设置
- 查看 Claude Desktop 的日志输出
npx 命令执行失败
- 确保已安装 Node.js 和 npm
- 检查网络连接是否正常
- 尝试清除 npm 缓存：npm cache clean --force
API 密钥错误
- 验证 AGENTPILOT_API_KEY 和 ARK_API_KEY 是否有效
- 检查 API 地址是否正确

调试模式

设置环境变量 LOG_LEVEL=DEBUG 可以获取更详细的日志信息：

LOG_LEVEL=DEBUG npx promptpilot-mcp-server

🔧 本地开发和测试

项目结构

PromptPilot/
├── requirements.txt          # 项目依赖
├── .env.example             # 环境变量示例
├── config.py                # 配置管理
├── mcp_server.py            # MCP 服务器主文件
├── package.json             # npm 包配置
├── bin/promptpilot-mcp.js   # npx 入口文件
├── test_agentpilot_sdk.py   # SDK 功能测试
├── test_integration.py      # 集成测试
└── README.md               # 项目文档

本地开发设置

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

复制 .env.example 为 .env 并填入您的配置：

cp .env.example .env

编辑 .env 文件：

# AgentPilot SDK 配置
AGENTPILOT_API_KEY=your_agentpilot_api_key
AGENTPILOT_API_URL=https://prompt-pilot.cn-beijing.volces.com

# 方舟推理服务配置 (可选)
ARK_API_KEY=your_ark_api_key

# 测试配置
TEST_TASK_ID=your_test_task_id
TEST_VERSION=1
SAMPLING_RATE=0.1

3. 启动 MCP 服务器

python mcp_server.py

🎯 SDK 核心功能

AgentPilot SDK 提供以下核心功能：

Task 和 Prompt 管理: 通过 SDK 直接管理 task 和 prompt，读取和列出版本信息
数据闭环和反馈: 支持与 Ark client 兼容的 completion 接口，数据回流到 PromptPilot 页面
Prompt 优化和报告: 提交 prompt 优化任务，读取评估报告
在线评估: 提交自定义评估请求得到评估结果
Badcase 检测: 根据评估 score 和 confidence 判断 badcase
Prompt 生成: 根据 task_description 生成 prompt

🔑 获取 API Key

注意: AgentPilot SDK 和 API Key 目前为邀测能力，需要填写问卷申请。

独立站版本

登录 "PromptPilot"
点击左侧 "API Key" 按钮
点击 "选择使用"，复制 API_KEY

火山方舟版本

登录 "方舟"
左侧 "Prompt 管理"
点击 "Get API Key"
点击 "选择使用"，复制 API_KEY

📋 获取 Task ID

独立站版本

登录 "PromptPilot"
左侧 "Prompt 调试" 选择任务类型 "文本理解"
点击上方加号 "+" 新建任务
选择 "评分模式"

火山方舟版本

登录 "方舟"
左侧 "Prompt 调优"
点击上方加号创建任务

🧪 运行测试

运行所有测试

pytest -v

运行特定测试文件

# 运行 SDK 功能测试
pytest test_agentpilot_sdk.py -v

# 运行集成测试
pytest test_integration.py -v

运行特定测试方法

pytest test_agentpilot_sdk.py::TestAgentPilotSDK::test_task_and_prompt_management -v

测试覆盖范围

SDK 功能测试 (`test_agentpilot_sdk.py`)

✅ 配置验证
✅ SDK 导入测试
✅ 任务和 Prompt 管理
✅ 数据闭环和反馈
✅ Prompt 优化和报告
✅ 在线评估
✅ Badcase 检测
✅ Prompt 生成
✅ 采样率和数据上限
✅ 支持的任务类型
✅ 模型兼容性

集成测试 (`test_integration.py`)

✅ SDK 初始化
✅ 任务信息获取
✅ 带反馈的推理接口
✅ 评估提交
✅ Prompt 优化工作流
✅ Badcase 分析工作流

⚠️ 重要限制

回流采样比率: 默认采样率为 0.1，即每条数据有 0.1 的概率回流
回流数据上限: 默认为 2000 条，超过限制时回流会失败
支持的任务类型: 当前仅支持"文本理解"和"视觉理解"任务的评分模式
模型限制: model_name 必须是 prompt 生成页模型下拉菜单中支持的模型

✨ SDK 优势

低侵入性: 对现有 Agent/Workflow 代码修改几行即可集成
模块化: 可以单独或任意组合使用各功能模块
易扩展: 支持多种 AI 模型/接口，多种模态数据
开放性: 无缝支持通用开源框架（LiteLLM, LangChain, LlamaIndex 等）

🔧 开发故障排除

常见问题

配置验证失败
- 检查 .env 文件是否正确配置
- 确认 AGENTPILOT_API_KEY 已设置
SDK 导入失败
- 确认已安装 agent-pilot-sdk: pip install agent-pilot-sdk
- 检查网络连接
API 调用失败
- 验证 API Key 是否有效
- 检查 API URL 是否正确
- 确认账号已通过实名认证
测试跳过
- 大部分测试需要有效的 AGENTPILOT_API_KEY
- 集成测试可能需要额外的配置（如 TEST_TASK_ID）

📞 联系支持

如需申请 AgentPilot SDK 邀测权限或遇到技术问题，请：

填写官方问卷申请邀测
提交工单获取技术支持
查阅官方文档获取更多信息

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

注意：使用前请确保已获得相应的 API 密钥，并遵守相关服务的使用条款。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PromptPilot MCP Server

🚀 AgentPilot SDK 简介

📦 安装方式

方式一：使用 npx（推荐）

方式二：全局安装

方式三：本地开发

🚀 TRAE AI IDE 配置

系统环境准备

配置方法

方法一：从 MCP 市场添加（推荐）

方法二：手动添加配置

方法三：使用 SSE 传输协议

在 TRAE 中使用

TRAE 特色功能

故障排除

⚙️ Claude Desktop 配置

配置文件位置

配置方法

方法一：使用 npx（推荐）

方法二：使用启动脚本

方法三：内联环境变量

🎯 Cursor IDE 配置

配置步骤

方法一：全局 MCP 配置（推荐）

方法二：使用 SSE 传输协议

在 Cursor 中使用

工具审批和自动运行

查看 MCP 日志

🔧 环境变量配置

🛠️ 可用工具

1. improve_prompt

2. generate_code_prompt

3. analyze_prompt_quality

4. get_prompt_templates

📚 使用示例

在 Claude Desktop 中使用

🔗 相关链接

🐛 故障排除

常见问题

调试模式

🔧 本地开发和测试

项目结构

本地开发设置

1. 安装依赖

2. 配置环境变量

3. 启动 MCP 服务器

🎯 SDK 核心功能

🔑 获取 API Key

独立站版本

火山方舟版本

📋 获取 Task ID

独立站版本

火山方舟版本

🧪 运行测试

运行所有测试

运行特定测试文件

运行特定测试方法

测试覆盖范围

SDK 功能测试 (test_agentpilot_sdk.py)

集成测试 (test_integration.py)

⚠️ 重要限制

✨ SDK 优势

🔧 开发故障排除

常见问题

📞 联系支持

📄 许可证

SDK 功能测试 (`test_agentpilot_sdk.py`)

集成测试 (`test_integration.py`)