init: add README.md with detailed instructions

README.md

@@ -1,3 +1,84 @@
-# gitea-mcp-adapter
+# Gitea MCP Adapter 🦊🔌
 
-MCP adapter for Gitea API REST
+Un proxy ligero que envuelve la API REST de **Gitea** como un servidor de **Model Context Protocol (MCP)** compatible con la especificación **Agent-to-Agent (A2A)** de **Capataz**.
+
+Permite que cualquier agente de IA o cliente compatible con MCP interactúe directamente con tu instancia de Gitea (listar issues, commits, estados de CI/CD, crear comentarios, PRs, etc.) usando lenguaje natural.
+
+---
+
+## 🚀 Características
+
+- **Tarjeta de Agente (A2A Manifest):** Expuesta en `/.well-known/agent.json` con URLs dinámicas basadas en la petición.
+- **Servidor MCP nativo:** Soporta el transporte estándar de SSE (Server-Sent Events) sobre HTTP.
+- **Herramientas (Tools) incluidas:**
+  - `issues_abiertos`: Listar issues abiertos con filtros opcionales de etiquetas.
+  - `commits_recientes`: Listar los últimos commits de cualquier rama.
+  - `estado_actions`: Consultar el estado de las ejecuciones de Gitea Actions (CI/CD).
+  - `crear_issue`: Crear un issue con etiquetas.
+  - `comentar_issue`: Añadir comentarios a issues existentes.
+  - `crear_pull_request`: Crear un nuevo PR entre ramas.
+- **Autenticación flexible:** Soporta configuración global mediante variable de entorno o paso de token dinámico mediante cabecera `Authorization: Bearer <token_de_gitea>`.
+
+---
+
+## 🛠️ Configuración y Variables de Entorno
+
+Crea un archivo `.env` basado en `.env.example`:
+
+```bash
+# URL de tu instancia de Gitea
+GITEA_URL=https://git.carmona.digital
+
+# Token de acceso personal de Gitea (opcional si usas cabeceras dinámicas)
+GITEA_TOKEN=tu_token_de_gitea
+
+# Configuración del servidor
+PORT=8000
+HOST=0.0.0.0
+```
+
+---
+
+## 📦 Ejecución Local
+
+### Con Python
+
+1. Instala las dependencias:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Inicia el servidor:
+   ```bash
+   python main.py
+   ```
+
+El adaptador estará disponible en `http://localhost:8000`.
+
+### Con Docker
+
+1. Construye la imagen:
+   ```bash
+   docker build -t gitea-mcp-adapter .
+   ```
+
+2. Ejecuta el contenedor:
+   ```bash
+   docker run -d -p 8000:8000 --env-file .env gitea-mcp-adapter
+   ```
+
+---
+
+## 🔌 Integración con Capataz (A2A)
+
+Para registrar este adaptador en **Capataz**, simplemente añade la URL de despliegue en la interfaz de Capataz (ej. `https://gitea-mcp-adapter.estamos.com.ar`).
+
+Capataz leerá automáticamente:
+1. `/.well-known/agent.json` para descubrir las capacidades y skills del adaptador.
+2. Se conectará al endpoint MCP en `/mcp/sse` para interactuar con las herramientas.
+
+---
+
+## 📝 Licencia
+
+MIT - Libre para usar en cualquier instalación de Gitea y ecosistemas agénticos.