aia-mcp

Servidor MCP (Model Context Protocol) que expone herramientas para el agente aia del proyecto hermano amanda-IA.

aia-mcp agrupa varios servidores MCP independientes (temperatura, Warhammer 40K, monitor de estanque, shell, Airbnb, charts, email, MangaDex, swagger) que el agente aia consume vía stdio o HTTP.

Estructura

aia-mcp/
├── README.md
├── pyproject.toml
├── Dockerfile                 # imagen keitarodxs/aia-mcp
├── docker-compose.yml         # despliegue en nara
├── mcp_cli/                   # CLI (entry point `mcp`) y registro de servidores
├── specs/                     # especificaciones (ej. SPEC_TEMPERATURA.md)
├── temperatura/  wahapedia/  monitor/  shell/  airbnb/
├── charts/  mcp_email/  mangadex/  swagger/
├── resources/mcp-ssh/         # config de mcp-ssh (no usado en la imagen)
└── tests/                     # tests unitarios (pytest)

Cada servidor MCP vive en su propio directorio y se registra en mcp_cli/cli.py (diccionario SERVERS). Ejecuta cualquiera con poetry run mcp <servidor>.

Requisitos

Python 3.11+
Poetry
(Opcional, para despliegue) Docker + un host con el self-hosted runner registrado

Instalación

cd aia-mcp
poetry install

Ejecutar servidores MCP

Desde el directorio aia-mcp/:

poetry run aia-mcp                    # temperatura (por defecto, stdio)
poetry run aia-mcp temperatura        # explícito
poetry run aia-mcp --list             # listar servidores disponibles

# Modo HTTP (para conexión remota / agente aia por red)
poetry run aia-mcp temperatura --http   # puerto 8001
poetry run aia-mcp all --http           # todos los servidores en paralelo

stdio (por defecto): para Cursor, Claude Desktop, etc.
HTTP (--http): servidor en http://0.0.0.0:<puerto>/mcp.

Puertos por servidor

Servidor	Puerto	Servidor	Puerto
temperatura	8001	airbnb	8006
wahapedia	8002	charts	8007
monitor	8003	email	8008
shell	8005	mangadex	8009
swagger	8010	drawio-mcp	3000/3333

drawio-mcp-server se instala dentro de la imagen Docker (no es un servidor MCP de este repo) y expone HTTP en :3000 + WebSocket de extensión en :3333.

Swagger UI (documentación de APIs)

poetry run mcp-swagger           # puerto 8010
# o
poetry run mcp swagger --http

Accede a: http://localhost:8010/

Conectar con el agente (Cursor / amanda-IA)

Configura el servidor MCP en Cursor o en el agente aia. Ejemplo para ~/.cursor/mcp.json:

{
  "mcpServers": {
    "temperatura": {
      "command": "poetry",
      "args": ["run", "mcp", "temperatura"],
      "cwd": "/ruta/a/aia-mcp"
    }
  }
}

Ajusta cwd a la ruta absoluta de tu proyecto aia-mcp.

Conectar aia por HTTP

Inicia el servidor MCP en modo HTTP: poetry run aia-mcp temperatura --http
En otra terminal, ejecuta el agente con la variable de entorno:
```
MCP_URL=http://localhost:8001/mcp poetry run aia
```

Añadir nuevos servidores: crea el directorio (ej. nuevo_servidor/), implementa el servidor con FastMCP, y regístralo en mcp_cli/cli.py en el diccionario SERVERS (sumando su puerto en SERVER_PORTS).

Despliegue (Docker)

El repo publica automáticamente la imagen keitarodxs/aia-mcp en Docker Hub al pushear un tag v*.*.* (workflow .github/workflows/docker-image.yml).

Local / servidor con Docker

deprecated?

docker compose pull
docker compose up -d

Esto levanta el contenedor aia-mcp con todos los puertos mapeados y los volúmenes logs/ y .aia/ montados. Carga las variables desde .env (ver .env.example).

Build de la imagen: el proyecto se sigue gestionando con Poetry (pyproject.toml + poetry.lock), pero dentro del Dockerfile las dependencias se instalan con uv (uv pip install --system) por velocidad. El poetry.lock se respeta vía poetry export a requirements.txt. La imagen parte de la base del ecosistema keitarodxs/aia-utils-base:v1.0.0 (Python 3.13, git, uv, Node 20 + drawio-mcp-server ya incluidos).

Tests

poetry install --with dev
poetry run pytest

Cobertura actual: wahapedia (slug/normalización/facciones) y airbnb (serialización MongoDB / formato iCal).

Tools disponibles

temperatura — `get_temperature`

Obtiene la temperatura actual de una ciudad (valores simulados).

Parámetro: city (string, opcional)
Retorno: String con la temperatura

Ciudades soportadas: Santiago, Buenos Aires, Lima, Bogotá, Madrid, New York, Londres, Tokio.

monitor — estanque / acumulador

get_lectura_actual(): litros y porcentaje en tiempo real vía MQTT (MQTT_HOST, MQTT_TOPIC_OUT) o TINAJA_ESTADO_URL como fallback.
calculate_tinaja_level(distance): litros/% desde la distancia del sensor (cm).
get_tinaja_config(): configuración del estanque y estado MQTT.
get_velocidad_disminucion_agua(db_name, horas_atras): velocidad de bajada (L/h) usando historial en MongoDB. Requiere MONGODB_URI.

Variables .env: MQTT_HOST, MQTT_PORT, MQTT_USERNAME, MQTT_PASSWORD, MQTT_TOPIC_OUT, TINAJA_ESTADO_URL, MONGODB_URI.

wahapedia — Warhammer 40K

get_unit_stats(query, faction) / search_wahapedia(query)
get_factions() / get_units(faction) / get_stratagems(faction)

Cache en disco configurable: WAHAPEDIA_CACHE_ENABLED, WAHAPEDIA_CACHE_DIR, WAHAPEDIA_CACHE_TTL_DAYS (por defecto deshabilitada; TTL 60 días).

airbnb — reservas y calendario (MongoDB)

get_proxima_reserva(), get_reservas_futuras(solo_futuras), get_calendario_mes_airbnb(mes, anio), get_ingresos_mes(mes, anio)

Requiere MONGODB_URI y AIRBNB_DB.

charts / email / mangadex / shell / swagger

charts: genera gráficos (matplotlib) desde datos de MongoDB.
email: consulta correo IMAP Yahoo (YAHOO_EMAIL, YAHOO_APP_PASSWORD).
mangadex: descarga/consulta mangas (AIA_MANGA_DIR).
shell: run_command(command, cwd) para ejecutar comandos desde el agente.
swagger: UI de documentación de APIs en :8010.

Release files for aia-mcp 1.8.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aia-mcp 1.8.5
File	Size	Uploaded
aia_mcp-1.8.5.tar.gz	64.1 kB	Jul 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aia-mcp 1.8.5
File	Interpreter	ABI	Platform	Reset
aia_mcp-1.8.5-py3-none-any.whl 71.6 kB Jul 30, 2026	Python 3	none	any	Details

Total release size: 135.7 kB

Release files / aia_mcp-1.8.5.tar.gz

Download URL	aia_mcp-1.8.5.tar.gz
Size	64.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`a6c2ec1d5aed185bd9c3f176f72247b6a2b9cd0c2edc3e26919cb0fdf66f4c16`
BLAKE2b-256 checksum How to use checksums	`a7923e565c8f773b2127ff3f59b8f919e20ff44ba1c5b60c09a87e37b78e16b7`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`

Release files / aia_mcp-1.8.5-py3-none-any.whl

Download URL	aia_mcp-1.8.5-py3-none-any.whl
Size	71.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e7978952077dae6381ec97b5726363d90537d1e04760d263e23f7f7c43609a51`
BLAKE2b-256 checksum How to use checksums	`f81a3c5343ba418c85d508caa9504e01a6db2757c381664aeb0325e6c7c83800`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`