Metadata-Version: 2.4
Name: aws-cost-mcp
Version: 1.0.0
Summary: MCP Server for AWS Cost Explorer — query costs, analyze EC2, detect anomalies, and generate cost reports
Project-URL: Homepage, https://github.com/nicolasdr/aws-cost-mcp
Project-URL: Repository, https://github.com/nicolasdr/aws-cost-mcp
License: MIT
Keywords: aws,cloud-costs,cost-explorer,finops,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: boto3>=1.34.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🐍 MCP Server Starter — Python / FastMCP

Plantilla lista para desarrollar servidores MCP en Python usando **FastMCP**, con soporte completo para probarlos localmente con **MCP Inspector** — ya sea via Docker o directamente en tu máquina.

---

## 📁 Estructura del proyecto

```
mcp-python-starter/
├── src/
│   ├── server.py              # Entry point — inicia el servidor (stdio o HTTP)
│   ├── constants.py           # Constantes globales (puerto, URL base, etc.)
│   ├── tools/
│   │   ├── hello.py           # Tools de ejemplo: hello_world, echo
│   │   └── calculator.py      # Tool de ejemplo: calculator
│   └── services/
│       └── api_client.py      # Cliente HTTP asíncrono reutilizable
├── Dockerfile                 # Imagen del servidor MCP
├── docker-compose.yml         # Servidor MCP + MCP Inspector (todo en Docker)
├── docker-compose.dev.yml     # Solo servidor con hot-reload
├── mcp.json                   # Config para MCP Inspector CLI y Claude Code
├── .env.example               # Variables de entorno de ejemplo
└── pyproject.toml             # Dependencias del proyecto
```

---

## 🚀 Inicio rápido

### Opción A — Todo en Docker (recomendado para probar rápido)

Levanta el servidor MCP **y** el MCP Inspector en un solo comando:

```bash
cp .env.example .env
docker compose up --build
```

Luego abre **http://localhost:6274** en el browser.

En el Inspector:
1. Transport → **Streamable HTTP**
2. URL → `http://mcp-server:8000/mcp`  *(dentro de Docker usa el nombre del servicio)*
3. Click **Connect**
4. Ve a la pestaña **Tools** → **List Tools**

> ⚠️ Si corres el Inspector en el **host** (no en Docker), usa `http://localhost:8000/mcp` como URL.

---

### Opción B — Servidor en Docker + Inspector en el host

```bash
# Terminal 1 — levantar solo el servidor
docker compose -f docker-compose.dev.yml up --build

# Terminal 2 — abrir el Inspector en tu máquina (abre browser automáticamente)
npx @modelcontextprotocol/inspector
```

En el Inspector: Transport → **Streamable HTTP** → URL → `http://localhost:8000/mcp`

---

### Opción C — Sin Docker (virtualenv local)

```bash
# Crear entorno virtual e instalar dependencias
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .

# Modo HTTP (para MCP Inspector)
TRANSPORT=http python -m src.server

# En otra terminal — abrir el Inspector
npx @modelcontextprotocol/inspector
# → Connect: Streamable HTTP → http://localhost:8000/mcp
```

---

## 🧪 Probar con MCP Inspector CLI

Sin browser, desde la terminal:

```bash
# Listar todas las tools disponibles
npx @modelcontextprotocol/inspector --cli \
  --config mcp.json --server my-mcp-server-stdio \
  --method tools/list

# Llamar hello_world
npx @modelcontextprotocol/inspector --cli \
  --config mcp.json --server my-mcp-server-stdio \
  --method tools/call --tool-name hello_world \
  --tool-arg 'params={"name": "Mundo", "language": "es"}'

# Llamar calculator
npx @modelcontextprotocol/inspector --cli \
  --config mcp.json --server my-mcp-server-stdio \
  --method tools/call --tool-name calculator \
  --tool-arg 'params={"a": 10, "b": 3, "operation": "divide"}'
```

---

## ➕ Agregar una nueva tool

1. Crea `src/tools/mi_tool.py`:

```python
import json
from mcp.server.fastmcp import Context, FastMCP
from pydantic import BaseModel, ConfigDict, Field

class MiInput(BaseModel):
    model_config = ConfigDict(extra="forbid")
    param: str = Field(..., description="Descripción del parámetro")

def register_mi_tools(mcp: FastMCP) -> None:
    @mcp.tool(
        name="mi_tool",
        annotations={
            "title": "Mi Tool",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        },
    )
    async def mi_tool(params: MiInput, ctx: Context) -> str:
        """Descripción de la tool — FastMCP la usa como 'description'.

        Args:
            params (MiInput):
                - param (str): Descripción del parámetro

        Returns:
            str: Resultado de la operación.
        """
        await ctx.log_info("mi_tool llamado", {"param": params.param})
        result = {"resultado": f"Procesado: {params.param}"}
        return json.dumps(result, ensure_ascii=False, indent=2)
```

2. Regístrala en `src/server.py`:

```python
from src.tools.mi_tool import register_mi_tools
# ...
register_mi_tools(mcp)
```

3. Prueba sin reconstruir (hot-reload activo con `docker-compose.dev.yml`).

---

## 🔌 Transportes disponibles

| Transporte | Cómo activar | Cuándo usar |
|---|---|---|
| **stdio** | `TRANSPORT=stdio python -m src.server` | Claude Code, Cursor, integración local |
| **HTTP** | `TRANSPORT=http python -m src.server` | MCP Inspector web, servidores remotos |

---

## 🔗 Conectar a Claude Code

```bash
# Agregar el servidor (modo stdio)
claude mcp add my-mcp-server python -m src.server

# O editar ~/.claude/mcp.json con la entrada de mcp.json de este repo
```

---

## ⚙️ Variables de entorno

| Variable | Default | Descripción |
|---|---|---|
| `TRANSPORT` | `stdio` | `stdio` o `http` |
| `PORT` | `8000` | Puerto del servidor HTTP |
| `API_BASE_URL` | `https://api.example.com` | URL base de tu API |
| `API_TOKEN` | *(vacío)* | Token Bearer para tu API |

---

## 🛠️ Características del starter

- ✅ **FastMCP** con `@mcp.tool` decorators
- ✅ **Pydantic v2** para validación de inputs
- ✅ **async/await** en todas las tools (con `httpx.AsyncClient`)
- ✅ **Context injection** para logging y progress reporting
- ✅ **Lifespan management** para recursos compartidos (DB, caché, etc.)
- ✅ **Doble transporte**: stdio y Streamable HTTP
- ✅ **Docker** con multi-stage build
- ✅ **Hot-reload** en modo desarrollo
- ✅ **MCP Inspector** integrado en Docker Compose

---

## 📚 Referencias

- [FastMCP Docs](https://gofastmcp.com)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
- [MCP Protocol Docs](https://modelcontextprotocol.io)
