nseap-mcp

NSEAP 教育平台 × Cogseed 连接器 —— stdio MCP 服务器。封装平台 HTTP 代理协议（x-api-key），提供本地交付物检查与提交-评审-通知闭环工具。

定位

• 本地工具（离线可用，非权威）：nseap_check_deliverables —— 按挑战交付物要求（支持 * 通配符）在本地工作区检查文件完整性

• 平台工具（权威，可审计）：挑战查询 / 我的提交 / 任务轮询 / 提交项目

• 架构红线（继承平台约束）：

  • 提交必须经平台消息总线（代理通道，不降级）

  • 不暴露任何直写飞书表的工具

  • from_agent 固定为 student-companion-<学号>，不接受工具参数伪造

  • 长耗时一律 submit → task_id → 轮询

Related MCP server: MCP Security Server

工具列表（13 个，按角色裁剪）

学生角色（12 个）：

教师角色（+1）：nseap_publish_challenge —— 发布挑战（走消息总线，飞书群公告）

安装与运行

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

分发（M1，推荐）

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

CogSeed 连接器 command 直接指向该文件，无需 nseap-mcp 项目环境。

环境变量见 .env.example。

本地开发（mock 模式，无需平台凭证）

NSEAP_MOCK=1 NSEAP_STUDENT_ID=test-student pnpm dev

接入 CogSeed

1. CogSeed 中打开连接器设置 → 添加自定义 MCP（custom transport, stdio）

2. 填入：

   • display_name: NSEAP 学习平台

   • command: npx tsx /path/to/nseap-mcp/src/index.ts（或构建后的 node /path/to/nseap-mcp/dist/index.js）

   • env（API key 走 secrets_enc 加密存储）:

     • NSEAP_SERVER_URL = 平台地址

     • NSEAP_API_KEY = 学生的 api_key（平台登录后下载 NSEAP-config-{学号}.json 获取）

     • NSEAP_STUDENT_ID = 学号

     • NSEAP_COHORT = 班级

3. 确认弹窗（展示将执行的精确命令）→ 用户同意后生效

4. 模型经 list_connector_tools / call_connector_tool 使用这些工具

测试

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

错误码

目录结构

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

许可

MIT