nseap-mcp

NSEAP-Bildungsplattform × Cogseed-Connector – stdio-MCP-Server. Kapselt das HTTP-Agent-Protokoll der Plattform (x-api-key) und bietet lokale Deliverable-Prüfung sowie einen Submit-Review-Benachrichtigungs-Kreislauf.

Positionierung

• Lokale Tools (offline nutzbar, nicht autoritativ): nseap_check_deliverables – prüft die Dateivollständigkeit im lokalen Workspace gemäß den Deliverable-Anforderungen der Challenge (unterstützt *-Wildcards)

• Plattform-Tools (autoritativ, auditierbar): Challenge-Abfrage / meine Einreichungen / Task-Polling / Projekt-Einreichung

• Architektur-Rotlinien (übernommen aus Plattform-Constraints):

  • Einreichungen müssen über die Plattform-Message-Bus (Agent-Kanal, kein Downgrade) erfolgen

  • Keine Tools, die direkt in Feishu-Tabellen schreiben

  • from_agent ist fest auf student-companion-<学号> gesetzt, keine Fälschung über Tool-Parameter

  • Langlaufende Vorgänge immer submit → task_id → Polling

Related MCP server: MCP Security Server

Tool-Liste (13, nach Rolle zugeschnitten)

Studentenrolle (12):

Lehrkraftrolle (+1): nseap_publish_challenge – Challenge veröffentlichen (über Message-Bus, Feishu-Gruppenankündigung)

Installation und Ausführung

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

Verteilung (M1, empfohlen)

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

Der CogSeed-Connector-Befehl zeigt direkt auf diese Datei, keine nseap-mcp-Projektumgebung erforderlich.

Umgebungsvariablen siehe .env.example.

Lokale Entwicklung (Mock-Modus, keine Plattform-Anmeldedaten erforderlich)

NSEAP_MOCK=1 NSEAP_STUDENT_ID=test-student pnpm dev

Anbindung an CogSeed

1. In CogSeed Connector-Einstellungen öffnen → Benutzerdefinierten MCP hinzufügen (custom transport, stdio)

2. Ausfüllen:

   • display_name: NSEAP 学习平台

   • command: npx tsx /path/to/nseap-mcp/src/index.ts (oder nach dem Build node /path/to/nseap-mcp/dist/index.js)

   • env (API-Key wird verschlüsselt über secrets_enc gespeichert):

     • NSEAP_SERVER_URL = Plattformadresse

     • NSEAP_API_KEY = api_key des Studenten (nach Login über NSEAP-config-{学号}.json von der Plattform herunterladen)

     • NSEAP_STUDENT_ID = Matrikelnummer

     • NSEAP_COHORT = Klasse

3. Bestätigungsdialog (zeigt den exakt auszuführenden Befehl) → wird nach Zustimmung des Benutzers wirksam

4. Das Modell nutzt diese Tools über list_connector_tools / call_connector_tool

Tests

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

Fehlercodes

Verzeichnisstruktur

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 冒烟

Lizenz

MIT