Perseus-mcp

Servidor MCP para la Biblioteca Digital Perseus — que brinda a los modelos de IA acceso directo a textos griegos antiguos, pasajes CTS y búsqueda en Scaife.

GitHub

Documentación

Perseus-mcp

Dale a Claude / Cursor / Windsurf acceso directo a la Biblioteca Digital Perseus — textos antiguos en griego y latín, navegación CTS precisa, texto plano, búsqueda y más.

Un servidor MCP de alta calidad para literatura clásica griega y latina. Se ejecuta como un servidor FastMCP local para que las aplicaciones compatibles con MCP puedan adjuntar estas herramientas de Perseus al proveedor de LLM/modelo de tu elección.

Características

Este servidor expone veintitrés herramientas MCP. Cada herramienta devuelve un payload de texto: algunas son XML CTS crudo de Perseus o JSON de Scaife, mientras que los asistentes de descubrimiento y texto plano devuelven JSON con formato local o texto legible.

get_passage(urn) — obtiene un pasaje CTS por URN.
get_passage_plus(urn) — obtiene el texto del pasaje más metadatos contextuales.
get_passage_plaintext(urn) — obtiene un pasaje CTS como texto plano legible.
get_valid_references(urn, level=None) — recupera referencias de citas navegables para una obra o edición.
get_valid_references_json(urn, level=None, limit=100, offset=0) — recupera referencias de citas paginadas como JSON (limit: 1–500).
count_valid_references(urn, level=None) — cuenta referencias válidas sin devolver la lista completa.
get_capabilities() — lista textos/ediciones disponibles de Perseus CTS.
get_cache_status() — inspecciona el estado de la caché de metadatos local.
refresh_metadata_cache() — actualiza los metadatos de la biblioteca CTS y Scaife en caché.
clear_metadata_cache() — limpia las entradas de la caché de metadatos en memoria y en disco.
list_text_groups(language=None, query=None, limit=100, offset=0) — lista autores/grupos de texto y obras coincidentes con metadatos de paginación (limit: 1–500).
get_author_resources(author, language=None) — lista obras, ediciones y traducciones para un nombre de autor o URN de grupo de texto CTS coincidente.
find_author_names(query, language=None, limit=100, offset=0) — encuentra nombres de autores/grupos de texto por coincidencia parcial de nombre con metadatos de paginación (limit: 1–500).
get_work_resources(urn_or_title, language=None) — lista ediciones, traducciones y recursos para una obra, opcionalmente filtrados por idioma original.
get_label(urn) — obtiene etiquetas de metadatos legibles para una URN.
get_first_urn(urn) — obtiene la primera URN navegable bajo una obra/edición.
get_prev_next_urn(urn) — obtiene URNs de pasajes vecinos para navegación.
search_perseus(query, language="greek", query_format="auto", author=None, search_kind="form", preserve_operators=False, page_num=1, text_group=None, work=None, result_format="instances") — busca textos a través de la API de búsqueda de Scaife. Las consultas en griego pueden ingresarse como Unicode griego (por ejemplo, μῆνιν) o Beta Code (por ejemplo, mh=nin).
search_within_text(query, text_urn, ..., size=10, offset=0) — busca dentro de una URN de texto/edición de Scaife (size: 1–500).
get_passage_highlights(query, passage_urn, ...) — obtiene posiciones de resaltado de tokens de Scaife para un pasaje.
get_scaife_library_metadata(urn) — obtiene metadatos JSON de Scaife para una URN de biblioteca.
get_scaife_passage_json(urn) — obtiene JSON de Scaife para una URN de pasaje.
get_scaife_passage_text(urn) — obtiene texto plano de Scaife para una URN de pasaje.

Entrada de búsqueda en griego

search_perseus normaliza los términos de búsqueda antes de enviarlos a la ruta de búsqueda JSON de Scaife. Las consultas deben contener al menos un carácter que no sea espacio en blanco. La herramienta devuelve la respuesta JSON de Scaife como texto.

Entrada	Valores aceptados	Comportamiento
`query`	Griego Unicode, como `μῆνιν`, o Beta Code, como `mh=nin a)/eide`	Normalizado a griego Unicode compuesto (NFC) antes de buscar.
`query_format`	`"auto"` (predeterminado), `"betacode"` o `"unicode"`	`auto` reconoce marcas de Beta Code como `=`, `/`, `(`, `)` y `*`, y términos cortos sin acentos que parecen griego como `logos`. Usa un formato explícito para entrada ASCII ambigua.
`language`	Aliases en griego: `greek`, `grc`, `gr`; aliases en latín: `latin`, `lat`, `la`	Controla la normalización de consultas, no el filtrado del corpus de Scaife. La entrada en blanco usa griego por defecto; los valores no reconocidos generan un error.
`search_kind`	`"form"` (predeterminado) o `"lemma"`	Busca formas flexionadas o lemas de diccionario.
`preserve_operators`	`False` (predeterminado) o `True`	Establécelo en `True` para frases entre comillas u operadores como `-`, `\|`, `*` y `~`, evitando que la detección de Beta Code los consuma.
`author`	Nombre de autor/grupo de texto CTS o URN	Una coincidencia única se convierte en un filtro `text_group` del lado del servidor. Las coincidencias ambiguas usan filtrado local por prefijo de URN CTS en la página devuelta.
`text_group`, `work`	URNs de alcance de Scaife	Aplica filtros de alcance del lado del servidor directamente.
`page_num`	Número de página	Selecciona la página de resultados.

Ejemplos de consultas con operadores:

search_perseus(
    '"μῆνιν ἄειδε"',
    query_format="unicode",
    preserve_operators=True,
)

search_perseus(
    "μῆνιν -ἄειδε",
    query_format="unicode",
    preserve_operators=True,
)

search_perseus(
    "λόγος | ἀνήρ",
    search_kind="lemma",
    query_format="unicode",
    preserve_operators=True,
)

Para el descubrimiento de inventario, list_text_groups, find_author_names, get_author_resources y get_work_resources tratan language como un filtro real de idioma de obra. find_author_names fusiona el inventario CTS heredado con el catálogo de la biblioteca de Scaife, por lo que los autores solo disponibles en Scaife, como Filón de Alejandría, siguen siendo descubribles. Las herramientas de pasaje y navegación usan URNs CTS, cuyo espacio de nombres greekLit/latinLit e identificador de edición ya seleccionan el texto.

Caché de metadatos local

Las herramientas de descubrimiento y navegación almacenan en caché metadatos CTS estables localmente para evitar solicitudes repetidas de varios megabytes a GetCapabilities y GetValidReff. La caché en disco predeterminada vive en .cache/perseus-mcp bajo el directorio de trabajo actual y también usa una caché en memoria para el proceso del servidor en ejecución. Configúrala con:

PERSEUS_MCP_CACHE_DIR — sobrescribe el directorio de caché en disco.
PERSEUS_MCP_CACHE_TTL_SECONDS — establece el TTL de la caché; el valor predeterminado es 86400 segundos.
PERSEUS_MCP_DISABLE_CACHE=1 — deshabilita las lecturas/escrituras de caché en memoria y en disco.

El directorio de trabajo actual es el directorio desde el que se inicia el proceso de Python. Ejecutar el servidor MCP desde la raíz del repositorio usa .cache/perseus-mcp; ejecutar un notebook desde examples/ usaría de otro modo examples/.cache/perseus-mcp. Eso no es una segunda instancia del servidor, solo una segunda ubicación de caché para un proceso de Python separado. Para mantener una ubicación de caché entre notebooks y clientes MCP, establece PERSEUS_MCP_CACHE_DIR a una ruta absoluta como /path/to/Perseus-mcp/.cache/perseus-mcp. Las entradas en disco se escriben en archivos temporales hermanos únicos y se reemplazan atómicamente, por lo que múltiples procesos locales pueden compartir ese directorio de forma segura sin exponer archivos de caché parcialmente escritos. Los fallos de escritura de la caché en disco emiten un MetadataCacheWarning pero no descartan una respuesta ascendente obtenida con éxito.

Descubrimiento de URN

Las URNs de edición disponibles pueden diferir entre los resultados de búsqueda de Perseus CTS y Scaife, y el inventario en vivo puede cambiar. Usa get_author_resources, get_work_resources o list_text_groups antes de construir URNs de pasaje CTS específicas de edición. Los notebooks seleccionan ediciones CTS anunciadas de los resultados de descubrimiento en lugar de asumir que una URN de edición de Scaife es válida para Perseus CTS.

La implementación en vivo de Perseus CTS puede devolver HTML malformado para GetFirstUrn y GetPrevNextUrn. Las herramientas MCP detectan esa respuesta y derivan resultados XML válidos de GetValidReff.

Perseus también puede devolver 429 Too Many Requests cuando un flujo de trabajo envía muchas solicitudes CTS en un período corto. Pausa antes de reintentar, reduce la concurrencia y agrega demoras a los bucles de procesamiento de pasajes. El servidor actualmente expone el error HTTP ascendente en lugar de reintentar automáticamente.

Configuración

1) Instalar dependencias

Usando uv:

uv sync

O con pip:

pip install -e .

Una vez que se publique una versión en PyPI, los usuarios pueden instalarla sin clonar el repositorio:

pip install perseus-mcp

Para desarrollo y pruebas:

pip install -e ".[dev]"

2) Ejecutar pruebas

pytest

Con uv, usa:

uv run --extra dev pytest

3) Ejecutar localmente

uv run perseus-mcp

El comando de consola instalado y el punto de entrada del módulo son equivalentes:

perseus-mcp
python -m perseus_mcp

4) Inspeccionar herramientas (opcional)

npx @modelcontextprotocol/inspector uv run perseus-mcp

Estrategia de pruebas y automatización

Perseus MCP usa verificaciones en capas en lugar de depender de una sola prueba de extremo a extremo. La mayoría del comportamiento está cubierto por pruebas pytest deterministas con fixtures XML/JSON locales y llamadas HTTP asíncronas simuladas. GitHub Actions verifica por separado la matriz de Python y sistemas operativos compatibles, artefactos de paquetes, secretos, etiquetas de versiones y publicación.

Los archivos de flujo de trabajo bajo .github/workflows/ son la fuente ejecutable de verdad.

Organización del conjunto de pruebas

Pytest está configurado en pyproject.toml para importar desde src/ y descubrir pruebas bajo tests/.

Módulo de prueba	Responsabilidad principal
`test_author_resources.py`	Análisis de autor, obra y recursos CTS; comportamiento de autor fusionado
`test_disk_cache.py`	Escrituras atómicas de caché, deshabilitación de caché, limpieza y escritores concurrentes
`test_exploration_tools.py`	Descubrimiento, navegación, herramientas de caché, alcance de autor y respuestas estructuradas
`test_greek_query_normalization.py`	Griego Unicode, Beta Code, parámetros de Scaife y operadores de búsqueda
`test_limits_and_language.py`	Límites de resultados, límites de paginación y aliases de idioma
`test_packaging.py`	Metadatos, dependencias, activos de documentación, notebooks y expectativas de flujo de trabajo
`test_scaife_urls.py`	Construcción segura de URL y codificación porcentual de URN CTS
`test_shared_http_client.py`	Reutilización de conexiones, cambios de bucle de eventos, apagado y errores HTTP
`test_xml_hardening.py`	Análisis XML seguro y rechazo de ataques XML basados en entidades

Una corrección de regresión debe incluir una prueba enfocada que falle para el problema original. Las pruebas deben afirmar el comportamiento observable y cubrir rutas de fallo y valores límite, así como llamadas exitosas.

Aislamiento de Perseus y Scaife

Las pruebas rutinarias no dependen de servicios ascendentes en vivo. Los ayudantes HTTP se monkeypatchean con dobles de prueba asíncronos, mientras que XML CTS representativo y JSON de Scaife se almacenan en fixtures de prueba. Esto mantiene CI determinista cuando los catálogos cambian o un servicio ascendente no está disponible, evita tráfico innecesario a infraestructura académica pública y hace seguras las pruebas de respuestas malformadas.

Se pueden usar sondas de solo lectura en vivo durante la revisión manual para la compatibilidad de endpoints o cambios en el ciclo de vida de la conexión, pero complementan en lugar de reemplazar el conjunto automatizado.

Limpieza de pruebas asíncronas

Varias pruebas invocan herramientas con asyncio.run(), lo que crea un nuevo bucle de eventos para cada llamada. El servidor usa un httpx.AsyncClient compartido a nivel de proceso, por lo que el fixture autouse en tests/conftest.py cierra y restablece ese cliente después de cada prueba. Las pruebas que manipulan el estado compartido del cliente también deben dejarlo restablecido.

Comandos de prueba locales

Ejecuta el conjunto completo:

python -m pytest

Ejecuta un módulo o una prueba:

python -m pytest tests/test_disk_cache.py
python -m pytest tests/test_disk_cache.py::test_disk_cache_set_writes_readable_content

Muestra pruebas omitidas, las más lentas y variables locales en caso de fallo:

python -m pytest -ra --durations=10 -l

Deshabilita lecturas y escrituras de caché de metadatos durante una ejecución de prueba:

PERSEUS_MCP_DISABLE_CACHE=1 python -m pytest

Equivalente en PowerShell:

$env:PERSEUS_MCP_DISABLE_CACHE = "1"
python -m pytest

Matriz de pruebas de GitHub Actions

.github/workflows/tests.yml instala el proyecto editable con dependencias de desarrollo y ejecuta python -m pytest en:

Ubuntu y Windows;
Python 3.11, 3.12 y 3.13.

La matriz usa fail-fast: false, por lo que cada trabajo de plataforma/versión termina incluso cuando uno falla. Esto hace visibles las regresiones específicas de versión y de Windows en una sola ejecución. Los cambios solo de documentación bajo docs/** se excluyen del flujo de trabajo de pruebas de Python; los filtros exactos de eventos y ramas permanecen definidos en el archivo de flujo de trabajo.

Validación de paquetes

.github/workflows/package.yml verifica que el repositorio produzca una distribución de código fuente válida y una rueda universal. Instala Python 3.12, ejecuta:

python -m build
python -m twine check dist/*

y sube dist/ como el artefacto del flujo de trabajo python-package. El flujo de trabajo está filtrado por ruta a archivos relevantes del paquete y admite despacho manual.

tests/test_packaging.py complementa esta compilación verificando expectativas a nivel de repositorio como metadatos, dependencias, archivos de documentación, JSON de notebooks y configuración de flujo de trabajo. Ambas capas importan: las pruebas de metadatos pueden pasar mientras una compilación aislada falla, y un paquete puede compilarse mientras faltan activos requeridos del repositorio.

Escaneo de secretos

.github/workflows/secret-scan.yml rechaza claves de OpenRouter rastreadas que coincidan con:

sk-or-v1-[A-Za-z0-9_-]{20,}

El flujo de trabajo informa los archivos afectados sin imprimir el secreto coincidente. Una clave detectada debe ser eliminada y rotada; la verificación nunca debe ser omitida. Este escaneo enfocado no reemplaza la higiene normal de credenciales: no confirmes archivos .env, tokens, configuración privada de MCP, o salidas de notebooks que contengan credenciales.

Seguridad de código y dependencias

.github/workflows/codeql.yml analiza tanto el código fuente de Python como los flujos de trabajo de GitHub Actions en los envíos a main y development, en solicitudes de extracción, y semanalmente. El análisis de Python utiliza el conjunto de consultas de seguridad y calidad de CodeQL, mientras que el análisis de flujos de trabajo utiliza el conjunto de seguridad extendida. El flujo de trabajo también admite el envío manual para verificaciones de configuración.

.github/workflows/dependency-review.yml se ejecuta en cada solicitud de extracción y falla cuando una dependencia modificada introduce una vulnerabilidad conocida de gravedad moderada o superior. Dependabot verifica tanto las dependencias de Python como las de GitHub Actions semanalmente. Sus etiquetas predeterminadas se utilizan intencionalmente para que las solicitudes de extracción de actualización no dependan de etiquetas específicas del repositorio creadas previamente.

Puertas de publicación y lanzamiento

.github/workflows/release.yml se ejecuta para etiquetas v* o envío manual. Para ejecuciones de etiquetas, verifica que la etiqueta sea igual a v<project.version>, compila la rueda y el archivo fuente, valida ambos con Twine, los adjunta a una versión de GitHub generada, y envía el flujo de trabajo de PyPI usando la misma etiqueta.

.github/workflows/publish.yml requiere una referencia de etiqueta, repite la verificación de etiqueta/versión, reconstruye y revalida los artefactos, y publica a través de la publicación confiable de PyPI. El entorno protegido de GitHub pypi utiliza OIDC (id-token: write), por lo que no se almacena ningún token de API de PyPI de larga duración.

Reconstruir durante la publicación evita confiar en un artefacto de flujo de trabajo no relacionado, mientras que la verificación repetida de etiquetas evita publicar desde una rama o una etiqueta de versión no coincidente.

Despliegue de documentación

.github/workflows/pages.yml compila docs/ con Jekyll y despliega el artefacto generado en GitHub Pages después de que los cambios de documentación lleguen a main o master. Este sitio de Pages está destinado principalmente a usuarios finales; la documentación de desarrollo y estrategia de pruebas vive en el README de este repositorio. Las solicitudes de extracción que cambian la documentación o el flujo de trabajo de Pages también compilan el sitio para validación, sin desplegarlo. Previsualiza el sitio generado en lugar de abrir docs/index.html directamente: la página de inicio ahora comparte el diseño de Jekyll utilizado por las otras páginas.

Interpretación de fallos

Fallos en cada trabajo de matriz generalmente indican una regresión general.
Un fallo de una sola versión de Python sugiere sintaxis, dependencias o comportamiento de la biblioteca estándar específicos de la versión.
Los fallos solo en Windows comúnmente involucran rutas, permisos, atributos de solo lectura o el ciclo de vida del bucle de eventos.
Un fallo de paquete con trabajos de pytest en verde generalmente se refiere a metadatos, manifiestos, renderizado de README o aislamiento de compilación.
Un fallo de escaneo de secretos requiere eliminación y rotación de credenciales.
Un fallo de lanzamiento antes de la publicación comúnmente significa que la etiqueta y project.version no coinciden.

Comprende el fallo antes de volver a ejecutar un trabajo y conserva los registros de flujo de trabajo útiles o los rastreos en la solicitud de extracción cuando la causa no sea obvia.

Las convenciones a nivel de mantenedor para ampliar el conjunto también se mantienen junto a las pruebas en tests/testing.md.

Notebooks de ejemplo

El directorio examples/ incluye notebooks de Jupyter que demuestran tanto llamadas directas a endpoints como el uso del cliente MCP con datos reales de griego y latín:

examples/00_install_and_run_perseus_mcp.ipynb — guía de instalación y lanzamiento que cubre PyPI, pip, uv, desarrollo de repositorio local, configuración del cliente MCP, verificación, actualizaciones y solución de problemas.
examples/01_basic_cts_workflow.ipynb — solicitudes CTS directas mínimas.
examples/02_search_and_navigation.ipynb — búsqueda JSON directa de Scaife y navegación CTS desde referencias válidas.
examples/03_mcp_connection_homer_iliad.ipynb — conexión del cliente FastMCP, descubrimiento de recursos de Homero y análisis de pasajes griegos de la Ilíada.
examples/04_mcp_greek_search_and_navigation.ipynb — búsqueda griega de MCP con Unicode/Beta Code, referencias válidas y navegación de pasajes.
examples/05_mcp_all_tools.ipynb — catálogo completo de herramientas MCP con descripciones y esquemas de entrada.
examples/06_openrouter_llm_mcp_interaction.ipynb — bucle opcional de llamadas a herramientas LLM de OpenRouter sobre las herramientas MCP locales, usando el enrutador de modelos gratuitos de OpenRouter por defecto.
examples/07_mcp_advanced_search_options.ipynb — búsqueda de formas/lemas de MCP, consultas de operadores de Scaife y ejemplos de búsqueda con ámbito de autor.
examples/08_mcp_cache_and_search_tools.ipynb — demostración avanzada de herramientas de caché, referencias paginadas, búsqueda con ámbito, búsqueda de lector, resaltados y recuperación de metadatos/texto de Scaife.
examples/09_openrouter_philo_politeia_analysis.ipynb — análisis asistido por OpenRouter, primero con evidencia, de πολιτεία en Filón de Alejandría usando resultados de búsqueda MCP con ámbito y pasajes citados.
examples/10_mcp_latin_augustine_workflow.ipynb — descubrimiento en latín, navegación CTS, recuperación de pasajes y un pequeño análisis de texto usando selecciones de las Epístolas de Agustín.

Ejecútalos después de instalar las dependencias del proyecto. Los notebooks de MCP usan el transporte de cliente en proceso de FastMCP y llaman a las mismas herramientas expuestas a clientes MCP externos. El notebook opcional de OpenRouter también requiere una clave de API de OpenRouter; el propio servidor MCP no. Las celdas de configuración de los notebooks instalan ayudas solo para notebooks, como python-dotenv directamente. Esas ayudas no son dependencias de tiempo de ejecución principales de perseus-mcp.

Configurar la clave de API de OpenRouter

Para examples/06_openrouter_llm_mcp_interaction.ipynb y examples/09_openrouter_philo_politeia_analysis.ipynb, copia .env.example a .env en la raíz del proyecto y reemplaza el marcador de posición:

OPENROUTER_API_KEY=sk-or-v1-...

Obtén tu clave de API en openrouter.ai. Consulta la documentación de claves de API de OpenRouter para detalles de autenticación. El archivo .env es ignorado por Git. También puedes establecer OPENROUTER_API_KEY en tu entorno o ingresarla de forma segura cuando el notebook lo solicite.

Ambos notebooks de OpenRouter usan por defecto openrouter/free. Este enrutador selecciona entre los modelos gratuitos actualmente disponibles en OpenRouter y filtra por capacidades requeridas por la solicitud, como llamadas a herramientas o salida estructurada. Evita vincular los ejemplos a un solo modelo gratuito que pueda eliminarse o no estar disponible temporalmente. La compensación es una reproducibilidad reducida: ejecuciones separadas pueden usar modelos concretos diferentes, por lo que los notebooks registran el modelo resuelto devuelto por OpenRouter. Establece OPENROUTER_MODEL a un slug de modelo fijo cuando la selección exacta del modelo sea importante.

El notebook 06_ se puede guardar y confirmar con sus salidas de LLM y llamadas a herramientas para que se rendericen en GitHub. Las variables de Python y la memoria del kernel no se almacenan en un archivo .ipynb, y el notebook no imprime la clave de API. Antes de confirmar una ejecución con credenciales, revisa las salidas visibles y busca una clave completa de OpenRouter:

rg "sk-or-v1-[A-Za-z0-9_-]{20,}" examples/06_openrouter_llm_mcp_interaction.ipynb

El comando no debería producir salida. No coincide con el marcador de posición documentado sk-or-v1-....

Uso con cualquier cliente LLM compatible con MCP

Este proyecto no requiere un LLM específico. Configura tu cliente para lanzar el servidor MCP local con:

uv --directory /full/path/to/Perseus-mcp run perseus-mcp

La mayoría de los clientes MCP necesitan las mismas piezas: nombre del servidor perseus, comando uv, argumentos --directory /full/path/to/Perseus-mcp run perseus-mcp y un entorno vacío a menos que tengas personalizaciones locales. Consulta docs/enduser.md para obtener orientación genérica sobre clientes y docs/architecture.md para las decisiones de arquitectura, incluido por qué se usa FastMCP.

Claude Desktop y Claude Code

El servidor se ejecuta con Claude sobre stdio, sin requerir OpenRouter ni clave de API (OpenRouter solo es necesario para el cliente de demostración opcional).

Claude Desktop — agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "perseus": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/Perseus-mcp", "run", "perseus-mcp"]
    }
  }
}

Reinicia Claude Desktop; las herramientas de Perseo aparecen en la lista de herramientas.

Claude Code — una línea:

claude mcp add perseus -- uv --directory /full/path/to/Perseus-mcp run perseus-mcp

Verificado contra un protocolo de enlace MCP stdio: las 23 herramientas se registran y las llamadas en vivo devuelven resultados (probado con search_perseus y list_text_groups).

Compilar una distribución de PyPI

Instala las dependencias de desarrollo, luego compila y valida ambos formatos de distribución:

python -m pip install -e ".[dev]"
python -m build
python -m twine check dist/*

La compilación crea una rueda y un archivo fuente en dist/. Prueba la rueda en un entorno virtual limpio antes de publicar. Sube primero a TestPyPI:

python -m twine upload --repository testpypi dist/*

Después de verificar la instalación desde TestPyPI, sube los mismos artefactos a PyPI:

python -m twine upload dist/*

PyPI no permite reemplazar una versión existente. Actualiza project.version en pyproject.toml, reconstruye desde un directorio dist/ limpio y publica cada versión solo una vez. El flujo de trabajo de compilación del paquete también compila y verifica los artefactos en CI sin publicarlos.

Lanzamiento automatizado de GitHub y publicación en PyPI

La automatización de lanzamientos sigue el mismo patrón de publicación confiable que MorphKit:

Establece la versión de lanzamiento en pyproject.toml, por ejemplo 1.2.3.
Fusiona el cambio de versión en la confirmación que debe lanzarse.
Crea y envía la etiqueta coincidente, por ejemplo v1.2.3.
El flujo de trabajo Build release artifacts verifica la coincidencia de etiqueta/versión, compila y valida ambas distribuciones, y las adjunta a una versión de GitHub generada.
Ese flujo de trabajo envía Publish to PyPI, que reconstruye y valida el paquete antes de publicarlo a través de la publicación confiable de PyPI.

Configura el repositorio una vez antes de la primera subida automatizada:

Crea un entorno de GitHub Actions llamado pypi.
En la configuración existente del proyecto PyPI, o como editor pendiente antes de la primera subida, agrega un editor confiable para el propietario tonyjurg, el repositorio Perseus-mcp, el flujo de trabajo publish.yml y el entorno pypi.
No agregues un token de API de PyPI; el flujo de trabajo usa OIDC de GitHub con id-token: write.

Los flujos de trabajo rechazan una etiqueta como v1.2.4 cuando project.version sigue siendo 1.2.3. Las versiones de PyPI son inmutables, así que incrementa la versión antes de reintentar un lanzamiento que ya se subió.

Contribuciones e informes de problemas

Los informes de errores, correcciones de documentación, solicitudes de funciones enfocadas y solicitudes de extracción son bienvenidos. Informa los problemas a través del rastreador de problemas de GitHub e incluye el comando, la versión de Python, el cliente MCP, los argumentos de la herramienta, el rastreo y cualquier URN de CTS relevante o consulta de búsqueda griega cuando sea posible.

Consulta docs/contributing.md para obtener orientación sobre contribuciones.

Divulgación responsable

Este proyecto fue creado con la asistencia de OpenAI Codex. El mantenedor humano sigue siendo responsable de revisar, probar y aceptar todos los cambios de código y documentación.

Licencia

Este proyecto se publica bajo la Licencia MIT. Consulta LICENSE para obtener detalles.