# MCP Cloud Operations Agent

## Overview

An MCP tool server for cloud operations that exposes read tools only. `GET /tools` lists `list_gke`, `describe_vm` and `get_billing`, and `POST /call` runs one of them; any request to apply changes is refused. It shows how an agent can inspect GKE clusters, VMs and billing without being able to change them.

- **Built with:** Python, pytest, GitHub Actions
- **Scope:** Local laptop proof with tests; it calls no hosted model and refuses apply.

<!-- project-guide:start -->
## Project guide

[Project architecture](PROJECT_ARCHITECTURE.md) · [Interview questions and answers](INTERVIEW_QA.md)

Use the architecture document for the component diagram, implementation boundaries, and verification entry points. The interview guide includes source-backed answers and project walkthroughs.

### Implementation map

| Component | Responsibility |
| --- | --- |
| [`src/mcpcloud/main.py`](src/mcpcloud/main.py) | HTTP handlers: `GET /healthz`, `GET /tools`, `POST /call` |
| [`src/mcpcloud/mcp.py`](src/mcpcloud/mcp.py) | Functions: `list_tools`, `call` |
| [`requirements.txt`](requirements.txt) | Implementation or supporting configuration |
| [`src/mcpcloud/__init__.py`](src/mcpcloud/__init__.py) | Implementation or supporting configuration |
| [`tests/test_mcp.py`](tests/test_mcp.py) | Executable checks and regression examples |
| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | GitHub Actions job definitions |
| [`README.md`](README.md) | Project explanations or operating notes |

### Local setup and verification

From the repository root (the commands follow the checked-in manifests):

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pytest -q
```

To serve the FastAPI application locally, install the server separately if it is not already available:

```bash
python -m pip install uvicorn
PYTHONPATH=src python -m uvicorn mcpcloud.main:app --reload
```

<!-- project-guide:end -->

Level: 10 — MCP & Tool-Using Agents

Skills: Python, cloud read tools

Tools: list_gke, describe_vm, get_billing. Apply refused.

```bash
pip install -r requirements.txt
pytest -q
```

This is a local laptop proof. It does not call a hosted model and it does not apply production changes.

## Ops plane

Workspaces, tenant isolation, job approval, and audit live under `/v1`. Production apply is refused. See `docs/ARCHITECTURE.md`.

## Documentation checks

Project architecture, interview guides, and local source links are checked automatically on pushes and pull requests. Run the same check locally:

```bash
python3 .github/scripts/validate_project_docs.py
```

See [service improvements and local run instructions](docs/UPGRADES.md).