Adventure Forge Conversation MCP

Adventure Forge Conversation MCP API

Este proyecto es un microservicio HTTP basado en FastAPI que expone un endpoint para generar conversaciones en el formato de Adventure Forge utilizando el modelo Gemini de Google (vía langchain-google-genai).

Descripción general

• Expone un endpoint POST /create-conversation que recibe un texto de entrada (input) y devuelve una conversación en el formato de Adventure Forge.
• Utiliza langchain y ChatGoogleGenerativeAI para orquestar el LLM de Gemini.
• Usa prompting estructurado con un contexto (formato_conversacion) y un ejemplo (ejemplo_conversacion) para forzar el formato de salida.
• Se despliega habitualmente en contenedor Docker y puede orquestarse con docker-compose.

Arquitectura

Componentes principales

• main.py

- Inicializa la aplicación FastAPI (app). - Define el modelo de entrada RequestBody con el campo input: str. - Carga variables de entorno mediante python-dotenv (se espera GOOGLE_API_KEY). - Configura el endpoint POST /create-conversation decorado con @traceable de langsmith. - Dentro del endpoint: - Construye un ChatPromptTemplate con: - question: texto de entrada del usuario. - context: formato_conversacion desde helpers.py. - example: ejemplo_conversacion desde helpers.py. - Instancia ChatGoogleGenerativeAI con el modelo gemini-2.5-flash y parámetros de temperatura y longitud máxima. - Invoca el LLM y devuelve un JSON con la clave conversation que contiene el texto generado.

• helpers.py

- Define formato_conversacion: documentación detallada del formato Adventure Forge (tipos de nodos, cabeceras, enlaces, respuestas, escritura rápida, etc.). - Define ejemplo_conversacion: ejemplo completo de una conversación en formato Adventure Forge que sirve de guía al modelo.

Dependencias clave

Definidas en requirements.txt:

• fastapi[standard] y uvicorn[standard]: framework web y servidor ASGI.
• python-dotenv: carga de variables de entorno desde .env.
• google-genai: SDK de Gemini.
• langchain-core, langchain-google-genai: integración de LangChain con Gemini.
• langsmith: trazabilidad y observabilidad del flujo (utilizado con el decorador @traceable).

Flujo de petición

1. El cliente realiza una petición POST a /create-conversation con cuerpo JSON:

   {
     "input": "Tema o descripción de la escena"
   }

1. El servicio construye un prompt usando:

- El tema proporcionado (input). - El contexto de formato (formato_conversacion). - Un ejemplo de referencia (ejemplo_conversacion).

1. El LLM Gemini genera un texto siguiendo el formato Adventure Forge.
2. La respuesta se devuelve como:

   {
     "conversation": "=P= Intro ==\n..."
   }

Despliegue y ejecución

Variables de entorno

Crear un archivo .env en la raíz del proyecto con al menos:

GOOGLE_API_KEY=tu_api_key_de_gemini

Ejecución local (sin Docker)

Requisitos: Python 3.11

cd mcp-api
python -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

La API quedará disponible en http://localhost:8000.

Ejecución con Docker

Construir la imagen y levantar el servicio con Docker Compose:

docker compose build
docker compose up -d

El servicio expone el puerto 8000 configurado en docker-compose.yml.

Uso del endpoint

Ejemplo de petición con curl:

curl -X POST "http://localhost:8000/create-conversation" ^
  -H "Content-Type: application/json" ^
  -d "{\"input\": \"Un encuentro misterioso en el bosque\"}"

Respuesta esperada (estructura general):

{
  "conversation": "=P= Intro ==\n..."
}

Manejo de errores

• Si ocurre una excepción al invocar el LLM, el endpoint devuelve un mensaje de error en texto plano con información básica del fallo.

Extensiones futuras

• Agregar más endpoints para otros tipos de contenido de Adventure Forge (por ejemplo, nodos de decisión avanzados o árboles de diálogo complejos).
• Internacionalización del prompt y del formato de ejemplo.
• Validación automática del formato generado antes de responder.