CloudOps MCP

CloudOps MCP 是一个只读的模型上下文协议服务器，通过一组小型、类型化、有边界的工具，向 AI 智能体暴露标准化的运维基础设施上下文（日志、指标、部署、健康状态）。

为什么存在

调查事件的智能体需要运维上下文：最近发生了什么变化、错误率如何、日志说了什么。它不需要对云 API 的无限制访问，也不应该由它来决定什么是根本原因。

CloudOps MCP 位于两者之间：

Cloud APIs / observability systems
        |
Provider adapters
        |
Normalized operational domain
        |
Deterministic services
        |
MCP tools
        |
AI agent

每一层进一步标准化并缩小智能体可以请求的范围。提供商适配器将供应商 API 转换为共享领域模型。服务以确定性方式应用边界、排序和聚合，对每个提供商都相同。MCP 工具将其暴露为一个小型、类型化的表面。

CloudOps MCP 返回运维事实，而非根本原因结论。一个工具可以说“错误率从 0.4% 增加到 8% 在 14:06”；它不会说“部署导致了中断”。该判断属于智能体，使用 CloudOps MCP 作为证据提供的事实。

Related MCP server: cloud-chat-assistant

能力

六个工具，全部只读且有边界：

get_operational_snapshot 组合了其他五个工具使用的相同原始服务，并发运行所有四个独立查询。它从不直接与提供商通信，也绝不会因为某个部分不可用而整体失败，每个部分报告自己的状态。

设计原则

• 构造上只读。 提供商接口不暴露任何修改方法。没有通往写入 API 的代码路径。

• 提供商无关的服务标识。 服务由 (service, environment) 标识。供应商特定的标识符（CloudWatch 日志组、Kubernetes 对象名称）保留在提供商绑定的内部，绝不成为公共契约的一部分。

• 规范、可扩展的指标。 error_rate、latency_p99 等名称是我们的，不是供应商的。从规范名称到真实指标的映射存在于每个服务的配置中。词汇表是开放的，不是固定的枚举。

• 有边界的查询。 每个遥测查询都有时间范围上限和数量上限。调用者可以请求更少；但不能请求无边界的数据。

• 显式的数据可用性。 每个集合报告 SUCCESS、EMPTY、PARTIAL 或 FAILED 之一。缺失的数据永远不会被静默视为“健康”或“什么都没发生”。

• 可用性与结果分离。 NOT_CONFIGURED（未连接提供商）和 EMPTY（成功查询，零匹配）是不同的状态，绝不混为一谈。

• 来源而不泄露内部细节。 当提供商适配器提供时，单个结果携带 provider 和 source。用于调用提供商的内部引用绝不会复制到公共输出中。

• 处处使用 UTC。 所有时间戳都感知时区并标准化为 UTC；朴素日期时间在模型边界被拒绝。

• MCP 服务器内部没有 LLM。 没有摘要、没有分类、没有对日志内容的推理。日志消息被视为不透明的、不可信的文本。

• 没有因果推理。 工具报告什么发生了变化以及何时发生。解释原因留给智能体。

快速开始：模拟模式

模拟模式是默认模式，也是尝试 CloudOps MCP 的主要方式。它不需要云账户。

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

运行服务器（stdio 传输）：

python -m cloudops_mcp.server

或者，如果包已安装其控制台脚本：

cloudops-mcp

服务器通过 stdio 使用 MCP 协议，并期望客户端在另一端。要直接从 Python 使用官方 SDK 的客户端尝试：

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool(
                "get_operational_snapshot",
                {"service": "checkout-api", "environment": "production"},
            )
            print(result.structured_content)

asyncio.run(main())

模拟场景

使用 CLOUDOPS_MCP_SCENARIO 选择场景（默认为 healthy）：

CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.server

bad_deploy 在固定时间戳植入三个相关事实：一次部署，几分钟后的指标变化，以及之后不久的超时日志行。CloudOps MCP 仅报告这三个事实，不再多言。它不声称部署导致了错误，该推理完全留给消费智能体。

AWS CloudWatch 模式

pip install -e ".[aws]"        # runtime only
pip install -e ".[dev,aws]"    # development

CLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp

参见 examples/aws-cloudwatch.toml 获取完整示例配置。它仅使用占位符值，该文件中不应包含真实的账户 ID、ARN 或凭证。

凭证完全来自 boto3 的标准提供商链：AWS_PROFILE、AWS_REGION / AWS_DEFAULT_REGION、环境凭证或 IAM 角色。CloudOps MCP 从不读取、存储或记录访问密钥或秘密。

在 AWS 模式下实现：

• 日志：CloudWatch Logs FilterLogEvents。

• 指标：CloudWatch GetMetricData（仅 MetricStat 查询）。

尚未实现：AWS 支持的部署和健康状态。未配置这些部分的服务只需为它们报告 NOT_CONFIGURED，与任何其他未配置的能力相同。参见 docs/aws.md 了解配置模式、分页行为和限制。

AWS IAM

此集成的最低只读策略（虚构账户和日志组）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:FilterLogEvents",
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

FilterLogEvents 可以限定到特定的日志组 ARN。对于此集成发出的 MetricStat 查询，GetMetricData 在 AWS 的 IAM 授权模型中没有资源级限定，因此该语句使用 Resource: "*"。这是 API 的属性，而非此处做出的选择。

有边界的查询

每个有边界的结果都报告 requested_bounds 和 applied_bounds，以便调用者可以准确看到被限制的内容。将请求限制到硬上限与 PARTIAL 不同：一个被限制但完全满足的查询仍然是 SUCCESS。PARTIAL 意味着提取本身已知不完整，例如提供商分页并在耗尽应用窗口内的所有匹配项之前停止。

数据可用性语义

两个正交问题，绝不合并为一个：

1. 此服务是否配置了该能力？（CONFIGURED / NOT_CONFIGURED）

2. 如果已查询，发生了什么？（SUCCESS / EMPTY / PARTIAL / FAILED）

对于没有配置健康提供商的服务的健康检查是 NOT_CONFIGURED，而不是 EMPTY 也不是 FAILED。在时间窗口内合法地未找到任何内容的日志查询是 EMPTY，而不是 FAILED。在返回任何可用内容之前遇到速率限制的指标调用是 FAILED 并带有原因，而不是静默的空数据。

结构化的 MCP 输出

每个工具接受类型化参数并返回一个类型化的 Pydantic 模型。官方的 Python MCP SDK 直接从该返回类型派生 structuredContent 和工具的输出模式，工具响应是真正的结构化数据，而不是包裹在文本块中的 JSON 字符串。

架构

flowchart TD
    subgraph Providers
        Fake[Fake providers]
        AWS[AWS CloudWatch providers]
    end

    Fake --> Services
    AWS --> Services

    Registry[ServiceRegistry] --> Services

    subgraph Services[Deterministic services]
        Catalog[catalog_service]
        Health[health_service]
        Deploy[deployment_service]
        Logs[logs_service]
        Metrics[metrics_service]
        Snapshot[snapshot_service]
    end

    Snapshot --> Deploy
    Snapshot --> Logs
    Snapshot --> Metrics
    Snapshot --> Health

    Services --> Tools[MCP tools]
    Tools --> Agent[AI agent]

get_operational_snapshot 组合原始服务，它不绕过它们或自行与提供商通信。参见 docs/architecture.md 获取完整的技术分解。

测试

• 确定性的模拟场景端到端地测试完整的工具表面。

• 提供商层测试使用故意行为不当的存根提供商（错误排序、忽略边界）来证明服务层本身保护输出，而不仅仅是行为良好的提供商。

• AWS 提供商测试使用小型存根 CloudWatch 客户端，没有真实的 AWS 调用，没有 moto，没有 LocalStack。

• 一个测试驱动真实的 MCP SDK 客户端与进程内服务器，确认协议边界本身（工具发现、结构化输出），而不仅仅是内部逻辑。

ruff check src tests
mypy src tests --strict
pytest -q

当前限制

• AWS 实时验证已通过类型化配置解析、存根客户端测试和真实的 MCP 客户端/服务器边界完成，尚未针对真实的 AWS 账户进行。这需要用户选择的资源，并且有意不自动化：CloudOps MCP 不会自行发现或探测账户。

• 尚无 AWS 支持的部署或健康提供商。

• 仅 stdio 传输，无远程 MCP。

• 服务注册表是静态的且由配置支持，没有从云账户自动发现服务。

• 没有任何类型的修改、修复或写入路径。

路线图

• 现有提供商上的额外只读能力。

• 第二个真实提供商，以针对多个供应商压力测试标准化边界。

• 远程传输，如果部署场景确实需要的话。

• 被事件响应智能体消费，作为通用 MCP 客户端的一个示例。CloudOps MCP 不与任何特定消费者耦合。

安全

• 提供者接口中没有任何变更方法。

• 不执行 shell 命令，不调用云 CLI 子进程。

• 最小权限 IAM：仅包含 logs:FilterLogEvents 和 cloudwatch:GetMetricData，不请求任何“以防万一”的权限。

• 仅使用标准 AWS 凭证链，不进行自定义凭证处理。

• 内部提供者引用（日志组名称、CloudWatch 维度）永远不会出现在工具输出中。

• 日志内容被视为不可信的不透明文本：从不解析、执行或解释。

• 意外失败在工具边界处被清理；只有固定的通用消息跨越该边界，绝不包含原始异常字符串。

• 每次遥测查询都有边界限制，既保护提供者 API，也保护代理的上下文窗口。

许可证

MIT，参见 LICENSE。