Asistente de Desarrollo para Estudiantes de IA — Servidor MCP

Un servidor de Model Context Protocol de calidad de producción que proporciona a un asistente de IA acceso unificado a tus issues de GitHub, tus plazos académicos (LMS) y un rastreador de tareas personales — para que pueda responder preguntas como "¿En qué debería trabajar hoy?" con una respuesta real y priorizada.

Construido con Python 3.12+, el SDK oficial de MCP para Python (v2), separación de servicios estilo FastAPI, SQLite y httpx. Totalmente probado con APIs externas simuladas — no se necesitan credenciales reales para ejecutar la suite.

Índice

• Resumen del proyecto

• Funcionalidades — las herramientas MCP

• Arquitectura

• Stack tecnológico

• Instalación

• Configuración

• Ejecutar el servidor

• Conectar un cliente de IA

• Ejemplo de uso

• Integración de API

• Base de datos

• Pruebas

• Seguridad

• Limitaciones

• Mejoras futuras

• Arquitectura del proyecto

• Escenario de demostración

• Puntos clave para entrevistas

Resumen del proyecto

El problema. El trabajo de un estudiante-desarrollador vive en tres lugares desconectados: tareas de código en GitHub, asignaciones y exámenes en un LMS universitario, y tareas personales dispersas en notas. Las prioridades se deciden por memoria, por lo que se escapan cosas.

La solución. Un servidor MCP que expone las tres fuentes como herramientas pequeñas, bien descritas y fuertemente tipadas. Un asistente de IA las lee y razona sobre todas a la vez: puede extraer tus issues asignados, los plazos de esta semana, tus tareas pendientes, detectar elementos vencidos, construir un resumen priorizado — y mutar los sistemas (crear/cerrar issues, crear tareas, importar plazos por lotes) con la misma interfaz.

Estado. Esta es una implementación de calidad de portafolio de una herramienta de productividad personal. Todo funciona de extremo a extremo; la integración con el LMS está deliberadamente simulada detrás de una interfaz intercambiable (ver Limitaciones).

Funcionalidades — las herramientas MCP

Quince herramientas de alcance limitado. Cada una tiene un nombre claro, una descripción que la IA lee para decidir cuándo llamarla, entradas validadas y una salida predecible:

GitHub (4 herramientas)

LMS / plazos académicos (3 herramientas)

Rastreador de tareas (8 herramientas)

Todas las herramientas devuelven la misma forma JSON para que un agente pueda analizar los resultados de manera confiable:

{ "ok": true,  "data": { "...": "..." }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

Arquitectura

flowchart TB
    subgraph Host["AI Client (e.g. Claude Desktop)"]
        Agent["Assistant / Agent"]
    end
    subgraph MCP["MCP Protocol (stdio)"]
        S["MCPServer (mcp SDK v2)"]
    end
    subgraph App["app/"]
        Tools["tools/ · 15 thin tool functions"]
        Services["services/ · GitHub · LMS · Task"]
        Repo["TaskRepository"]
        DB[("SQLite")]
        Mock["MockLMSService"]
    end
    Ext["GitHub REST API v3"]
    Agent -->|tools/list · tools/call · server/discover| S
    S --> Tools
    Tools --> Services --> Repo --> DB
    Services --> Ext
    Services --> Mock

La regla de oro en este código base: la capa MCP es solo adaptadores. Cada función de herramienta valida las entradas mediante su firma de tipo, llama a un servicio y renderiza el resultado. Ninguna lógica de negocio vive en las funciones de herramienta.

Stack tecnológico

Instalación

Requisitos: Python 3.12+ y git. (El SDK MCP en sí necesita ≥3.10; este proyecto apunta a 3.12.)

Windows (PowerShell)

cd "C:\Users\ASUS\mcp project"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Si Activate.ps1 está bloqueado por la política de ejecución:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS / Linux

cd mcp-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Configuración

Copia el archivo de marcadores de posición y completa tus valores:

cp .env.example .env     # Windows:  copy .env.example .env

Crear un token de GitHub → GitHub → Configuración → Configuración de desarrollador → Tokens de acceso personal → Tokens de grano fino → Generar nuevo token → selecciona solo los repositorios que necesites → concede solo Issues: Lectura y Escritura.

⚠️ .env está ignorado por git. Nunca lo confirmes. .env.example contiene solo marcadores de posición.

Ejecutar el servidor

1. Inicializar la base de datos y sembrar datos de demostración

python -m scripts.seed_demo

Esto crea data/tasks.db e inserta algunas tareas de demostración realistas (una deliberadamente vencida).

2. Ejecutar el servidor MCP

python -m app.server

El servidor se inicia sobre stdio (el predeterminado para clientes MCP de escritorio) y permanece ejecutándose hasta que se detiene.

Desarrollo y depuración

El SDK incluye una CLI y un inspector interactivo:

mcp dev app/server.py        # launch + open the MCP Inspector in a browser
mcp run app/server.py        # run the server (same behavior as python -m app.server)

Conectar un cliente de IA

Los servidores MCP locales se ejecutan sobre stdio: el cliente de IA inicia tu proceso del servidor y se comunica con él a través de stdin/stdout. El formato de configuración es el bloque mcpServers del cliente.

Claude Desktop (Windows)

Edita %APPDATA%\Claude\claude_desktop_config.json (ábrelo mediante Configuración → Desarrollador → Editar configuración), cierra completamente y vuelve a abrir:

{
  "mcpServers": {
    "ai-student-assistant": {
      "command": "C:\\Users\\ASUS\\mcp project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\ASUS\\mcp project\\app\\server.py"]
    }
  }
}

Requisitos:

• Rutas absolutas — Claude Desktop no hereda tu PATH de shell ni el directorio de trabajo.

• Usa where python / where git para confirmar la ruta exacta del intérprete.

• Después de guardar, reinicia completamente Claude Desktop, luego busca en el menú de conectores/caja de mensajes el servidor y sus herramientas.

• Registros si falla: %APPDATA%\Claude\logs\mcp*.log.

Alternativas

• Inspector MCP (sin configuración): mcp dev app/server.py te da una interfaz gráfica para llamar a cada herramienta manualmente — ideal para demostraciones.

• Cursor — .cursor/mcp.json usa la misma forma de mcpServers.

• El servidor es independiente del transporte: el mismo MCPServer puede servirse sobre Streamable HTTP más tarde (ver Mejoras futuras).

Ejemplo de uso

Usuario: ¿Qué issues de GitHub están abiertos actualmente?

El agente llama a get_open_issues (sin repositorio → issues asignados a ti), luego resume:

Tienes 2 issues abiertos asignados a ti: "Corregir error de inicio de sesión" (#1, bug) y "Añadir pipeline de CI" (#2).

Usuario: ¿Qué asignaciones vencen en los próximos 7 días?

El agente llama a get_upcoming_deadlines con start/end calculados a partir de hoy:

Vencen esta semana: Cuestionario 3 (Matemáticas, 12 de agosto), Borrador de propuesta de proyecto (ING101, 11 de agosto), Asignación de recorrido de grafos (CS101, 13 de agosto).

Usuario: Crea tareas para esas asignaciones.

El agente llama a create_tasks_from_deadlines (el servidor ya respeta la deduplicación por source/source_id, por lo que volver a ejecutar nunca duplica):

Se crearon 3 tareas. Se omitieron 0 (sin duplicados).

Usuario: ¿En qué tareas debería trabajar primero?

El agente llama a get_workload_summary y get_overdue_tasks, luego razona sobre prioridad + fechas de vencimiento:

Primero: "Corregir test inestable en el pipeline de CI" (VENCIDA, alta). Luego: Borrador de propuesta de proyecto (vence mañana), Examen 3 (vence en 2 días)...

Integración con API

GitHub

• Endpoints: GET /issues (asignadas a ti), GET|POST /repos/{owner}/{repo}/issues, GET|PATCH /repos/{owner}/{repo}/issues/{number}.

• Auth: Authorization: Bearer <GITHUB_TOKEN>. Se permite acceso anónimo para repositorios públicos; un 401 luego devuelve un error claro de "se requiere autenticación".

• Límites de velocidad: Se mapearon 403-con-x-ratelimit-remaining: 0 y 429 a un error rate_limited.

• Pull requests: el endpoint de issues también devuelve PRs; se filtran mediante la clave pull_request.

• Todos los estados de red/timeout/error se traducen a excepciones de dominio (ver Seguridad).

LMS

No se asumió ninguna API de LMS universitaria legítima/accesible para este proyecto, por lo que el LMS vive detrás de una interfaz pequeña (LMSService) con una implementación mock realista (MockLMSService) que:

• siembra un catálogo de cursos con fechas de vencimiento relativas a hoy,

• valida cursos (curso desconocido → not_found),

• valida fechas y rangos (entrada incorrecta → invalid_input).

Agregar un proveedor real más tarde = implementar la misma interfaz + establecer LMS_PROVIDER=real. No se scrapingaron páginas protegidas; nada evita la autenticación. El mock se comporta como un servicio real para que el resto de la aplicación se pruebe sin modificaciones.

Base de datos

Archivo SQLite en DATABASE_PATH (por defecto data/tasks.db), una tabla en MVP:

CREATE TABLE tasks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT    NOT NULL,
    description TEXT,
    status      TEXT    NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','completed')),
    priority    TEXT    NOT NULL DEFAULT 'medium'
                    CHECK (priority IN ('low','medium','high','urgent')),
    due_date    TEXT,                      -- ISO-8601 (date or timestamp)
    source      TEXT,                      -- 'github' | 'lms' | NULL
    source_id   TEXT,                      -- e.g. GitHub issue number
    source_url  TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
);

CREATE INDEX idx_tasks_status    ON tasks(status);
CREATE INDEX idx_tasks_due_date  ON tasks(due_date);
CREATE INDEX idx_tasks_priority  ON tasks(priority, due_date);

CREATE UNIQUE INDEX uq_tasks_source ON tasks(source, source_id)
    WHERE source IS NOT NULL AND source_id IS NOT NULL;

Por qué cada decisión es importante:

• Índice único parcial en (source, source_id) — SQLite trata los NULL como distintos en un UNIQUE normal, lo que permitiría que se cuelen importaciones duplicadas y prohibiría múltiples tareas "personales" (sin fuente). El índice parcial WHERE source IS NOT NULL hace que las importaciones sean idempotentes a nivel de base de datos, exactamente donde debe estar. Esto es lo que hace que create_task_from_issue / create_tasks_from_deadlines sean seguras de llamar repetidamente.

• status/priority como TEXT + CHECK — SQLite no tiene enums; el CHECK proporciona integridad mientras que los enum.Enum de Python reflejan los valores para seguridad de tipos.

• Marcas de tiempo ISO-8601 UTC como cadenas ordenables — el orden lexicográfico == orden cronológico, sin ambigüedad de zona horaria, compatible con JSON.

• source + source_id + source_url conservan la procedencia para que una tarea siempre pueda rastrearse hasta el issue o la asignación de la que provino.

Pruebas

pytest          # runs the whole suite: mocked GitHub, mock LMS, SQLite tasks, MCP client

Alcance (tests/):

Las herramientas MCP se prueban contra una conexión de protocolo real usando el cliente en memoria del SDK (async with Cliente(servidor)) — el mismo patrón que el TestCliente de FastAPI. Sin subproceso, sin puerto, sin credenciales.

Seguridad

• Los secretos viven solo en variables de entorno (.env está en gitignore; .env.example tiene marcadores de posición).

• Mínimo privilegio: un PAT de GitHub de grano fino limitado a Lectura y Escritura de Issues en repos específicos — nunca el ámbito repo completo.

• Sin registro de secretos: un filtro de redacción elimina los valores de Authorization de los registros; y como el servidor no imprime nada en stdout (el registro va a stderr), el flujo del protocolo stdio se mantiene limpio.

• Validación de entradas: Pydantic en el límite de la herramienta + validación de domínio en los servícios.

• SQL paramétrizado mediante SQLAlchemy — sin consultas construidas con cadenas.

• Exposión controlada de errores: la IA recibe errores estructurados (código, mensaje); los rastros de pila completos van solo a los registros del servidor.

• Exposición mínima del clente: el token .env es leído por el proeso del servidor, no se pasa a través de la configuracion del clente.

Ver también la discusión enfocada en entevistas en Puntos de Conversación para Entevistas.

Limitaciones

Advertencias honestas, a propósito:

• El LMS es mock. LMS_PROVIDER=mock es el único proveedor. Se debe agregar un adaptador de API real, un caledario exportado u otra fuente de datos autorizada para reemplazarlo (de forma intercambiable, mediante la interfaz LMSService).

• SQLite es para un solo usuario. Sin garantías de concurrencia, sin acceso a la red, sin replicación en el sistema. Idea para un asiente personal.

• Sin OAuth / sin transporte HTTP aún. El token de GitHub es un secreto estático; el servidor se ejecuta sobre stdio. Adecuado para uso local personal; el uso remoto/alojado necesitaría OAuth y HTTP Stremable.

• La creción de issues no admite asignación ni markdown en el cuerpo explícitamente más allá del texto lbre — se mantuvo intencionalmente pequeño.

• Granularidad de una hora en los plazos — sin conversión de zona horaria; las fechas se comparan en la forma ISO-8601 proporcionada por el usuario.

• Las importaciones describen elementos fuente mutables como instantáneas: si un issue de GitHub se edita posteriormente, una tarea ya creada no se actualiza (un comportamiento diseñado, no un error).

Mejoras futuras

• Adaptador LMSService real (API oficial o exportación de caledario .ics)

• Integración con Google Caledar para plazosmn* Notificaciones Slack/Teams para tareas vencidas

• Backend de PostgreSQL (el repositorio ya lo abstrae)

• OAuth para GitHub + transporte HTTP Streamable + implementación Docker

• Tabla de historial/auditoría de tareas; las actualizaciones de issues se resincronizan en tareas

• Flujos de trabajo de agente más ricos (auto-triaje, informe semanal de "standup")

Arquitectura del proyecto

Capas, en orden de dependencia:

app/tools       MCP adapters — type-hinted params, docstrings as descriptions, guard() → {ok, data, error}
app/services    GitHubService · LMSService (mock) · TaskService — business logic + cross-service workflows
app/database    Database (engine/session) · TaskRepository (all SQL)
app/models      SQLAlchemy ORM (Task) · Pydantic schemas (TaskCreate/Out, GitHubIssue, Deadline)
app/config.py   validated env config
app/exceptions  domain error hierarchy → AI-readable codes

Inyección de dependencias: app/server.py es la raíz de composición — construye config → base de datos → servicios → MCPServer, y registra funciones de herramienta con los servícios que necesitan. Nada es glbal; las prubas mnan el mismo gafo con falso.

Flujo de errores: herramienta → servicio → repositorio/API lanza una StudentAssistantError → guard() renderiza {ok: false, error: {code, message}}. Las excepciones inesperadas se guadan (stderr) y se devuelven como un mensaje genérico internal_error.

Escenario de demostración

1. Crear un token de GitHub de grano fino y establecer GITHUB_TOKEN en tu .env.

2. Sembrar la base de datos de tareas: python -m scripts.seed_demo (crea algunas tareas, una vencida).mn3. Iniciar el servidor: python -m app.server (o mcp dev app/server.py para iniciar el Inspctor).m4. Conectar Claude Desktop / Inspctor al servidor.

3. Preguntar: "¿En qué necesito trabajar esta semana?" → el agente llama a get_workload_summary, combina los issues abiertos de GitHub + los plazos próxmos + las tareas pending/vencidas, y da una respusta priotizada.

4. Preguntar: "Crear tareas para todas las asignaciones que vencen esta semana." → el agente llama a create_tasks_from_deadlines.

5. Verificar en la base de datos:

   sqlite3 data/tasks.db "SELECT title, due_date, source FROM tasks ORDER BY due_date;"

   → aparecen nuevas filas con source = 'lms', una por plazo. Vuelve a ejecutar la misma pregunta y la herramienta informa skipped en vez de duplicar.

***mn## Puntos de conversación para entevistas

Prepárate para defender estas deiciones: m1. ¿Por qué MCP? Es un protocolo estandadizado para que un sol servidor funcione con cualquier clente de IA; las heramientas se descubren (tols/list), se llaman (tols/call) y se desciben al modelo — los nombres y las desciciones son un contrato de UX para LLMs. 2. ¿Por qué el SDK de MCP v2 actual? El SDK renombró FastMCP → MCPServer y ahora sirve tanto la revisión del protoco de 2025 como la de 2026-07-28 desde un solo proeso; pip install mcp instalá la v2. Contruir sobre la línea mntenida (no el mntenimiento de v1) es la eleción defendible.mn3. Capa de MCP delgada / capa de servicos. Las funciones de heramienta son adaptadores; la lógica vive en servicos detrás de interfaces. Esto es lo que hace que GitHúb, LMS y las tareas sean plugables y probables sin una red.mn4. Índice único parcial para idempotencia. Explicar por qué SQLite necesita un índice parcial para (source, source_id) y cómo hace que create_task_from_issue/create_tasks_from_deadlines sean seguras como una demostración pequeña y razonada de profundidad en SQL.mn5. Ambigüedad de 403 en GitHúb. La diferecia entre Probido y limtado por velocidad se disipa mediante la cabecera de respusta x-ratelimit-remaining — una sutileza real de integración con API, no un folclore.mn6. Tokens de mínimo privilegio. PAT de grano fino con solo Issues: Read & Write vs. un token clásico de ámbito repo. Saber el "por qué" de memria.mn7. Taxonomía de errores. Una jeaía de excepciones mapeada a códigos estables legibles por AI, con los rastros de pila confinados a los registros. La fiabilidad es un objetivo de dseño, no una reflexión.mn8. Pruebas de la capa de protocolo. Cliente(servidor) en memria significa que el cableado de MCP se prueba exactamente como un cliente lo usa. m9. Alcance honesto. El LMS está explicitamente mockeado; SQLite es single-user — "herramienta de productividad personal", no una afirmación de un producto multi-usuario empresarial.

Licencia

MIT — ver LICENSE. Copyright (c) 2026 Mahendra Vattikuti.