nseap-mcp

NSEAP Education Platform × Cogseed Connector — stdio MCP Server. Wraps the platform HTTP Agent protocol (x-api-key), providing local deliverable checking and a submit-review-notify closed loop toolset.

Positioning

• Local tools (offline-capable, non-authoritative): nseap_check_deliverables — checks file completeness in the local workspace against challenge deliverable requirements (supports * wildcards)

• Platform tools (authoritative, auditable): challenge queries / my submissions / task polling / project submission

• Architecture red lines (inherited from platform constraints):

  • Submissions must go through the platform message bus (Agent channel, no fallback)

  • No tools that write directly to Feishu sheets are exposed

  • from_agent is fixed to student-companion-<student-id>, not forgeable via tool arguments

  • Long-running operations always follow submit → task_id → polling

Related MCP server: MCP Security Server

Tool list (13 tools, trimmed by role)

Student role (12 tools):

Teacher role (+1): nseap_publish_challenge — publish challenge (via message bus, Feishu group announcement)

Installation & Running

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

Distribution (M1, recommended)

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

The CogSeed connector command points directly to this file; no nseap-mcp project environment needed.

Environment variables: see .env.example.

Local development (mock mode, no platform credentials needed)

NSEAP_MOCK=1 NSEAP_STUDENT_ID=test-student pnpm dev

Connecting to CogSeed

1. In CogSeed, open Connector Settings → Add Custom MCP (custom transport, stdio)

2. Fill in:

   • display_name: NSEAP Learning Platform

   • command: npx tsx /path/to/nseap-mcp/src/index.ts (or the built node /path/to/nseap-mcp/dist/index.js)

   • env (API key stored encrypted via secrets_enc):

     • NSEAP_SERVER_URL = platform address

     • NSEAP_API_KEY = student's api_key (obtained by downloading NSEAP-config-{student-id}.json after logging into the platform)

     • NSEAP_STUDENT_ID = student ID

     • NSEAP_COHORT = class

3. Confirmation dialog (shows the exact command to be executed) → takes effect after user consent

4. The model uses these tools via list_connector_tools / call_connector_tool

Testing

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

Error codes

Directory structure

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

License

MIT