Beagle Security MCP Server

Beagle安全MCP服务器

这是一个模型上下文协议（MCP）服务器，提供与Beagle Security API的集成。它允许您通过Beagle security平台管理项目、应用程序和自动化安全测试。

特性

• 项目管理：创建、修改、列出和删除项目
• 应用程序管理：创建、获取、修改、列出和删除应用程序
• 域名验证：获取验证签名，并使用多种签名类型验证域所有权
• 安全性测试：启动、监控、停止和检索自动渗透测试的结果
• 团队支持：与团队项目和测试合作

安装

选项1:Docker（推荐）

1. 克隆此存储库
2. 设置环境变量：

   cp .env.example .env
   # Edit .env with your API token

1. 使用Docker构建和运行：

   npm run docker:build
   npm run docker:run

或者使用Docker Compose：

docker-compose up -d

选项2：本地安装

1. 克隆此存储库
2. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

配置

环境变量

将Beagle Security API令牌设置为环境变量：

export BEAGLE_SECURITY_API_TOKEN=your_api_token_here

您可以从Beagle Security帐户设置（配置文件→ 个人访问令牌）。

MCP配置

Docker配置

将服务器添加到MCP配置文件中：

{
  "mcpServers": {
    "beagle-security": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i", 
        "--env", "BEAGLE_SECURITY_API_TOKEN=your_api_token_here",
        "--env", "NODE_ENV=production",
        "mcp/beagle-security-mcp-server"
      ]
    }
  }
}

本地配置

对于本地安装：

{
  "mcpServers": {
    "beagle-security": {
      "command": "node",
      "args": ["path/to/beagle-security-mcp-server/build/index.js"],
      "env": {
        "BEAGLE_SECURITY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

可用工具（共18个）

项目管理（4个工具）

• beagle_create_project：创建新项目
• beagle_modify_project：修改现有项目
• beagle_list_projects：列出所有项目和应用程序
• beagle_delete_project：删除项目

应用程序管理（5个工具）

• beagle_create_application：在项目中创建新应用程序
• beagle_get_application：通过令牌获取应用程序详细信息
• beagle_modify_application：修改现有应用程序
• beagle_list_applications：列出项目下的所有应用程序
• beagle_delete_application：删除应用程序

域验证（2个工具）

• beagle_get_domain_signature：获取域验证签名
• beagle_verify_domain：使用FILE、DNS或API签名类型完成域验证

安全测试（7个工具）

• beagle_start_test：启动自动渗透测试
• beagle_get_test_status：获取正在运行的测试的状态
• beagle_stop_test：停止运行测试
• beagle_get_test_result：获取JSON格式的详细测试结果
• beagle_list_test_sessions：列出应用程序的所有测试会话
• beagle_list_running_tests：列出用户或团队的所有正在运行的测试（支持团队筛选）

测试

综合测试套件

运行所有测试以验证功能：

# Run complete test suite (recommended)
npm run test:all

# Test individual components
npm run test:tools          # Test all 18 MCP tools
npm run test:integration    # Integration & API tests
npm run test                # Unit tests

# Test with real API (requires token)
BEAGLE_SECURITY_API_TOKEN=your_token npm run test:all

测试特性

• 工具验证：使用适当的参数测试所有18个工具
• API集成：提供凭证时进行API实时测试
• 错误处理：验证错误场景和边缘情况
• 交叉平台的：适用于Linux、macOS和Windows
• Docker测试：验证容器功能

有关详细的测试信息，请参阅 测试.md.

发展

Docker开发

# Build Docker image
npm run docker:build

# Run with Docker
npm run docker:run

# Use Docker Compose
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop services
npm run docker:compose:down

地方发展

# Running in Development Mode
npm run dev

# Building
npm run build

# Starting the Server
npm start

api参考

此服务器实现Beagle Security API v2.0。有关API的详细文档，请访问： https://beaglesecurity.com/developer/apidoc

API兼容性

此服务器实现 Beagle Security API v2.0 与：

• ✅ 所有端点均已验证 与官方文件不符
• ✅ 正确的参数命名 （camelCase格式）
• ✅ 正确的错误处理 适用于所有API响应代码
• ✅ API最新功能 包括域验证类型

错误处理

该服务器包括全面的错误处理功能，用于：

• 身份验证错误（API令牌无效）
• HTTP错误（网络问题、服务器错误）
• 验证错误（缺少必需的参数）
• 特定于API的错误（由Beagle Security返回）
• 跨平台兼容性问题

安全考虑

• 保持API令牌的安全，并且永远不要将其提交给版本控制
• 使用环境变量或安全配置管理
• 生成API令牌时确保设置了正确的作用域
• 监控API使用情况以检测未经授权的访问

故障排除

常见问题

1. 服务器无法启动：运行 npm run build 检查生成错误
2. API调用失败：验证您的 BEAGLE_SECURITY_API_TOKEN 有效
3. Docker问题：确保Docker已安装并正在运行
4. macOS超时错误：安装 brew install coreutils 否则测试将自动回退

获取帮助

• 运行测试套件： npm run test:all
• 检查开发模式下的日志： NODE_ENV=development npm start
• 审查 测试.md 详细故障排除

api参考

完整的API文件：https://beaglesecurity.com/developer/apidoc

许可证

MIT许可证