OpenEdu MCP

MCP-сервер для поиска образовательных материалов, охватывающий уровни от K-12 до университетского. Объединяя четыре публичных API — Open Library, Wikipedia, Dictionary API и arXiv, — предоставляет 22 инструмента: рекомендации книг, краткие изложения вики-статей, анализ лексики и поиск академических статей.

Этот репозиторий — форк с изменениями Cicatriiz/openedu-mcp для развёртывания через Goover MCP Hub. Оригинал поддерживал только stdio transport; в этом репозитории добавлена поддержка streamable HTTP transport и исправлена критическая ошибка, из-за которой сервер вообще не запускался.

Основная информация

Related MCP server: MCP Learning Server

Введение

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.

한글

OpenEdu MCP는 Open Library, Wikipedia, Dictionary API, arXiv 등 4개의 공개 API를 결합해 K-12부터 대학 수준까지 교육 자료를 제공하는 MCP입니다. 총 22개 도구로 학년별 교육 도서 검색·추천, 학년 수준에 맞춘 위키피디아 문서 검색·요약·오늘의 추천 문서, 어휘 난이도 분석과 발음 가이드를 포함한 사전 조회, 주제·학업 수준별 학술 논문 검색과 연구 동향 분석을 지원합니다. 모든 결과에 학년 적합도(K-2~College)와 교육과정 연계 정보(Common Core 등)가 태그로 붙습니다. 응답은 로컬 캐시로 저장되어 중복 호출을 줄이며, 별도의 API 키나 인증 없이 사용 가능합니다.

Предоставляемые инструменты (22)

Это чисто инструмент-ориентированный MCP без промптов и ресурсов.

Изменения относительно оригинала

Исправления ошибок

1. Краш на этапе импорта — критический дефект, из-за которого сервер вообще не запускался

Внизу исходного src/main.py остался незавершённый экспериментальный код SSE.

@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() не поддерживает аргументы route/methods, что вызывало немедленный краш с TypeError; из-за этого сервер нельзя было запустить даже в stdio-режиме. Полностью удалены функции sse_event_generator и stream_events (около 34 строк).

2. Пакет mcp отсутствовал в списке прямых зависимостей

В requirements.txt/pyproject.toml был указан только fastmcp>=0.1.0, однако фактический код импортировал отдельный от него mcp.server.fastmcp. Это работало лишь случайно, благодаря транзитивной зависимости пакета fastmcp, — хрупкая структура, которая могла сломаться при изменении зависимостей fastmcp. Добавлен mcp>=1.9.0,<2.0.0 как прямая зависимость.

3. Отсутствовала настройка HTTP transport

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

Также добавлен пропущенный import os.

Примечание — пункты, решённые на уровне развёртывания без изменения кода

load_config() в src/config.py ищет config/default.yaml по относительному пути от рабочей директории процесса, поэтому проблема решена установкой WORKDIR в Dockerfile на корень репозитория (изменение кода не потребовалось).

Добавлен HTTP-мост

Существующая main() (путь stdio) не тронута; в src/main.py создана новая функция main_http().

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

Новый файл 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()

Добавленные пункты в 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"

Результат теста trailing-slash: голый /mcp возвращает 200, /mcp/ — 307, что подтверждает корректную работу без отдельного ASGI-обёртки.

Способы запуска

stdio (исходный способ, сохранён без изменений)

python src/main.py

streamable HTTP (новый, для развёртывания через 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"]

Локальная сборка и смоук-тест

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

Проверенные пункты:

• initialize — без ID сессии, stateless работает корректно

• tools/list — корректно возвращает 22 инструмента

• tools/call (get_word_definition, "photosynthesis") — реальный вызов dictionaryapi.dev успешен, корректно возвращены определение, произношение и образовательные метаданные

Особенности этого форка

• Исходный репозиторий был проверен только для stdio, а незавершённый HTTP/SSE-код вызывал краш всего сервера на этапе импорта. Это был не просто пропуск настройки, а дефект уровня полной неработоспособности.

• Пакет mcp существовал не как прямая зависимость, а лишь как транзитивная зависимость пакета fastmcp, что делало упаковку хрупкой. Указан как прямая зависимость для защиты от будущих breaking change.

• Загрузчик конфигурации зависит от относительных путей, поэтому вместо изменения кода проблема обойдена через WORKDIR в Dockerfile.

• Сервис кэша и сервис статистики использования используют один и тот же файл SQLite.

• Все 4 внешних API (Open Library, Wikipedia, Dictionary API, arXiv) не требуют аутентификации/API-ключей, поэтому проблем с управлением учётными данными нет.

Лицензия

Действует лицензия исходного репозитория (Cicatriiz/openedu-mcp). Перед распространением или коммерческим использованием обязательно ознакомьтесь с файлом LICENSE оригинала.