nseap-mcp

NSEAP 교육 플랫폼 × Cogseed 커넥터 —— stdio MCP Server. 플랫폼 HTTP Agent 프로토콜（x-api-key）을 래핑하여 로컬 산출물 검사 및 제출-평가-알림 폐쇄 루프 도구를 제공합니다.

포지셔닝

• 로컬 도구（오프라인 사용 가능, 비공식）：nseap_check_deliverables —— 챌린지 산출물 요구사항에 따라（* 와일드카드 지원）로컬 작업공간에서 파일 무결성을 검사합니다

• 플랫폼 도구（공식, 감사 가능）：챌린지 조회 / 내 제출 / 작업 폴링 / 프로젝트 제출

• 아키텍처 레드라인（플랫폼 제약 상속）：

  • 제출은 반드시 플랫폼 메시지 버스를 경유해야 합니다（Agent 채널, 다운그레이드 불가）

  • 飞书表에 직접 쓰는 도구를 노출하지 않습니다

  • 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