Skip to main content
Glama

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개):

도구

설명

nseap_check_deliverables

로컬 산출물 와일드카드 검사(오프라인)

nseap_prepare_submission

로컬 제출 사전 점검 보고서(액션 항목+제출 초안)

nseap_list_challenges

게시된 챌린지 목록

nseap_get_challenge

단일 챌린지 상세(산출물/rubric/평가 차원/레드라인)

nseap_list_my_submissions

내 제출 기록

nseap_get_task

비동기 작업 상태(제출 후 폴링)

nseap_submit_project

프로젝트 제출(사전 점검→Envelope→task_id)

nseap_get_evaluation

평가 상세(AI/교사/동료, 항목별 점수+장단점)

nseap_submit_review

평가 제출(peer는 플랫폼 할당 검증 / teacher는 메시지 버스 경유)

nseap_get_dashboard

진행 통계(챌린지/제출/완료/평가 대기)

nseap_notify

飞书 알림 트리거(학생 DM/반 그룹 채팅)

nseap_health

플랫폼 연결 확인(지연/모드)

교사 역할(+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 模式,无需凭证)

오류 코드

code

의미

AUTH_FAILED

api_key 무효/만료

FORBIDDEN

권한 없음

CONFLICT

중복 제출(60초 중복 방지 창)

BUS_UNAVAILABLE

메시지 버스 사용 불가

NOT_FOUND

작업 없음/만료됨

NETWORK_ERROR

플랫폼에 연결할 수 없음

BAD_REQUEST

검증 실패(예: 산출물 누락)

INTERNAL

알 수 없는 오류

디렉터리 구조

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers