nseap-mcp

Conector NSEAP Plataforma Educativa × Cogseed — servidor MCP stdio. Envuelve el protocolo HTTP Agent de la plataforma (x-api-key) y proporciona herramientas de verificación local de entregables y un ciclo cerrado de envío-revisión-notificación.

Posicionamiento

• Herramientas locales (disponibles sin conexión, no autoritativas): nseap_check_deliverables — verifica la integridad de archivos en el espacio de trabajo local según los requisitos de entregables del desafío (admite comodines *)

• Herramientas de plataforma (autoritativas, auditables): consulta de desafíos / mis envíos / sondeo de tareas / envío de proyectos

• Línea roja de arquitectura (hereda restricciones de la plataforma):

  • Los envíos deben pasar por el bus de mensajes de la plataforma (canal de agente, sin degradación)

  • No se expone ninguna herramienta que escriba directamente en tablas de Feishu

  • from_agent está fijo como student-companion-<número de estudiante>, no acepta falsificación mediante parámetros de herramienta

  • Las operaciones de larga duración siempre usan submit → task_id → sondeo

Related MCP server: MCP Security Server

Lista de herramientas (13, recortadas por rol)

Rol de estudiante (12):

Rol de profesor (+1): nseap_publish_challenge — publicar desafío (a través del bus de mensajes, anuncio en grupo de Feishu)

Instalación y ejecución

pnpm install          # Node ≥20
pnpm dev              # 开发模式（tsx 直跑）
pnpm build && pnpm start   # 生产模式（dist/）
pnpm bundle           # 单文件打包（dist-bundle/nseap-mcp.mjs，自包含无 node_modules）

Distribución (M1, recomendado)

pnpm bundle
# 产物 dist-bundle/nseap-mcp.mjs（1.1MB 自包含），任意有 Node ≥20 的机器：
node dist-bundle/nseap-mcp.mjs

El comando del conector CogSeed apunta directamente a este archivo, sin necesidad del entorno del proyecto nseap-mcp.

Variables de entorno en .env.example.

Desarrollo local (modo mock, sin credenciales de plataforma)

NSEAP_MOCK=1 NSEAP_STUDENT_ID=test-student pnpm dev

Integración con CogSeed

1. En CogSeed, abrir configuración de conectores → agregar MCP personalizado (custom transport, stdio)

2. Completar:

   • display_name: NSEAP Plataforma de Aprendizaje

   • command: npx tsx /path/to/nseap-mcp/src/index.ts (o node /path/to/nseap-mcp/dist/index.js tras compilar)

   • env (la API key se almacena cifrada con secrets_enc):

     • NSEAP_SERVER_URL = dirección de la plataforma

     • NSEAP_API_KEY = api_key del estudiante (obtener descargando NSEAP-config-{número de estudiante}.json tras iniciar sesión en la plataforma)

     • NSEAP_STUDENT_ID = número de estudiante

     • NSEAP_COHORT = clase

3. Diálogo de confirmación (muestra el comando exacto a ejecutar) → se activa tras el consentimiento del usuario

4. El modelo usa estas herramientas mediante list_connector_tools / call_connector_tool

Pruebas

pnpm typecheck   # tsc 零错误
pnpm test        # 33 个单元测试（含 5 个契约测试）
pnpm smoke       # 冒烟（握手/12工具注册/预检/拦截）
pnpm demo:student  # 学生全流程预演（9 步，mock 模式，无需凭证）
pnpm demo:teacher  # 教师全流程预演（5 步，mock 模式，无需凭证）

Códigos de error

Estructura de directorios

src/
  index.ts        # MCP Server 主入口（6 工具注册）
  config.ts       # 环境变量加载 + 脱敏 + 身份固定
  errors.ts       # NseapError + 错误码表
  client.ts       # 平台 HTTP 客户端（重试/限流/mock）
  tools/
    local.ts      # 交付物检查（纯本地）
    read.ts       # 只读工具
    submit.ts     # 提交工具
test/             # 单元测试
scripts/smoke-m0.sh  # M0 冒烟

Licencia

MIT