Skolverket MCP 服务器

使用说明（简要，便于上手）：

• 项目简介
  • 这是一个完整的后端 MCP 服务器实现，旨在向 LLM 客户端提供 Skolverket 的教育数据、工具与提示模板，按照 MCP 规范通过 JSON-RPC 进行交互，并支持多种传输方式。
  • 代码包括两类服务器入口：一个基于标准输入输出的服务（stdio 传输），一个基于 HTTP/SSE 的流式接口（streamable-http 传输）。两者均为可运行的 MCP 服务实现。
• 主要功能点
  • 资源（Resources）：提供上下文用的数据资源清单并支持读取资源内容。
  • 工具（Tools）：暴露用于查询 Läroplan（Läroplan API）、Skolenhetsregistret、Planned Educations 等 API 的工具，且带有参数校验、错误处理与缓存。
  • 提示（Prompts）：提供可直接调用的提示模板，便于 LLM 生成相应的对话内容与工作流。
  • 客户端通信：通过 MCP 的 JSON-RPC 请求/响应实现，服务端按请求顺序处理并返回结构化 JSON-RPC 响应。
  • 会话与能力声明：在服务初始化时声明名称、版本以及 capabilities（工具、资源、提示、日志等）。
  • 传输协议：支持 stdio（通过 index.ts 启动的入口）和 HTTP/SSE（通过 streamable-http-server.ts 提供的端点）。
  • 日志与错误处理：内置统一的错误类型、日志器与错误包装，便于追踪与排错。
• 安装步骤
  • 安装依赖
    • 使用 Node.js 环境安装依赖包（如 npm install）。
  • 构建与运行
    • 运行 stdio 版本（通过 stdin/stdout 与客户端通信）：
      • 构建产物后执行入口：node dist/index.js（或等效的编译输出入口）。
    • 运行 HTTP/SSE 版本（通过 HTTP/ SSE 与客户端通信）：
      • 构建产物后执行入口：node dist/streamable-http-server.js（默认监听端口为 3000，必要时可通过环境变量 PORT 设置）。
  • 运行前的必要配置
    • 根据需要设置环境变量（如 SKOLVERKET_API_KEY、SKOLVERKET_SYLLABUS_API_URL、PORT 等），以便后端正确访问 Skolverket 的 API。
  • MCP 客户端连接配置
    • 客户端连接不需要改动服务端实现，但需要提供一个 JSON 配置，描述服务器名称、启动命令与参数等，以便客户端能够启动与 MCP 服务器的连接。如下所示（仅为描述性配置示例，非代码块）：
      • server 名称：skolverket
      • command：node
      • args：dist/index.js（若使用 stdio 入口）或 dist/streamable-http-server.js（若使用 HTTP/SSE 入口）
      • 说明：仓库提供两种入口，客户端可根据实际运行的传输方式选择对应的启动命令与参数；没有必须的额外参数，运行时可通过环境变量控制端口、是否开启缓存等特性。
• 基本使用方法
  • 启动后，MCP 客户端通过指定传输方式向服务器发起 JSON-RPC 请求，服务器返回相应的 JSON-RPC 响应或通知。
  • 浏览健康状态：使用 /health（HTTP/SSE 版本）或等价的健康检查接口，确认服务是否在线、可用。
  • 调用资源/工具/提示：通过对应 MCP 端点发起 ListResources、ListTools、ListPrompts、CallTool 等请求，或通过 /mcp 进行请求（HTTP/SSE 版本的端点暴露在 /mcp 路径下）。
  • 监控与日志：后端使用集中日志系统输出到 stderr（符合 MCP 要求），并在日志中包含请求信息、错误信息与上下文数据，便于排错。