flashduty-mcp-server

🚀 Flashduty MCP Server

Flashduty MCP Server 是一个 模型上下文协议（Model Context Protocol，MCP） 服务器，它能与 Flashduty API 实现无缝集成，为开发者和工具提供高级的事件管理和自动化功能。

🔍 使用场景

• 自动化执行 Flashduty 工作流和流程。
• 从 Flashduty 中提取和分析数据。
• 构建与 Flashduty 交互的人工智能驱动工具和应用程序。

🚀 快速开始

🌐 远程 Flashduty MCP 服务器

远程 Flashduty MCP 服务器提供了最简单的方式来实现与 Flashduty 的集成。如果你的 MCP 主机不支持远程 MCP 服务器，你可以使用 本地版本的 Flashduty MCP 服务器。

📋 前提条件

1. 支持最新 MCP 规范和远程服务器的 MCP 主机，例如 Cursor。
2. 从你的 Flashduty 账户获取的 Flashduty APP 密钥。

💻 安装步骤

以 Cursor 为例：

对于支持远程 MCP 的 Cursor，使用以下配置：

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/flashduty",
      "authorization_token": "Bearer <your_flashduty_app_key>"
    }
  }
}

⚠️ 重要提示

请参考你的 MCP 主机文档，以获取远程 MCP 服务器设置的正确语法和位置。

💻 本地 Flashduty MCP 服务器

📋 前提条件

1. 若要在容器中运行服务器，你需要安装并运行 Docker。
2. 从你的 Flashduty 账户获取的 Flashduty APP 密钥。

💻 安装步骤

以 Cursor 为例：

🐳 使用 Docker

将以下 JSON 块添加到你的 Cursor MCP 配置中。

{
  "mcpServers": {
    "flashduty": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FLASHDUTY_APP_KEY",
        "flashcat.tencentcloudcr.com/flashduty/flashduty-mcp-server"
      ],
      "env": {
        "FLASHDUTY_APP_KEY": "your_flashduty_app_key"
      }
    }
  }
}

💽 使用二进制文件

除了从源代码进行构建，你还可以直接从项目的 GitHub 发布页面 下载适合你操作系统的预编译版本，这是一种更快、更方便的选择。

如果你更喜欢从源代码构建，可以在 cmd/flashduty-mcp-server 目录中使用 go build 来构建二进制文件。你可以通过环境变量或命令行参数提供 APP 密钥。

你应该将你的 MCP 主机配置为使用构建好的可执行文件作为其 command。例如：

通过环境变量：

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio"],
      "env": {
        "FLASHDUTY_APP_KEY": "your_app_key_here"
      }
    }
  }
}

通过命令行参数：

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio", "--app-key", "your_app_key_here"]
    }
  }
}

⚙️ 工具配置

Flashduty MCP 服务器支持多种配置选项，以满足不同的使用场景。主要选项包括：

• 工具集：允许你启用或禁用特定的功能组。仅启用你需要的工具集可以帮助大语言模型（LLM）选择工具，并减少上下文大小。
• 只读模式：将服务器限制为只读操作，防止任何修改，增强安全性。
• 国际化（i18n）：支持自定义工具描述，以适应不同的语言或团队偏好。

配置方法分为 远程服务配置 和 本地服务配置。

🌐 远程服务器配置

当使用公共远程服务 (https://mcp.flashcat.cloud/flashduty) 时，你可以通过在 URL 后附加查询参数来动态配置它。

🔧 配置示例

以下是一个配置远程服务的示例，指定了工具集和只读模式：

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/flashduty?toolsets=flashduty_incidents,flashduty_teams&read_only=true",
      "authorization_token": "Bearer <your_flashduty_app_key>"
    }
  }
}

• toolsets=...：使用逗号分隔的列表指定要启用的工具集。
• read_only=true：启用只读模式。

💻 本地服务器配置

当通过 Docker 或从源代码在本地运行服务时，你可以完全控制配置。

1. 通过环境变量

这是本地配置最常用的方法，特别是在 Docker 环境中。

| 变量 | 描述 | 是否必需 | 默认值 | |------|------|----------|--------| | FLASHDUTY_APP_KEY | Flashduty APP 密钥 | ✅ | - | | FLASHDUTY_TOOLSETS | 要启用的工具集（逗号分隔） | ❌ | 所有工具集 | | FLASHDUTY_READ_ONLY | 限制为只读操作（1 或 true） | ❌ | false | | FLASHDUTY_BASE_URL | Flashduty API 基础 URL | ❌ | https://api.flashcat.cloud | | FLASHDUTY_LOG_FILE | 日志文件路径 | ❌ | 标准错误输出 | | FLASHDUTY_ENABLE_COMMAND_LOGGING | 启用命令日志记录 | ❌ | false |

Docker 示例：

docker run -i --rm \
  -e FLASHDUTY_APP_KEY=<your-app-key> \
  -e FLASHDUTY_TOOLSETS="flashduty_incidents,flashduty_teams" \
  -e FLASHDUTY_READ_ONLY=1 \
  flashcat.tencentcloudcr.com/flashduty/flashduty-mcp-server

2. 通过命令行参数

如果你直接从源代码构建并运行二进制文件，可以使用命令行参数。

./flashduty-mcp-server stdio \
  --app-key your_app_key_here \
  --toolsets flashduty_incidents,flashduty_teams \
  --read-only

可用的命令行参数：

• --app-key：Flashduty APP 密钥（替代 FLASHDUTY_APP_KEY 环境变量）
• --toolsets：要启用的工具集，用逗号分隔
• --read-only：启用只读模式
• --base-url：Flashduty API 基础 URL
• --log-file：日志文件路径
• --enable-command-logging：启用命令日志记录
• --export-translations：将翻译保存到 JSON 文件

⚠️ 重要提示

命令行参数优先于环境变量。对于工具集配置，如果同时设置了 FLASHDUTY_TOOLSETS 环境变量和 --toolsets 参数，命令行参数将优先。

3. 国际化（i18n）/ 覆盖描述（仅适用于本地部署）

覆盖工具描述的功能仅适用于本地部署。你可以通过创建 flashduty-mcp-server-config.json 文件或设置环境变量来实现。

通过 JSON 文件： 在与二进制文件相同的目录中创建 flashduty-mcp-server-config.json：

{
  "TOOL_CREATE_INCIDENT_DESCRIPTION": "an alternative description",
  "TOOL_LIST_TEAMS_DESCRIPTION": "List all teams in Flashduty account"
}

通过环境变量：

export FLASHDUTY_MCP_TOOL_CREATE_INCIDENT_DESCRIPTION="an alternative description"

🛠️ 可用工具集

以下工具集可用（默认全部启用）。你也可以使用 all 来启用所有工具集。

| 工具集 | 描述 | | ---- | ---- | | flashduty_incidents | Flashduty 事件管理工具 | | flashduty_members | Flashduty 成员管理工具 | | flashduty_teams | Flashduty 团队管理工具 | | flashduty_channels | Flashduty 协作渠道管理工具 |

🧰 工具列表

服务器基于 Flashduty API 提供以下工具集：

flashduty_members - 成员管理工具

• flashduty_member_infos - 通过人员 ID 获取成员信息

flashduty_teams - 团队管理工具

• flashduty_teams_infos - 通过团队 ID 获取团队信息

flashduty_channels - 渠道管理工具

• flashduty_channels_infos - 通过渠道 ID 获取协作空间信息

flashduty_incidents - 事件管理工具

• flashduty_incidents_infos - 通过事件 ID 获取事件信息
• flashduty_list_incidents - 使用综合过滤器列出事件
• flashduty_list_past_incidents - 列出类似的历史事件
• flashduty_get_incident_timeline - 获取事件时间线和动态
• flashduty_get_incident_alerts - 获取与事件关联的警报
• flashduty_create_incident - 创建新事件
• flashduty_ack_incident - 确认事件
• flashduty_resolve_incident - 解决事件
• flashduty_assign_incident - 将事件分配给人员或升级规则
• flashduty_add_responder - 为事件添加响应者
• flashduty_snooze_incident - 暂停事件一段时间
• flashduty_merge_incident - 将多个事件合并为一个
• flashduty_comment_incident - 为事件添加评论
• flashduty_update_incident_title - 更新事件标题
• flashduty_update_incident_description - 更新事件描述
• flashduty_update_incident_impact - 更新事件影响
• flashduty_update_incident_root_cause - 更新事件根本原因
• flashduty_update_incident_resolution - 更新事件解决方案
• flashduty_update_incident_severity - 更新事件严重程度
• flashduty_update_incident_fields - 更新自定义字段

📚 库使用说明

目前，此模块导出的 Go API 应被视为不稳定的，可能会有重大更改。未来我们可能会提供稳定性保障；如果你有相关使用场景，请提交一个 issue。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。