Signal Agent 🚨

Signal Agent 🚨

通过 Model Context Protocol（MCP）智能处理故障事件

一个可用于生产环境的 MCP 服务和客户端系统，可通过自动分类、严重性分析和响应建议，将原始故障事件转化为可执行的情报。

🎯 什么是 Signal Agent？

Signal Agent 展示了 Model Context Protocol（MCP）在构建智能自动化系统方面的强大能力。它通过一套复杂的分析流程处理故障事件，该流程能够：

• 🔍 分析故障事件内容，使用基于关键词的严重性评估
• 📊 分类事件，将其归入运营类别（数据库、网络、安全等）
• 💡 生成适当的响应建议
• 📋 整理易于运维团队阅读的摘要

✨ 主要功能

🏗️ 可用于生产环境的架构

• 符合标准的 MCP 实现，使用官方 SDK
• 可靠的输入验证，采用 Pydantic 模式
• 完善的错误处理和日志记录
• 与传输方式无关的设计（开发时使用 stdio，生产环境使用可流式传输的 HTTP）

🧠 智能分析流程

• 多阶段事件处理，包含验证和丰富处理
• 基于关键词重新计算严重性，不依赖来源评估
• 运营分类，便于正确路由事件
• 根据严重性和事件类型提供情境化建议

🔧 开发者体验

• 多种部署模式（集成演示、仅服务端、仅 Agent）
• 兼容 MCP Inspector，支持交互式测试
• 完善的日志记录和调试支持
• 清晰分离传输逻辑与业务逻辑

🚀 快速开始

前置条件

• Python 3.8+
• uv（现代 Python 包管理器）
• just

安装

git clone https://github.com/no0ktheali3n/signal-agent.git
cd signal-agent

# Setup environment and dependencies
uv venv                         #first time only

just venv                       #activates venv

just init-install               #qol scripts and copes justfile to root

just sync                       #syncs environment dependencies

运行演示

# Full integrated demonstration
just run

# Server only (for MCP Inspector testing)  
just run server

# Agent only (launches server subprocess)
just run agent

可用命令

just compile      # Lock dependencies
just sync         # Install dependencies  
just upgrade      # Upgrade all dependencies
just activate     # Activate virtual environment
just run [mode]   # Run Signal Agent (demo/server/agent)

🏗️ 架构

Signal Agent 采用清晰的模块化架构，分离不同职责，便于轻松演进：

┌─────────────────┐    MCP Protocol    ┌──────────────────┐
│   Signal Agent  │◄──────────────────►│  Signal Server   │
│   (Client)      │     stdio/HTTP     │   (MCP Server)   │
│                 │                    │                  │
│ • Event Loading │                    │ • Tool Registry  │
│ • Result Display│                    │ • Event Analysis │
│ • Demo Workflow │                    │ • Classification │
└─────────────────┘                    └──────────────────┘

核心组件

🖥️ Signal 服务（server/server.py）

• 符合 MCP 规范的服务端，使用官方 SDK
• 工具注册，配有合适的输入模式
• 事件分析流程，采用多阶段处理
• 基于标准的响应，使用 TextContent 格式

🤖 Signal Agent（agent/signal_agent.py）

• MCP 客户端，使用 stdio 传输
• 事件处理工作流协调
• 结果格式化和显示
• 演示功能，含测试数据

🎛️ 主协调器（main.py）

• 多模式部署（演示、仅服务端、仅 Agent）
• 组件生命周期管理
• 平稳关闭处理

🔧 MCP 集成

服务端工具

classify_failure_event

通过智能分析流程处理故障事件。

输入模式：

{
  "event_id": "string",
  "timestamp": "string", 
  "service": "string",
  "severity": "string",
  "message": "string",
  "details": "object (optional)"
}

用法示例：

{
  "event_id": "sig_001_db_failure",
  "timestamp": "2024-12-11T14:30:45Z",
  "service": "user-authentication-service",
  "severity": "critical",
  "message": "PostgreSQL connection pool exhausted",
  "details": {
    "pool_size": 20,
    "active_connections": 20,
    "queue_length": 150
  }
}

响应：

{
  "event_id": "sig_001_db_failure",
  "original_severity": "critical",
  "calculated_severity": "critical",
  "classification": "database_issue",
  "recommendation": "Immediate attention required - escalate to on-call engineer",
  "human_readable": "🚨 Signal Alert: sig_001_db_failure...",
  "status": "processed"
}

health_check

验证服务健康状态和连接情况。

使用 MCP Inspector 测试

# In another terminal, launch MCP Inspector
npx @modelcontextprotocol/inspector uv run python server/server.py

or

just run-inspector

测试 HTTP 传输

# Terminal 1: Start HTTP server
just run-server-http

# Terminal 2: Test with HTTP agent
just run-agent-http

# Or test with direct commands
python main.py server --transport http
python main.py agent --transport http

Inspector 将在 http://localhost:#### 提供 Web 界面，以便交互式测试工具。

📊 分析流程

Signal Agent 通过一套复杂的多阶段流程处理事件：

1. 输入验证

• JSON 解析和结构验证
• 强制执行 Pydantic 模型
• 验证必填字段

2. 严重性分析

• 基于关键词的内容分析
• 与严重性指标进行模式匹配
• 独立于来源评估重新计算

3. 事件分类

• 确定运营类别
• 模式匹配：
  • 数据库问题
  • 网络问题
  • 资源限制
  • 安全事件
  • 服务故障

4. 生成建议

• 提供结合上下文的响应建议
• 基于严重程度的升级规则
• 标准化运营流程

5. 摘要格式化

• 编译易于阅读的结果
• 结构化展示格式
• 兼容运营仪表板

🎯 使用场景

🏢 企业运营

• 事件响应自动化 - 智能事件分类与路由
• 运营智能分析 - 模式识别与趋势分析
• 团队协作 - 标准化沟通与升级

🔧 开发工作流

• 监控集成 - 处理来自 Sentry、Datadog 等工具的警报
• CI/CD 增强 - 自动分析和报告故障
• 质量保证 - 系统化错误分类与跟踪

📚 学习与研究

• MCP 协议示例 - 参考实现模式
• AI 集成模式 - 智能自动化架构
• 协议标准 - MCP 服务开发最佳实践

🛠️ 开发

项目结构

signal-agent/
├── server/
│   └── server.py          # MCP server implementation
├── agent/
│   └── signal_agent.py    # MCP client implementation
├── main.py                # System orchestrator
├── events/
│   └── test_payload.json  # Demo event data
├── docs/                  # Documentation
└── examples/              # Usage examples

运行测试

# Test server with MCP Inspector (stdio)
just run-inspector

# Test HTTP server and agent
just run-server-http &    # Background streamable-HTTP MCP server
just run-agent-http       # streamable-HTTP agent test / listener 

我们的 Agent 有双重用途：既可作为 HTTP 监听器用于手动测试，也可作为 MCP 客户端与 MCP 服务交互。

要进行手动测试，请运行 Agent，然后选择选项 3 以启动监听器。

服务运行在 localhost:8000，监听器运行在 localhost:8001。

要进行手动测试（最新更新导致主协调器无法运行），请运行 chaos_agent：

#runs chaos agent to run 10 events with 1.5 second delay between event
python agent/chaos_agent.py --count 10 --delay 1.5

事件通过 SQLite 本地存储在 signals_events.db 中。

现在运行另一个 Agent：

just run-agent-http

现在，我们可以使用 Agent 作为 MCP 客户端与 MCP 服务交互，并使用服务提供的工具。这样，我们便可以在命令行界面中查询 signal_events.db，获取事件数据。

代码质量

• 整个代码库均包含类型提示
• 全面的日志记录，便于调试
• 错误处理，支持优雅降级
• 为所有公共接口编写文档

🚀 演进路线图

Signal Agent 为构建更复杂的事件响应系统奠定了基础：

🎯 当前状态（v1.1.0）

• ✅ 符合标准的 MCP 实现
• ✅ 智能事件分析
• ✅ 支持双传输方式（stdio + HTTP streamable）
• ✅ 可用于生产环境的架构
• ✅ 采用 justfile 自动化的现代开发工作流

🔮 未来演进

• 🌐 HTTP 传输，支持分布式部署
• 📊 集成多种监控工具（Sentry、Datadog、Raygun）
• 🤖 通过 机器学习增强模式识别
• 🏢 面向 MSP 环境的 企业功能

🤝 贡献

欢迎贡献！本项目展示了 MCP 最佳实践，并可作为社区参考。

贡献方向

• 为不同事件类型添加 更多分析模式
• 传输方式实现（SSE、WebSocket）
• 与常用监控工具集成的 示例
• 改进文档并编写教程

📄 许可证

MIT 许可证——详情请参阅 LICENSE。

🔗 链接

• Model Context Protocol - MCP 官方文档
• MCP Python SDK - 官方 Python 实现

🙏 致谢

本项目基于官方 Model Context Protocol SDK 构建，旨在满足现代运营对智能自动化的需求。

---

Signal Agent - 借助 MCP 的力量，将原始故障事件转化为可执行的智能信息。🚨➡️🧠