MCP UJI 学术服务器
模型上下文协议（MCP）的HTTP服务器，用于公开哈维·伊·大学（UJI）的学术信息。它允许用户通过兼容的MCP客户端和简单的HTTP集成查询课程、学位、位置和官方日历。
✨ 关键特性
- 🎓 统一访问学术数据（课程、学习、地点和时间表）
- 🌐 当API提供时，支持多语言（加泰罗尼亚语、西班牙语和英语）
- ⚡ 缓存到内存中以减少对UJI API的重复调用
- 🛠 八款即开即用的MCP工具，兼容MCP Inspector
- 🛡️ Pydantic模型和远程客户端的一致错误处理
🏗️ 建筑学
UJI Academic MCP服务器作为兼容的MCP客户端与Jaume I大学公共API之间的中介，通过JSON-RPC 2.0协议促进对学术数据的访问。
sequenceDiagram
participant Cliente as Cliente MCP
(Claude Desktop, VS Code, etc.)
participant Servidor as Servidor MCP
UJI Academic
participant API as API UJI
Cliente->>Servidor: Conectar a /mcp (HTTP)
Servidor-->>Cliente: Confirmación de conexión
Cliente->>Servidor: Llamada a herramienta
(e.g., get_subjects)
activate Servidor
Servidor->>API: Consulta datos académicos
(GET /api/subjects)
API-->>Servidor: Respuesta JSON con datos
Servidor-->>Cliente: Resultado de la herramienta
deactivate Servidor
Note over Cliente,Servidor: Comunicación vía JSON-RPC 2.0 sobre HTTP
Note over Servidor,API: Comunicación HTTP con caché en memoria🚀 快速启动
- 安装依赖项：
git clone && cd MCP_UJI_academic && uv sync - 启动服务器：
uv run start_server.py --host 127.0.0.1 --port 8084 - 连接一个MCP客户端： 使用URL
http://127.0.0.1:8084/mcp在你首选的MCP客户端中（参见“🤖 连接MCP客户端”部分）。
对于Docker： docker compose up 并连接到 http://localhost:8084/mcp。
🧱 先决条件
- Python 3.12或更高版本
- 紫外线 已安装为依赖管理器
- 访问互联网以查询UJI的公共API
- （可选）Docker 和 Docker Compose 用于容器化运行
🚀 安装与配置
git clone
cd MCP_UJI_academic
uv sync▶️ 服务器执行
注： 在连接任何MCP客户端之前，服务器必须已经运行。保持终端打开或在后台运行。
# Desarrollo local
uv run start_server.py --host 127.0.0.1 --port 8084
# Servidor accesible desde la red
uv run start_server.py --host 0.0.0.0 --port 8084
# Desarrollo con recarga automática
uv run start_server.py --host 127.0.0.1 --port 8084 --reloadstart_server.py他是一名一投即发的投手mcp_server.py使用指定的参数。如果你更倾向于直接使用Python，请运行python start_server.py。
🐳 使用 Docker 运行
注： 确保容器正在运行后再连接MCP客户端。服务器将在 http://localhost:8084。手动构建和运行镜像
docker build -t mcp-uji-academic .
docker run --rm -p 8084:8084 mcp-uji-academic该API将可供使用于 http://localhost:8084你可以使用 Ctrl+C 或者使用 docker stop 如果你在后台运行它。
使用Docker Compose进行编排
# Levantar el servicio
docker compose up
# Levantar en segundo plano
docker compose up -d
# Detener y limpiar
docker compose down文件 docker-compose.yml 它暴露了8084端口。如果你需要在另一个主机端口上提供服务，请调整映射（例如 - "9090:8084"）。
🌐 主要的HTTP端点
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | （GET请求） / | 服务器基本信息 |
| GET | （GET方法） /health | 快速状态检查 |
| GET | （GET请求） /tools | MCP工具列表及其输入方案 |
| 帖子 | /mcp | 兼容客户端的MCP JSON-RPC 2.0终端点 |
远程参考服务器
- 基础URL：
http://:8084 - 端点MCP：
http://:8084/mcp - 健康检查：
http://:8084/health
当你将服务器发布到其他主机时，请将IP替换为你部署的IP。
🧰 可用的MCP工具
| 工具 | 返回的数据 | 主要参数 |
|---|---|---|
get_subjects | 分页显示的课程列表 | start， limit， full |
search_subjects | 按课程代码或名称搜索课程 | query， language |
get_degrees | 完整学位目录 | full |
search_degrees | 学位搜索 | query， language |
get_locations | 位置（楼宇、教室、实验室） | full |
search_locations | 搜索位置 | query |
get_class_schedule | iCalendar格式的课程表 | year， degree_id |
get_exam_schedule | iCalendar格式的考试日程表 | year， degree_id |
所有工具都返回结构化的JSON数据，并在适用时提供多语言信息。
🤖 连接MCP客户
重要提示： 在连接任何客户端之前，MCP服务器必须正在运行（本地或Docker中）。请确认curl http://127.0.0.1:8084/healthocurl http://localhost:8084/health用于Docker。
一般建议
- MCP终端通过HTTP使用JSON-RPC 2.0协议；任何兼容的客户端都可以使用它。
- 确保端口（
8084（默认情况下）可从你的机器或SSH隧道访问。 - 对于公共环境，请根据您的策略添加身份验证或安全代理。
- 如果你在本地使用Docker： 服务器将在
http://localhost:8084/mcp确保容器正在运行后再连接客户端。
MCP 检查员（npx)
npx @modelcontextprotocol/inspector- 打开浏览器（通常打开
http://localhost:3000）。 - 选择 可流式传输的HTTP 作为交通工具。
- 输入端点URL（
http://127.0.0.1:8084/mcp如果你在本地使用 Docker，或者http://:8084/mcp（对于远程服务器）。 - 脉搏 连接 并尝试使用任意一种可用的八种工具之一。
VS Code（MCP扩展）
添加到 settings.json 用户或工作区：
{
"mcp.servers": {
"mcp-uji-academic": {
"transport": "http",
"url": "http://127.0.0.1:8084/mcp"
}
}
}如果你使用SSH隧道：
ssh -L 8084:localhost:8084 usuario@IP_SERVIDOR_REMOTO并将URL更改为 http://127.0.0.1:8084/mcp。
Claude Desktop（可译为“Claude桌面版”或根据上下文简化为“桌面版Claude”）
Claude Desktop（可译为“Claude桌面版”） 不 它可以自行调用远程HTTP服务器：它只执行本地命令。因此，你需要在你的机器上运行MCP服务器 之前 克劳德启动了它。
添加到你的 claude_desktop_config.json:
{
"mcpServers": {
"mcp-uji-academic": {
"command": "uv",
"args": [
"run",
"start_server.py",
"--host",
"127.0.0.1",
"--port",
"8084"
],
"cwd": "/ruta/completa/a/MCP_UJI_academic"
}
}
}- 调整
cwd到项目的实际路线。 - 里面的命令
args必须在一行内；JSON 不支持手动换行（\) 在字符串内部。 - 修改文件后，重启Claude Desktop以重新加载设置。
npx @modelcontextprotocol/inspector 它是一个测试工具。VS Code和Claude需要各自的JSON配置。🧪 测试与验证
# Test de integración (arranca el servidor temporalmente y verifica endpoints)
# Asegúrate de que el puerto 8084 esté libre antes de ejecutar
uv run python integration_test.py
# Checks manuales rápidos
curl http://127.0.0.1:8084/health
curl -X POST http://127.0.0.1:8084/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'📁 项目结构
MCP_UJI_academic/
├── api_client.py # Cliente HTTP con caché y parseo iCalendar
├── integration_test.py # Prueba de arranque y endpoints HTTP
├── mcp_server.py # FastAPI con endpoints HTTP y MCP JSON-RPC
├── models.py # Modelos Pydantic para datos académicos
├── start_server.py # Lanzador de conveniencia
├── pyproject.toml # Configuración y dependencias
└── README.md # Documentación (este archivo)🛠️ 问题解决
| 问题 | 如何解决 |
|---|---|
| 端口8084已被占用 | lsof -i :8084 以识别该进程。终止该进程或使用 --port 8001 以更改端口。 |
| 连接超时或被拒绝 | 确认服务器正在运行，并且 curl http://:8084/health检查防火墙或SSH隧道。 |
| 与uv不一致的依赖项 | 运行 uv sync --reinstall 以重新安装依赖项。 |
| UJI公共API的错误 | 检查服务器日志；API可能较慢或不稳定。请稍后再试。 |
| Docker: 容器无响应 | 确保端口已正确映射（-p 8084:8084）。 美国 docker logs 以查看日志。 |
| Claude Desktop 无法连接 | 确认命令中 claude_desktop_config.json 要正确，并且 cwd 指向项目路径。重启Claude。 |
🌍 使用的外部API
- 基本URL：
https://ujiapps.uji.es/lod-autorest/api/ - 可用数据：课程、研究、地点和日历，格式为JSON/iCalendar
📄 许可和支持
- 许可证：MIT
- 有问题或遇到故障？请先打开一个议题，查看故障排除表或运行集成测试，再进行报告。
______________________________________________________________________
该项目旨在简化在MCP生态系统内访问UJI学术信息的程序化途径。利用并自动化您的教育流程！