OpenEdu MCP

Es un servidor MCP de búsqueda de materiales educativos que cubre desde K-12 hasta nivel universitario. Combina 4 API públicas —Open Library, Wikipedia, Dictionary API y arXiv— y ofrece 22 herramientas que incluyen recomendación de libros, resúmenes de artículos de Wikipedia, análisis de vocabulario y búsqueda de artículos académicos.

Este repositorio es una versión bifurcada y modificada de Cicatriiz/openedu-mcp para su distribución a través de Goover MCP Hub. El original era exclusivo para transporte stdio; en este repositorio se ha añadido soporte para transporte streamable HTTP y se ha corregido un error crítico que impedía por completo el arranque.

Información básica

Related MCP server: MCP Learning Server

Introducción

English

OpenEdu MCP provides curated educational resources for K-12 through college-level learning by combining four public APIs: Open Library, Wikipedia, Dictionary API, and arXiv. It offers 22 tools covering educational book search and recommendations by grade level, Wikipedia article search with grade-appropriate summaries and featured articles, dictionary lookups with vocabulary complexity analysis and pronunciation guides, and academic paper search with research trend analysis by subject and academic level. Every tool tags results with grade-level appropriateness (K-2 through College) and curriculum alignment (e.g., Common Core). Responses are cached locally to reduce redundant API calls. No API keys or authentication are required for any of the underlying data sources.

Coreano

OpenEdu MCP es un MCP que combina 4 API públicas —Open Library, Wikipedia, Dictionary API y arXiv— para ofrecer materiales educativos desde K-12 hasta nivel universitario. Con un total de 22 herramientas, admite búsqueda y recomendación de libros educativos por nivel de grado, búsqueda, resumen y artículo destacado del día de Wikipedia adaptados al nivel de grado, consulta de diccionario con análisis de dificultad de vocabulario y guía de pronunciación, y búsqueda de artículos académicos y análisis de tendencias de investigación por tema y nivel académico. Todos los resultados llevan etiquetas de idoneidad por grado (K-2~College) e información de alineación curricular (Common Core, etc.). Las respuestas se guardan en caché local para reducir llamadas duplicadas, y se puede usar sin claves de API ni autenticación adicionales.

Herramientas proporcionadas (22)

Es un MCP puramente basado en herramientas, sin prompts ni recursos.

Cambios respecto al original

Corrección de errores

1. Fallo en el momento del import — defecto crítico que impedía el arranque del propio servidor

Al final del src/main.py original quedaba un código experimental SSE sin terminar.

@mcp.tool(route="/events", methods=["GET"])  # Assuming a route decorator might exist or be added to FastMCP
async def stream_events(request: Request) -> StreamingResponse:

@mcp.tool() no admite los argumentos route/methods, por lo que se producía un TypeError y un fallo inmediato; debido a esto, ni siquiera en modo stdio era posible ejecutar el servidor. Se eliminaron por completo las funciones sse_event_generator y stream_events (unas 34 líneas).

2. El paquete mcp no figuraba en la lista de dependencias directas

En requirements.txt/pyproject.toml solo se especificaba fastmcp>=0.1.0, pero el código real importaba mcp.server.fastmcp, que es un paquete distinto. Funcionaba por casualidad como dependencia transitiva del paquete fastmcp, una estructura frágil que podría romperse si la dependencia de fastmcp cambiara en el futuro. Se añadió mcp>=1.9.0,<2.0.0 como dependencia directa.

3. Falta de configuración del transporte HTTP

# 변경 전
mcp = FastMCP("openedu-mcp-server")

# 변경 후
mcp = FastMCP(
    "openedu-mcp-server",
    host=os.getenv("OPENEDU_MCP_HOST", "0.0.0.0"),
    port=int(os.getenv("OPENEDU_MCP_PORT", "8000")),
    stateless_http=True,
)

También se añadió el import os que faltaba.

Nota — elementos resueltos en la distribución sin modificar el código

load_config() de src/config.py busca config/default.yaml mediante una ruta relativa al cwd del proceso, por lo que se resolvió ajustando el WORKDIR del Dockerfile a la raíz del repositorio (sin necesidad de cambios de código).

Adición del puente HTTP

Sin tocar en absoluto el main() existente (ruta stdio), se creó la función main_http() en src/main.py.

def main_http():
    """HTTP entry point for the OpenEdu MCP Server (streamable-http transport).

    Added for Goover MCP Hub deployment; the original stdio path via main()
    is untouched.
    """
    try:
        asyncio.run(initialize_services())

        import atexit
        atexit.register(lambda: asyncio.run(cleanup_services()))

        logger.info("Starting OpenEdu MCP Server (HTTP)...")

        mcp.run(transport="streamable-http")

    except KeyboardInterrupt:
        logger.info("Server shutdown requested")
    except Exception as e:
        logger.error(f"Server startup failed:{e}")
        sys.exit(1)
    finally:
        logger.info("OpenEdu MCP Server stopped")

Nuevo archivo src/http_entrypoint.py:

"""
HTTP entrypoint for OpenEdu MCP Server (Goover MCP Hub deployment).

Runs the server over streamable-http transport by invoking main_http()
from main.py. The original stdio entrypoint (main.py's main(), run via
`python src/main.py`) is left completely untouched.

Must be run with the repository root as the working directory, since
config.py resolves "config/default.yaml" relative to the process cwd.
"""
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))

import main

if __name__ == "__main__":
    main.main_http()

Elementos añadidos a pyproject.toml:

dependencies = [..., "mcp>=1.9.0,<2.0.0", ...]

[project.scripts]
openedu-mcp-server = "src.main:main"
openedu-mcp-server-http = "src.main:main_http"

Resultado de la prueba de trailing-slash: /mcp desnudo devuelve 200 y /mcp/ devuelve 307, lo que confirma que funciona correctamente sin necesidad de un wrapper ASGI adicional.

Método de ejecución

stdio (método original, se mantiene igual)

python src/main.py

streamable HTTP (nuevo, para distribución con Goover MCP Hub)

python src/http_entrypoint.py

Docker

Dockerfile

FROM python:3.11-slim-bookworm

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV OPENEDU_MCP_HOST=0.0.0.0
ENV OPENEDU_MCP_PORT=8000
ENV OPENEDU_MCP_CACHE_PATH=/data/cache.db

EXPOSE 8000

CMD ["python", "src/http_entrypoint.py"]

Compilación local y prueba de humo

docker build --no-cache --platform linux/amd64 -t openedu-mcp:latest .
docker run -d --name openedu-mcp-test -p 8069:8000 openedu-mcp:latest

Elementos verificados:

• initialize — sin ID de sesión, funcionamiento stateless correcto

• tools/list — devuelve correctamente las 22 herramientas

• tools/call(get_word_definition, "photosynthesis") — llamada real a dictionaryapi.dev correcta, devuelve definición, pronunciación y metadatos educativos

Aspectos característicos de esta bifurcación

• El repositorio original solo estaba verificado para stdio, y el código HTTP/SSE sin terminar provocaba un fallo de todo el servidor en el momento del import, quedando abandonado en ese estado. No era una simple omisión de configuración, sino un defecto de nivel que hacía imposible la ejecución.

• El paquete mcp no era una dependencia directa, sino que existía únicamente como dependencia transitiva del paquete fastmcp, lo que hacía frágil el empaquetado. Se declaró como dependencia directa para prepararse ante futuros cambios disruptivos.

• El cargador de configuración depende de rutas relativas, por lo que se resolvió de forma indirecta con el WORKDIR del Dockerfile en lugar de modificar el código.

• El servicio de caché y el servicio de estadísticas de uso comparten el mismo archivo SQLite.

• Las 4 API externas (Open Library, Wikipedia, Dictionary API, arXiv) no requieren autenticación ni claves de API, por lo que no hay problemas de gestión de credenciales.

Licencia

Se sigue la licencia del repositorio original (Cicatriiz/openedu-mcp). Antes de la redistribución o el uso comercial, asegúrese de revisar el archivo LICENSE original.