Un moderno servidor Model Context Protocol (MCP) y un servicio FastAPI para el Student Affairs Information System de Middle East Technical University (METU / ODTÜ), con la abreviatura SAIS y acceso mediante student.metu.edu.tr.
Conecta tus asistentes de IA (como OpenCode, Claude Desktop y Cursor) directamente a METU SAIS con autenticación real y procesamiento estructurado de datos.
Autenticación SSO: Gestiona el flujo real de inicio de sesión SSO de METU (/ssO/backend/request/user/signin) y la validación del token de sesión.
Proxy Scraper y analizador HTML: Establece automáticamente sesiones proxy autenticadas (/pxy/Student_Information/) y analiza los registros de estudiantes en JSON estructuredo.
Servidor MCP (MCP 2.x SDK): Expone herramientas tipificadas mediante entrada/salida estándar (stdi).
Servicio REST FastAPI: Backend REST HTTP altornativo para integraciones.
Privacidad y seguridad: Cero registro o expocición de credenciales. Las credenciales permanecen locales en tu arcivo .env ignoredo por git.
Related MCP server: SABIS MCP Server
Herramienta | Descripción |
| Obtiene el ID de estudiente, nomre, departamento, semestre, GPA/CGPA, estado acadéico y asesor. |
| Obtiene el horario semanal de clases (días, horcos, códigos de curso, nomres de curso, aulas e instuctores). |
| Obtiene el expediente acadéico de todos los semestres, con cursos, créditos, calificaciones y estadísticas de GPA del semestre. |
| Obtiene los avisos activos del portl. |
| Crea un registro de conexión en memria. |
| Lista todos los registros de conexión guardados. |
Python >= 3.11
uv (recomendado) o pip
# Using uv (recommended)
uv sync
# Or using pip
pip install -e .Copia .env.example a .env e intoduce tus credenciales de METU:
cp .env.example .envEdita .env:
SAIS_USERNAME=your_metu_username
SAIS_PASSWORD=your_metu_password
LOCALE=tr
PORT=8300[!NOTE]
.envestá incluido en.gitignrey nunca se incluirá en un commit.
En este repositorio ya se incluye un opencode.json.
Al iniciar OpenCode dentro de este repositorio:
opencodeOpenCode se conectará automáticamente al servidor MCP metu-sais.
Para usar las herramientas de METU SAIS en cualquier proyecto de OpenCode, añade el servidor a ~/.config/opencode/opencode.jsonc:
{
"mcp": {
"metu-sais": {
"type": "local",
"command": [
"uv",
"--directory",
"/absolute/path/to/metu-sais-mcp",
"run",
"metu-sais-mcp"
],
"enabled": true
}
}
}opencode mcp listDeberías ver:
● ✓ metu-sais connectedPuedes ejecutar el servidor MCP directamente mediante entada/salida estándar:
uv run metu-sais-mcpPara iniciar el servidor FastAPI:
uv run uvicorn api.main:app --port 8300 --reloadLa documentación interactiva de la API estará disponible en:
Swagger UI: http://localhost:8300/docs
Health check: http://localhost:8300/healthz
GET /api/sais/info — Información del estudiante
GET /api/sais/schedule — Horario de clases
GET /api/sais/transcript — Historial del expediente acadéico
GET /api/sais/announements — Avisos del portl
GET|POST|PUT|DELETE /api/connections — CRUD de gestión de conexiones
Ejecuta la suite de pruebas automatizadas con pytst:
uv run pytest -vLa suite de pruebas incluye:
Pruebas unitarias para los anailzadores HTML (parese_student_info, parse_schedule, parse_transcript, parse_announcements).
Pruebas de registro de herramientas MCP y de llamada a herramientas.
Pruebas de endpoints REST de FastAPI.
Pruebas de integración en vivo contra METU SAIS cuando las credenciales estén configuradas.
├── sais/
│ ├── connector.py # Core SAIS authentication, proxy scraping, and HTML parsers
│ └── connections.py # Shared in-memory connection store
├── sais_mcp/
│ └── server.py # MCP stdio server definition and tool registrations
├── api/
│ └── main.py # FastAPI REST API wrapper
├── tests/
│ ├── test_connector.py # Scraper and HTML parser tests
│ ├── test_mcp_server.py# MCP server tests
│ └── test_api.py # FastAPI tests
├── .env.example # Environment variable template
├── opencode.json # OpenCode MCP configuration
├── pyproject.toml # Package dependencies and CLI entrypoints
└── README.md # Project documentationLicencia MIT.
Yeni bir bağlantı kaydı oluşturur.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, but it only says 'creates a new connection record.' It does not disclose duplicate handling, required permissions, idempotency, or any side effects beyond the basic creation action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler, repetition, or unnecessary detail. It is front-loaded and every word earns its place, even though the overall content is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the output schema removes the need to document return values, this is a state-changing tool with no annotations and no usage or parameter guidance. The description lacks context about what a connection record represents, when to create one, and what happens on duplicate or invalid input, so it is not complete enough for confident invocation beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the 'name' or 'description' parameters. It does not clarify what a valid name should be, whether names must be unique, or how the description field is used, so it provides no value beyond the schema's property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a distinct action ('Yeni bir bağlantı kaydı oluşturur' / creates a new connection record) with a clear verb and resource. Among sibling tools, it is the only create-style action, so an agent can distinguish it from list_connections and the various get_* tools without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to use this tool versus list_connections or other siblings. It only defines the action, leaving the agent to infer prerequisites, typical triggers, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
METU SAIS öğrenci portalındaki güncel duyuruları alır.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It signals a read-only retrieval action ('alır') and restricts scope to 'current' announcements, but it does not mention authentication needs, caching, or any other operational traits. This is acceptable for a zero-parameter fetch but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the source and content of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is very simple (no parameters, output schema present), so the description covers the basic action. However, it omits any context about whether an existing connection or authentication is required, which is relevant given sibling tools create_connection and list_connections. The absence of annotations makes this a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description adds no conflicting parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('alır' / gets) and the resource ('METU SAIS öğrenci portalındaki güncel duyurular' / current announcements from the METU SAIS student portal). It is specific but does not explicitly differentiate from sibling tools like get_schedule or get_transcript, though the announcement subject is distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The name and resource imply 'use when you need announcements,' but the description does not state this or mention sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
METU SAIS'ten haftalık ders programını alır. Belirli bir dönem kodu (ör. '20251|1') verilebilir.
| Name | Required | Description | Default |
|---|---|---|---|
| semester | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure responsibility. It mentions an optional semester code but does not disclose default behavior when omitted, authentication needs, rate limits, or any other operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the main purpose front-loaded and the optional parameter explained second. Every word earns its place; there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with an output schema and one optional parameter, the description is adequate for basic invocation. However, it lacks usage context and default behavior, making it minimally viable rather than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description partially compensates with a concrete example semester code ('20251|1') and clearly indicates the parameter is optional. It does not explain what null means or fully define the accepted format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('alır' – retrieves) and a specific resource: the weekly course schedule from METU SAIS. It is clearly distinct from sibling tools like get_transcript and get_announcements, though it does not explicitly contrast itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives, and there are no exclusions or conditions. An agent must infer usage solely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
METU SAIS'ten öğrenci temel bilgilerini, danışmanını, GPA/CGPA ve kayıt durumunu alır.
| Name | Required | Description | Default |
|---|---|---|---|
| semester | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys a read-only retrieval operation and lists the data included, which is useful behavioral content. However, with no annotations provided, it does not disclose connection/auth requirements, semester handling, or possible error behavior, leaving meaningful gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the source and the key data scopes, so it is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema and no annotations, the description is incomplete because it omits the only parameter's semantics and any dependency on connections. The output schema may explain return structure, but behavioral and invocation context remain underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions the 'semester' parameter. The agent receives no explanation of the semester value format, whether it is needed, or how it affects the returned GPA/CGPA and registration status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('alır') and names a concrete resource: student basic info, advisor, GPA/CGPA, and registration status from METU SAIS. It is clear what the tool returns, though it does not explicitly contrast itself with sibling tools like get_schedule or get_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool instead of alternatives such as get_transcript or get_schedule. There are no conditions, exclusions, or prerequisites mentioned, so the agent must infer usage solely from the tool name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
METU SAIS'ten tüm dönemleri, alınan dersleri, harf notlarını, kredileri ve GPA geçmişini (transkript) alır.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly says the tool retrieves all semesters and the full transcript data, making the operation's scope clear. It does not discuss auth, rate limits, or failure modes, but for a zero-parameter read operation the enumerated retrieval behavior is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence leads with the source and then lists the exact data elements. There is no filler, no repetition of the tool name, and every phrase adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter getter with an output schema, the description covers the source and contents well, and return values are likely already documented by the output schema. The only minor gap is that it does not mention whether an existing connection is required, especially given sibling tools like create_connection and list_connections.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics for the description to clarify. The baseline score of 4 applies, and the description appropriately focuses on what data is returned rather than input options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('alır' - gets), a specific resource (METU SAIS transcript), and enumerates the exact contents: all semesters, courses, letter grades, credits, and GPA history. This clearly differentiates it from siblings like get_student_info and get_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool should be used when a transcript is needed, but it never explicitly states when to use it versus alternatives or when not to use it. Sibling tools such as get_student_info and get_schedule could partially overlap, so an explicit routing hint would help, but the context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mevcut tüm bağlantı kayıtlarını listeler.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It communicates a read-only 'list all' operation, which is useful, but it adds no further behavioral context such as ordering, scope limitations, or pagination. The output schema presumably covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word contributes to identifying the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only list tool with an output schema, the description is largely complete. The main gap is that the term 'connection records' is left ambiguous, but the operation itself is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and there are no parameter semantics to explain. The baseline for zero-parameter tools is 4, and the description does not need to compensate for anything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('listeler'/'lists') and identifies the resource ('bağlantı kayıtları'/'connection records'), making the tool's purpose reasonably clear. It does not fully define what a 'connection' is in this domain, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool instead of siblings like create_connection. There is no stated context, prerequisite, or exclusion, so the agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_connectionget_announcementsget_scheduleget_student_infoget_transcriptlist_connectionsScored across 6 tools
Each tool targets a clearly distinct resource or action: student info, schedule, transcript, announcements, and connection records. There is no meaningful overlap that would cause an agent to select the wrong tool.
Tool names follow a consistent snake_case verb_noun pattern: get_student_info, get_schedule, get_transcript, get_announcements, create_connection, list_connections. The only minor variation is singular vs plural nouns, but the pattern is predictable.
Six tools is a well-scoped set for a student portal MCP server. It covers the core read operations and adds connection management without bloating the surface.
The student-facing read operations are solid, but connection management is incomplete: create_connection and list_connections have no corresponding update or delete operation, creating a lifecycle dead end. Minor gaps like course-level detail or exam results are less critical but still absent.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Every service you connect, one MCP endpoint for all your AI tools. Sign in once.
