Air Controls MCP

空气控制MCP服务器

AI代理的运行时可见性层 --MCP（模型上下文协议）服务器，自动将代理操作记录到AIR-Controls中，并具有完整的审计链完整性。

该服务器允许Cursor、Claude Code、Windsurf和任何其他兼容MCP的AI开发工具自动捕获代理正在做的事情，并提供完整的元数据以实现合规性、安全性和调试。

特性

• 自动动作记录 -捕获LLM调用、工具使用、API请求、文件编辑、命令和错误
• HMAC-SHA256审计链 -事件历史未被篡改的加密证明
• 元数据跟踪 -令牌、成本、持续时间、风险评分和自定义字段
• 代理控制 -使用单个命令暂停/恢复代理（终止开关）
• 链式验证 -验证整个审计跟踪的完整性
• 多工具支持 -适用于Cursor、Claude Code、Windsurf和任何MCP客户端

安装

1.安装包装

pip install air-controls-mcp

这将安装MCP服务器和底层 air-controls 存储层。

2.配置您的AI工具

选择下面的工具，并将MCP服务器配置添加到其设置文件中。

光标

添加 ~/.cursor/mcp.json （如果不存在则创建）：

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

地点： 打开光标设置（Cmd+或Ctrl+），搜索“MCP”，并编辑用户目录中的MCP.json文件。

克劳德代码（VS代码扩展）

添加 ~/.claude/mcp.json （如果不存在则创建）：

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

地点： 在VS Code中，打开Claude Code侧栏，单击设置，然后选择“编辑MCP设置”以访问MCP.json文件。

帆板运动

添加 ~/.windsurf/mcp.json （如果不存在则创建）：

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

地点： 打开Windsurf设置，搜索“MCP”，然后编辑配置文件。

自定义工具/通用MCP客户端

对于任何其他MCP兼容工具，请将配置添加到其MCP设置文件中：

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db",
        "AIR_AGENT_NAME": "my-custom-agent"
      }
    }
  }
}

3.重新启动工具

重新启动Cursor、Claude Code、Windsurf或您的MCP客户端。空气控制工具现在应该可用。

用法

配置后，您可以在任何对话中访问这些工具：

log_action

记录代理操作（主要工具）。所需参数：

• agent_name -代理的显示名称
• action_type -其中之一： llm_call, tool_use, api_call, file_edit, command_run, decision, error
• description -人类可读的事件摘要

可选参数：

• raw_action -技术细节（JSON、回溯、代码等）
• tokens_used -LLM调用的令牌计数
• cost_usd -成本（美元）
• duration_ms -执行持续时间（毫秒）
• risk_score -风险评估： low, medium，或 high

例子：

Log this agent action:
- Agent: my-research-bot
- Type: llm_call
- Description: Searched for recent AIR Act guidelines using Claude 3.5 Sonnet
- Tokens: 4200
- Cost: 0.0315
- Duration: 2100ms
- Risk: low

获取状态

获取所有受监视代理和最近活动的概述。显示：

• 受监控的代理人总数
• 每个代理的状态（活动或暂停）
• 事件计数和错误计数
• 所有代理的总成本

例子：

Get a status report of all monitored agents

get_timeline

获取特定代理的事件时间线。按时间顺序显示最近的事件。

参数：

• agent_name -代理人姓名
• limit -要显示的事件数（默认值：20）

例子：

Show me the timeline for my-research-bot with the last 30 events

贫民

暂停代理（终止开关）。阻止代理采取进一步行动。

参数：

• agent_name -要暂停的代理的名称

例子：

Pause the my-research-bot agent

简历_代理

恢复之前暂停的代理。

参数：

• agent_name -要恢复的代理人姓名

例子：

Resume my-research-bot

验证链

验证HMAC-SHA256审核链的完整性。检查事件历史记录是否未被篡改。

参数：

• agent_name -可选。如果省略，则验证所有代理。

例子：

Verify the audit chain for my-research-bot

或者验证所有代理：

Verify the audit chain for all agents

资源

服务器公开了两个用于浏览代理元数据的资源：

空气controls://agents

列出所有受监视的代理及其框架和状态。

空气controls://status

当前系统状态摘要，包括代理计数、事件总数和成本。

环境变量

配置这些可选环境变量以自定义服务器：

例子：

export AIR_CONTROLS_DB=/custom/path/events.db
export AIR_AGENT_NAME=my-research-agent
export AIR_FRAMEWORK=langchain

air-controls-mcp

数据库

MCP服务器使用SQLite进行存储：

• 用于审计链完整性的HMAC-SHA256签名
• 自动架构初始化
• 可配置路径（默认： ~/.air-controls/events.db)

数据库在首次使用时自动创建。

建筑

Your AI Tool (Cursor/Claude Code/Windsurf)
       ↓
    MCP Protocol
       ↓
AIR Controls MCP Server (this package)
       ↓
air_controls.EventStore
       ↓
SQLite Database with HMAC-SHA256 Chain

服务器：

1. 通过MCP协议从您的AI工具接收操作日志
2. 自动检测哪个工具正在调用它
3. 首次使用时自动创建代理
4. 使用完整的元数据存储操作
5. 维护加密审计链以确保合规性

例子

记录一个复杂的研究会议

Log this comprehensive agent action:
- Agent: research-team
- Type: api_call
- Description: Queried EU AI Act regulatory database for Article 9 requirements
- Raw: {"endpoint": "/api/v2/eu-ai-act", "method": "GET", "params": {"article": 9}}
- Tokens: 1200
- Cost: 0.008
- Duration: 3400ms
- Risk: medium

监控多个代理

Get a status report on all agents I've created

合规性验证

Verify the entire audit chain to ensure no events were tampered with

紧急停止

Pause the autonomous-trading-bot agent immediately

合规与安全

• HMAC-SHA256审计链 -事件完整性的加密证明
• 不可变记录 -事件仅可追加；永远无法修改
• 完整元数据 -每个操作的完整上下文（风险、成本、持续时间、令牌）
• 链式验证 -检测篡改加密验证
• 代理暂停/恢复 -代理人行为应急控制

非常适合：

• 欧盟人工智能法案合规性 （第10、12、14、15条）
• SOX合规性 -金融人工智能系统的审计跟踪
• ISO 42001 -人工智能管理系统
• 内部治理 -跟踪和控制AI代理行为
• 调试 -了解代理人做了什么以及为什么
• 成本跟踪 -LLM支出归因于特定的代理人和行为

贡献

欢迎投稿！请在GitHub上打开问题或拉取请求。

许可证

Apache许可证2.0——有关详细信息，请参阅许可证文件。

支持

• 文档 - https://github.com/airblackbox/air-controls-mcp
• 问题 - https://github.com/airblackbox/air-controls-mcp/issues
• 讨论 - https://github.com/airblackbox/air-controls-mcp/discussions

______________________________________________________________________

使用Anthropic的模型上下文协议构建。AIR-Controls生态系统的一部分，用于AI代理的可观察性和合规性。