OpenEdu MCP

An MCP server for educational resource search covering K-12 through college level. It combines four public APIs—Open Library, Wikipedia, Dictionary API, and arXiv—to provide 22 tools for book recommendations, wiki article summaries, vocabulary analysis, and academic paper search.

This repository is a fork and modification of Cicatriiz/openedu-mcp for Goover MCP Hub distribution. The original was stdio transport-only; this repository adds streamable HTTP transport support and fixes a critical bug that made startup impossible.

Basic Information

Related MCP server: MCP Learning Server

Introduction

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.

Korean

OpenEdu MCP is an MCP that provides educational resources from K-12 through college level by combining four public APIs: Open Library, Wikipedia, Dictionary API, and arXiv. With 22 tools in total, it supports grade-level educational book search and recommendations, Wikipedia article search, summaries, and featured articles tailored to grade level, dictionary lookups including vocabulary difficulty analysis and pronunciation guides, and academic paper search and research trend analysis by subject and academic level. Every result is tagged with grade-level appropriateness (K-2~College) and curriculum alignment information (Common Core, etc.). Responses are stored in a local cache to reduce redundant calls, and no API keys or authentication are required.

Provided Tools (22)

It is a pure tool-based MCP that does not provide prompts/resources.

Changes from the Original

Bug Fixes

1. Crash at import time — a critical defect that made the server itself impossible to start

The original src/main.py had unfinished SSE experiment code left at the bottom.

@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() does not support route/methods arguments, so it crashed immediately with a TypeError, making it impossible to run the server even in stdio mode. The entire sse_event_generator and stream_events functions (about 34 lines) were removed.

2. The mcp package was not in the direct dependency list

requirements.txt/pyproject.toml only specified fastmcp>=0.1.0, but the actual code imported mcp.server.fastmcp, which is separate. It happened to work as a transitive dependency of the fastmcp package, a fragile structure that could break if the fastmcp dependency changes in the future. Added mcp>=1.9.0,<2.0.0 as a direct dependency.

3. Missing HTTP transport configuration

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

Also added the missing import os.

Note — Items Resolved Through Deployment Without Code Changes

Since load_config() in src/config.py looks up config/default.yaml using a relative path based on the process cwd, this was resolved by setting the Dockerfile's WORKDIR to the repository root (no code change needed).

HTTP Bridge Addition

Without touching the existing main() (stdio path) at all, a new main_http() function was added to 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")

New file 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()

Items added to 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 test results: bare /mcp returns 200 and /mcp/ returns 307, confirming normal operation without a separate ASGI wrapper.

How to Run

stdio (Original Method, Kept As-Is)

python src/main.py

streamable HTTP (New, for Goover MCP Hub Distribution)

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

Local Build and 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

Verified items:

• initialize — no session ID, stateless operation confirmed

• tools/list — all 22 tools returned correctly

• tools/call(get_word_definition, "photosynthesis") — actual call to dictionaryapi.dev succeeded, definition, pronunciation, and educational metadata all returned correctly

Notable Features of This Fork

• The original repository was only verified for stdio, and unfinished HTTP/SSE code was left in a state that crashed the entire server at import time. This was not a simple configuration omission but a defect at the level of making execution itself impossible.

• The mcp package existed only as a transitive dependency of the fastmcp package rather than a direct dependency, making packaging fragile. It was declared as a direct dependency to prepare for future breaking changes.

• Since the config loader depends on relative paths, this was worked around with the Dockerfile WORKDIR instead of code changes.

• The cache service and usage statistics service share the same SQLite file.

• All four external APIs (Open Library, Wikipedia, Dictionary API, arXiv) require no authentication/API keys, so there are no credential management issues.

License

Follows the license of the original repository (Cicatriiz/openedu-mcp). Be sure to check the original LICENSE file before redistribution or commercial use.