iGuat-MCP

Servicio MCP (Model Context Protocol) de solo lectura para los datos del campus de iGuihang. El proyecto se basa en Python, FastMCP y Streamable HTTP, y expone consultas de horarios, clases y campus como herramientas estándar que los clientes de IA pueden invocar.

Este proyecto solo ofrece capacidades de consulta; no modifica el miniprograma de WeChat ni los datos académicos de origen.

Funcionalidades

• Obtener la lista completa de semestres, el semestre actual y el siguiente

• Buscar clases por especialidad, grado y palabra clave de clase

• Consultar el horario de una clase, semestre y semana específicos

• Consultar el horario de una persona específica y eliminar los campos de identidad antes de devolver la respuesta

• Inferir el campus según la información de la especialidad

• Caché de horarios con TTL integrado, límite de concurrencia y comprobación de estado

• Protección de las interfaces MCP y de administración mediante Bearer API Key

• Soporte para actualizar en caliente el token de origen a través de la interfaz de administración

• Soporte para despliegue con Docker, variables de entorno y Docker Secrets

Related MCP server: gaokao-helper-worker-mcp

Herramientas MCP

Pila tecnológica

• Python 3.11+

• MCP / FastMCP

• HTTPX

• Uvicorn

• Pytest

• Docker

Inicio rápido

Ejecución local

git clone https://github.com/Strayed2SE/iGuat-MCP.git
cd iGuat-MCP

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[test]"

cp .env.example .env
# 按下方说明配置环境变量后启动
python server.py

El servicio escucha por defecto en 0.0.0.0:8000:

• MCP: http://127.0.0.1:8000/mcp

• Comprobación de estado: http://127.0.0.1:8000/healthz

Cabeceras de solicitud del cliente MCP:

Authorization: Bearer <MCP_PUBLIC_API_KEY>

Docker

docker build -t iguat-mcp .
docker run --rm -p 8000:8000 --env-file .env iguat-mcp

En producción se recomienda usar la forma NAME_FILE para cargar configuraciones sensibles desde Docker Secrets o archivos de solo lectura:

docker run --rm -p 8000:8000 \
  -e IGUAT_USER_TOKEN_FILE=/run/secrets/iguat_token \
  -e IGUAT_MAIN_SIGN_KEY_FILE=/run/secrets/main_sign_key \
  -e MCP_PUBLIC_API_KEY_FILE=/run/secrets/public_key \
  -e MCP_ADMIN_API_KEY_FILE=/run/secrets/admin_key \
  --mount type=bind,src=/secure/secrets,dst=/run/secrets,ro \
  iguat-mcp

Configuración

Copie .env.example y ajuste según sea necesario:

Actualizar el token de origen

Cuando el token de origen caduca, el administrador puede actualizar el token en memoria sin reiniciar el servicio:

curl -X PUT http://127.0.0.1:8000/admin/token \
  -H "Authorization: Bearer <MCP_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"token":"<NEW_TOKEN>"}'

Pruebas

pip install -e ".[test]"
pytest -q

Notas de seguridad

• No envíe tokens reales, claves de firma, API Keys ni .env al repositorio.

• El servicio no devuelve tokens, firmas ni campos de identidad personal a los clientes MCP.

• Por defecto no se leen las variables de entorno de proxy del sistema; solo configure IGUAT_TRUST_ENV=1 si el entorno de despliegue realmente lo requiere.

Proyectos relacionados

• Sistema de consulta de la enciclopedia de Guihang: base de conocimiento del campus y sistema de preguntas y respuestas inteligente que integra este servicio MCP.