CloudOps MCP

CloudOps MCP는 정규화된 운영 인프라 컨텍스트(로그, 메트릭, 배포, 상태)를 AI 에이전트에 소수의 타입화된 경계 있는 도구 세트를 통해 노출하는 읽기 전용 Model Context Protocol 서버입니다.

존재 이유

인시던트를 조사하는 에이전트는 운영 컨텍스트가 필요합니다: 최근에 무엇이 변경되었는지, 오류율이 어떻게 보이는지, 로그가 무엇을 말하는지. 클라우드 API에 대한 무제한 액세스가 필요하지 않으며, 근본 원인을 결정하는 주체가 되어서는 안 됩니다.

CloudOps MCP는 둘 사이에 위치합니다:

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

각 계층은 더욱 정규화하고 에이전트가 요청할 수 있는 범위를 좁힙니다. 제공자 어댑터는 벤더 API를 공유 도메인 모델로 변환합니다. 서비스는 경계, 순서, 집계를 결정론적으로, 모든 제공자에 대해 동일한 방식으로 적용합니다. MCP 도구는 이를 작은 타입화된 표면으로 노출합니다.

CloudOps MCP는 근본 원인 결론이 아닌 운영 사실을 반환합니다. 도구는 "오류율이 14:06에 0.4%에서 8%로 증가했습니다"라고 말할 수 있지만, "배포가 중단을 일으켰습니다"라고 말하지 않습니다. 그 판단은 CloudOps MCP가 증거로 제공하는 사실을 바탕으로 에이전트에게 맡겨집니다.

Related MCP server: cloud-chat-assistant

기능

6개의 도구, 모두 읽기 전용이며 경계가 있습니다:

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 쿼리의 경우, AWS IAM 권한 부여 모델에서 GetMetricData에는 리소스 수준 범위 지정이 없으므로 해당 문은 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 MCDK는 structuredContent와 도구의 출력 스키마를 반환 타입에서 직접 파생합니다. 도구 응답은 실데 구조 데이티이며 텍트 블록으로 감싸진 JSN 문자열이 아닙니다.

아키텍처

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/architure.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는 특정 소비에 결되지 않않습니다.

보안

• 프로바이더 인터페이스에는 변경 메서드가 전혀 없습니다.

• 셸 실행이나 클라우드 CLI 서브프로세스 호출이 없습니다.

• 최소 권한 IAM: 정확히 logs:FilterLogEvents와 cloudwatch:GetMetricData만 있으며, "만약을 대비해" 요청된 것은 없습니다.

• 표준 AWS 자격 증명 체인만 사용하며, 사용자 정의 자격 증명 처리는 없습니다.

• 내부 프로바이더 참조(로그 그룹 이름, CloudWatch 차원)는 도구 출력에 절대 나타나지 않습니다.

• 로그 콘텐츠는 신뢰할 수 없는 불투명 텍스트로 처리되며, 절대 구문 분석, 실행 또는 해석되지 않습니다.

• 예상치 못한 오류는 도구 경계에서 정리되며, 고정된 일반 메시지만 경계를 넘고, 원시 예외 문자열은 절대 넘지 않습니다.

• 모든 원격 측정 쿼리는 제한되어 있어, 프로바이더 API와 에이전트의 컨텍스트 창을 모두 보호합니다.

라이선스

MIT, LICENSE를 참조하세요.