Open Conjugator MCP

MCP de solo lectura e independiente de Reverso para análisis y conjugación verbal. El árabe es la prioridad: usa CAMeL Tools 1.6.0 como motor y la base abierta CAMeL Morph MSA v1.0. Español, inglés y francés se resuelven con instantáneas fijadas de UniMorph.

No consulta Reverso, no hace scraping y no necesita red durante una consulta. Los datos se descargan una sola vez durante la preparación o construcción del contenedor, se verifican por SHA-256 y quedan locales.

Herramientas MCP

Todas las herramientas son idempotentes, no destructivas y devuelven JSON estructurado con sources, sourceUrl, retrievedAt y provenance.

Related MCP server: seerah-kb

Cobertura

• ar / ara: árabe estándar moderno, análisis y generación con CAMeL Morph/CAMeL Tools; raíz, patrón, voz activa/pasiva, perfecto, imperfecto, imperativo, modos y Buckwalter.

• es / spa: español mediante UniMorph.

• en / eng: inglés mediante UniMorph.

• fr / fra: francés mediante UniMorph.

También acepta nombres como árabe, Arabic, español, English o français.

Ejemplo abreviado:

{
  "query": {"original": "يَكْتُبُونَ", "resolved": "يَكْتُبُونَ"},
  "canonicalVerb": "كَتَب",
  "model": {
    "root": "ك.ت.ب",
    "pattern": "1َ2َ3",
    "patternAbstract": "1َ2َ3"
  },
  "candidateLemmas": ["كَتَب", "أَكْتَب"]
}

Las ḥarakāt, shadda, sukūn, hamza, alif maqṣūra, tāʾ marbūṭa y el orden RTL se conservan en toda salida. Solo la clave interna de búsqueda puede ignorar diacríticos; nunca se sustituye el texto devuelto.

Arquitectura

ChatGPT / Work / Codex
          │ Streamable HTTP o STDIO
          ▼
  seis herramientas MCP 2.x
          │
          ├── árabe → CAMeL Tools → CAMeL Morph MSA v1.0 (DB local)
          └── es/en/fr → índice SQLite de verbos UniMorph (local)

• El endpoint remoto usa Streamable HTTP sin estado.

• La base UniMorph se indexa por lema y forma; no se carga el corpus completo en memoria.

• El motor árabe se carga de forma perezosa y las consultas repetidas se almacenan en caché LRU.

• No hay cookies, cuentas, credenciales ni llamadas lingüísticas salientes en runtime.

• La concurrencia del analizador/generador se serializa para proteger las estructuras internas de CAMeL Tools.

Instalación local

Requiere Python 3.11 o superior.

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e '.[test]'
.venv/bin/pip install --no-deps -r requirements-morphology.txt
.venv/bin/python scripts/prepare_data.py

La instalación deliberadamente ligera evita descargar los modelos de IA de CAMeL Tools que no intervienen en morfología. Solo se instalan el paquete oficial y las dependencias que requieren el analizador, el generador y la transliteración.

STDIO

PYTHONPATH=src .venv/bin/python -m open_conjugator_mcp --transport stdio

Streamable HTTP local

PYTHONPATH=src PORT=3000 MCP_PATH=/api/open-conjugator-mcp \
  .venv/bin/python -m open_conjugator_mcp --transport http

• MCP: http://127.0.0.1:3000/api/open-conjugator-mcp

• Salud: http://127.0.0.1:3000/health

Pruebas

PYTHONPATH=src .venv/bin/pytest

La batería cubre las siete entradas árabes solicitadas (كتب, كَتَبَ, يَكْتُبُونَ, قال, رأى, استمر, kataba), ambigüedad, Unicode, raíces y patrones; además de hablar, write, parler, las seis herramientas mediante un cliente MCP STDIO y una llamada real por Streamable HTTP.

Contenedor y despliegue

docker build -t open-conjugator-mcp .
docker run --rm -p 3000:3000 open-conjugator-mcp

render.yaml describe un servicio Docker sin secretos. En Render puede crearse como Blueprint después de subir este repositorio. La ruta pública final será:

https://SU-SERVICIO.onrender.com/api/open-conjugator-mcp

Producción necesita una URL HTTPS estable y accesible. Esta forma sigue la guía oficial de servidores MCP de OpenAI, que recomienda Streamable HTTP y probar todas las herramientas con MCP Inspector.

ChatGPT y ChatGPT Work

1. Abra Settings → Plugins / Developer mode; en Work, el administrador debe permitir plugins y herramientas MCP.

2. Pulse + en el directorio de plugins, cree una app MCP e introduzca la URL HTTPS completa.

3. Confirme las seis herramientas detectadas y pruebe identify_verb_form con يَكْتُبُونَ.

ChatGPT web y Work necesitan el endpoint HTTPS; no pueden abrir el proceso STDIO de este ordenador. La arquitectura de plugins compartida por ChatGPT y Codex se describe en la documentación oficial.

Codex

Instalación remota:

codex mcp add open-conjugator --url https://SU-SERVICIO.onrender.com/api/open-conjugator-mcp

Instalación local en este proyecto:

codex mcp add open-conjugator -- \
  /RUTA/AL/PROYECTO/.venv/bin/python \
  -m open_conjugator_mcp --transport stdio

Para STDIO, configure también PYTHONPATH=/RUTA/AL/PROYECTO/src si el paquete no se instaló con pip install -e .. Codex CLI, la app y la extensión comparten su configuración MCP.

Procedencia y licencias

• CAMeL Tools: MIT.

• CAMeL Morph: código MIT; base MSA v1.0 bajo CC BY 4.0.

• UniMorph: las instantáneas eng, spa y fra usadas aquí son CC BY-SA 3.0.

Los commits y hashes exactos están en scripts/prepare_data.py; consulte también THIRD_PARTY_NOTICES.md. El código del MCP es MIT. La base SQLite derivada de UniMorph conserva CC BY-SA 3.0.

Limitaciones

• CAMeL Morph analiza fuera de contexto: una misma grafía puede tener varios lemas o lecturas. El MCP devuelve esa ambigüedad en vez de fingir una única certeza.

• La transliteración aceptada y devuelta para árabe es Buckwalter; kataba funciona, pero no se pretende reconocer cualquier convención latina informal.

• CAMeL Morph no etiqueta directamente cada lema con el número tradicional de wazn. Se devuelven raíz, patrón y patrón abstracto reales; no se inventa el número.

• Los participios árabes se modelan como entradas nominales separadas y no se atribuyen automáticamente a un verbo sin evidencia explícita.

• UniMorph ofrece tablas y rasgos, no explicaciones prescriptivas ni nombres de “modelos” como un conjugador pedagógico.

• Solo se empaquetan español, inglés y francés como cobertura secundaria para mantener una imagen remota razonable.

Solución de problemas

• Faltan bases de datos: ejecute .venv/bin/python scripts/prepare_data.py.

• El primer arranque árabe tarda: la base CAMeL Morph se carga de forma perezosa una vez por proceso.

• ChatGPT no conecta: compruebe /health, HTTPS público y la ruta exacta /api/open-conjugator-mcp.

• Codex no muestra herramientas: ejecute codex mcp list y reinicie el cliente después de añadir el servidor.

• Resultado árabe ambiguo: use los campos candidateLemmas, matches y rawFeatures; es un resultado lingüístico válido, no un fallo.