OpenEdu MCP

Dies ist ein MCP-Server zur Suche nach Bildungsmaterialien, der von K-12 bis zur Hochschulebene abdeckt. Er kombiniert vier öffentliche APIs – Open Library, Wikipedia, Dictionary API und arXiv – und stellt 22 Tools bereit, von Buchempfehlungen über Wikipedia-Artikelzusammenfassungen und Vokabelanalysen bis hin zur Suche nach wissenschaftlichen Arbeiten.

Dieses Repository ist eine für die Goover MCP Hub-Verteilung geforkte und modifizierte Version von Cicatriiz/openedu-mcp. Das Original war ausschließlich für den stdio-Transport ausgelegt; in diesem Repository wurde die Unterstützung für den streamable HTTP-Transport hinzugefügt und ein kritischer Fehler behoben, der den Start vollständig verhinderte.

Grundinformationen

Related MCP server: MCP Learning Server

Einführung

Englisch

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.

Koreanisch

OpenEdu MCP ist ein MCP, das vier öffentliche APIs – Open Library, Wikipedia, Dictionary API und arXiv – kombiniert und Bildungsmaterialien von K-12 bis zur Hochschulebene bereitstellt. Mit insgesamt 22 Tools unterstützt es die Suche und Empfehlung von Bildungsbüchern nach Klassenstufe, die Suche und Zusammenfassung von Wikipedia-Artikeln sowie die Empfehlung des Artikels des Tages passend zur Klassenstufe, Wörterbuchabfragen mit Vokabel-Schwierigkeitsanalyse und Aussprachehilfen sowie die Suche nach wissenschaftlichen Arbeiten und die Analyse von Forschungstrends nach Thema und akademischem Niveau. Alle Ergebnisse werden mit Tags für die Klassenstufen-Eignung (K-2~College) und die Lehrplan-Anbindung (Common Core usw.) versehen. Antworten werden lokal zwischengespeichert, um doppelte Aufrufe zu reduzieren, und es sind keine separaten API-Schlüssel oder Authentifizierungen erforderlich.

Bereitgestellte Tools (22)

Es ist ein reiner Tool-basierter MCP, der keine Prompts/Ressourcen bereitstellt.

Änderungen gegenüber dem Original

Fehlerbehebungen

1. Absturz beim Import – kritischer Fehler, der den Serverstart vollständig verhinderte

Am Ende der Originaldatei src/main.py war unvollständiger SSE-Experimentiercode verblieben.

@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() unterstützt die Argumente route/methods nicht, sodass sofort ein TypeError auftrat und der Server selbst im stdio-Modus nicht gestartet werden konnte. Die Funktionen sse_event_generator und stream_events (insgesamt ca. 34 Zeilen) wurden vollständig entfernt.

2. Das Paket mcp fehlte in der direkten Abhängigkeitsliste

In requirements.txt/pyproject.toml war nur fastmcp>=0.1.0 angegeben, aber der tatsächliche Code importierte das davon getrennte mcp.server.fastmcp. Es funktionierte nur zufällig über die transitive Abhängigkeit des Pakets fastmcp, was eine fragile Struktur darstellte, die brechen könnte, wenn sich die fastmcp-Abhängigkeit in Zukunft ändert. mcp>=1.9.0,<2.0.0 wurde als direkte Abhängigkeit hinzugefügt.

3. Fehlende HTTP-Transportkonfiguration

# 변경 전
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,
)

Das fehlende import os wurde ebenfalls ergänzt.

Hinweis – durch Verteilung gelöste Punkte ohne Codeänderung

Da load_config() in src/config.py die Datei config/default.yaml über einen relativen Pfad basierend auf dem Prozess-cwd sucht, wurde dies gelöst, indem der WORKDIR im Dockerfile auf das Repository-Root gesetzt wurde (keine Codeänderung erforderlich).

Hinzufügen einer HTTP-Brücke

Die bestehende main()-Funktion (stdio-Pfad) wurde überhaupt nicht angefasst; in src/main.py wurde eine neue Funktion main_http() eingerichtet.

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")

Neue Datei 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()

In pyproject.toml hinzugefügte Einträge:

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

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

Ergebnis des trailing-slash-Tests: Bare /mcp liefert 200, /mcp/ liefert 307, sodass die Funktion ohne separaten ASGI-Wrapper ordnungsgemäß funktioniert.

Ausführungsmethoden

stdio (Originalmethode, unverändert beibehalten)

python src/main.py

streamable HTTP (neu, für die Goover MCP Hub-Verteilung)

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"]

Lokaler Build und Smoke-Test

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

Verifizierte Punkte:

• initialize – keine Sitzungs-ID, zustandsloser Normalbetrieb

• tools/list – 22 Tools werden ordnungsgemäß zurückgegeben

• tools/call (get_word_definition, "photosynthesis") – tatsächlicher Aufruf von dictionaryapi.dev erfolgreich, Definition, Aussprache und Bildungsmetadaten werden ordnungsgemäß zurückgegeben

Besonderheiten dieses Forks

• Das Original-Repository war nur für stdio verifiziert, und unvollständiger HTTP/SSE-Code verursachte beim Import einen Absturz des gesamten Servers. Es handelte sich nicht nur um eine fehlende Konfiguration, sondern um einen Fehler, der die Ausführung selbst unmöglich machte.

• Das Paket mcp existierte nicht als direkte Abhängigkeit, sondern nur als transitive Abhängigkeit des Pakets fastmcp, was die Paketierung fragil machte. Durch die Angabe als direkte Abhängigkeit wurde Vorsorge für zukünftige Breaking Changes getroffen.

• Da der Konfigurationslader von relativen Pfaden abhängt, wurde dies anstelle einer Codeänderung über den Dockerfile-WORKDIR umgangen.

• Der Cache-Dienst und der Nutzungsstatistik-Dienst teilen sich dieselbe SQLite-Datei.

• Alle vier externen APIs (Open Library, Wikipedia, Dictionary API, arXiv) benötigen keine Authentifizierung/API-Schlüssel, sodass es keine Probleme mit der Verwaltung von Anmeldeinformationen gibt.

Lizenz

Es gilt die Lizenz des Original-Repositorys (Cicatriiz/openedu-mcp). Vor Weiterverbreitung oder kommerzieller Nutzung muss die LICENSE-Datei des Originals unbedingt geprüft werden.