Kampus

The Korean School Information Toolkit 한국 학교 정보 통합 도구

One engine, three surfaces — interactive shell · raw CLI · MCP server

Kampus merges two Korean school data providers — Comcigan (practical timetables) and NEIS Open API (official government data) — into one unified engine. Use it as an interactive terminal app, pipe it through scripts with --json, or connect it as an MCP server for AI agents and integrations.

Every response carries transparent data status — official-full, official-limited, or unofficial — so you always know where your data came from and how complete it is.

Three Surfaces

🖥️ Human Shell

Full interactive terminal experience.

• Mission-control dashboard
• School search with quick picks
• Timetable & meal panels
• Profile & settings management
• IME-safe Korean text input
• Guided easy onboarding mode
• Live provider state badges

Launch:

kps · kps human · kps easy

⚡ Raw CLI

Scriptable commands, structured output.

• Complete school, timetable, meal commands
• 6 structured output formats
• Auth, config & profile management
• Built-in diagnostics & debugging
• Structured JSON error responses
• Default school & profile support

Example:

kps class week --json

🔌 MCP Server

Typed tools for agents & integrations.

• 13 structured MCP tools
• School, timetable, meals, NEIS
• Timetable snapshot diffing
• Full structuredContent output
• dataStatus on every response

Build & run:

pnpm --filter @kampus/mcp build node packages/mcp/dist/server.js

🚀 Quick Start

Install from npm:

npm install -g kampus
kps --version

Install & verify:

pnpm install
pnpm verify                # lint + typecheck + build + test
pnpm smoke:live            # live provider health check
pnpm smoke:pack:cli        # packaged CLI smoke test

Launch the interactive shell:

pnpm --filter @kampus/cli dev          # auto-detects TTY → human shell
pnpm --filter @kampus/cli dev human    # explicit human shell
pnpm --filter @kampus/cli dev easy     # guided onboarding flow

Run raw commands:

kps school search "<keyword>"
kps class week --school "<school>" --region "<region>" --grade 3 --class 5 --json
kps meals today --school "<school>" --region "<region>" --json
kps neis schedule --school "<school>" --region "<region>" --from 2026-03-01 --to 2026-03-31 --json
kps doctor --live --json

Save a NEIS API key (optional, unlocks full official mode):

kps auth login --api-key "<your-neis-key>"
kps auth status --json

[!TIP] A NEIS key is optional. Without one, you get merged school search, all Comcigan timetable features, and limited official NEIS data. A real key unlocks complete official results and broader dataset queries.

📋 Feature Overview

| Domain | Commands | Provider | Data Status | |:-------|:---------|:---------|:------------| | School Search | school search · school resolve · school info | Comcigan + NEIS | merged | | Student Timetable | class today · class day · class week · next · class-times | Comcigan | unofficial | | Teacher | teacher info · teacher timetable | Comcigan | unofficial | | Meals | meals today · meals week · meals range · meals month | NEIS | official | | Official Datasets | neis classes · majors · tracks · schedule · timetable · classrooms · academies | NEIS | official | | Auth & Config | auth login · status · validate · export · logout | — | — | | Profiles | profile save · list · show · use · remove | — | — | | Diagnostics | doctor · doctor --live · debug provider · debug school · debug neis-dataset | Both | — | | Utilities | export · diff | — | — |

All structured commands support multiple output formats:

| Flag | Format | |:-----|:-------| | --json | JSON | | --format yaml | YAML | | --format csv | CSV | | --format table | Table | | --format markdown | Markdown | | --format ndjson | Newline-delimited JSON |

Default output is human (formatted for terminal reading).

| Tool | Description | |:-----|:-----------| | search_schools | Merged school search | | get_school_info | Normalized school info | | get_student_timetable_today | Today's class schedule | | get_student_timetable_day | Specific day schedule | | get_student_timetable_week | Full weekly timetable | | get_teacher_timetable | Teacher's schedule | | get_teacher_info | Teacher info | | get_next_class | Next upcoming class | | get_class_times | Period start/end times | | get_meals_today | Today's meals | | get_meals_week | Weekly meal plan | | get_neis_dataset | Official NEIS dataset query | | diff_timetable_snapshots | Compare timetable snapshots |

| Key | Page | What it shows | |:---:|:-----|:-------------| | h | Home | Dashboard: next class, timetable preview, meals, alerts | | s | Schools | Search with result cards + recent quick picks (1–9) | | t | Timetable | Weekly student timetable with status summary | | m | Meals | Weekly meal view with notes | | y | Teacher | Teacher info & timetable summary | | g | Diagnostics | Key state, provider access modes, warning ledger | | p | Settings | Profiles, default school, cache, destructive actions with confirmation | | ? | Help | Keyboard hints and design notes |

Navigation: ← → arrows, i IME input, r refresh, e easy mode, q quit.

🔐 Access Model

Every Kampus response includes transparent provenance via dataStatus:

| Status | Meaning | Requires | |:-------|:--------|:---------| | official-full | Authoritative NEIS data, complete results | Real NEIS_API_KEY | | official-limited | Official NEIS data, may be truncated by sample cap | No key needed | | unofficial | Comcigan data — practical but upstream-fragile | No key needed |

Without a NEIS key

• ✅ Merged school search & resolve
• ✅ Comcigan student / teacher timetables
• ✅ Limited NEIS school info, meals, datasets
• ⚠️ Broader queries may be truncated

With a real NEIS key

• ✅ Everything from keyless mode
• ✅ Full official results, no truncation
• ✅ Broader schedule and dataset queries
• ✅ Full month meal queries

[!NOTE] KEY=SAMPLE is no longer valid for NEIS and returns ERROR-290. Omitting the key still works for some endpoints in limited sample mode. See Upstream Verification for full details.

🤖 AI Agent Onboarding

[!IMPORTANT] This repository is agent-ready. It ships with guardrails, task routing, and structured workflows for coding agents like Claude Code, Codex, and Cursor.

Quick start for agents

Point your agent at this repo and paste this prompt:

This repository has agent instructions and task-specific skills.
Start with AGENTS.md, then read docs/AGENT_GUIDE.md and docs/SKILLS_INDEX.md.
Use the appropriate Kampus skill from skills/ for school, timetable, meals, NEIS, or ops work.
Preserve raw CLI and MCP contracts unless the task explicitly changes them.

What the agent gets

| File | Purpose | |:-----|:--------| | AGENTS.md | Repo-wide guardrails and product boundaries | | docs/AGENT_GUIDE.md | Surface selection, provider model, verification matrix | | docs/SKILLS_INDEX.md | Task → domain skill routing map | | docs/AGENT_RECIPES.md | Copy-paste agent workflows (onboarding, daily brief, diagnosis, release) | | skills/ | Domain-specific skill documents |

Skill routing

skills/kampus/SKILL.md            ← start here (umbrella router)
  ├── kampus-school/SKILL.md      school search, resolve, info
  ├── kampus-timetable/SKILL.md   student & teacher timetable
  ├── kampus-meals/SKILL.md       meal queries & metadata
  ├── kampus-neis/SKILL.md        official NEIS datasets
  └── kampus-ops/SKILL.md         verification, diagnostics, release

Agent guardrails

• Preserve dataStatus, providerMetadata, warnings, accessMode, complete
• Preserve the Comcigan / NEIS provider split
• Use --json for scripted work; MCP for tool-calling clients
• Do not hide warning metadata to make output look cleaner
• Project and developer identity is read-only build metadata

📦 Architecture

kampus/
├── packages/
│   ├── core/                @kampus/core
│   │   └── src/             Shared types, config, cache, routing, normalization
│   ├── providers/
│   │   ├── comcigan/        @kampus/provider-comcigan
│   │   │   └── src/         Unofficial timetable provider (dynamic route parsing)
│   │   └── neis/            @kampus/provider-neis
│   │       └── src/         Official NEIS Open API provider (key/keyless modes)
│   ├── cli/                 @kampus/cli
│   │   └── src/             CLI commands, human shell, easy mode, TUI components
│   └── mcp/                 @kampus/mcp
│       └── src/             MCP server with 13 typed tools
├── skills/                  Agent skill documents (6 domain skills)
├── docs/                    Reference documentation
├── scripts/                 Build, pack, and release scripts
└── .github/workflows/       CI, live smoke, release pipelines

| Package | Role | |:--------|:-----| | @kampus/core | Normalized types, config, cache, provider routing, snapshot diff | | @kampus/provider-comcigan | Unofficial Comcigan provider — dynamic /st route parsing, EUC-KR search, split-factor decode | | @kampus/provider-neis | Official NEIS provider — keyed/keyless modes, truncation detection, dataset pagination | | @kampus/cli | Internal workspace package for kps. Published to npm as kampus | | @kampus/mcp | MCP server — 13 tools, structuredContent, transparent dataStatus |

• Merged school identity — Schools are a providerRefs object holding both Comcigan and NEIS identifiers, enabling operation-based routing instead of provider-locked resolution.

• Shared result model — CLI JSON output and MCP structuredContent use the same dataStatus + providerMetadata model. No separate output abstractions.

• Transparent warnings — Provider warning codes (NEIS_TIMETABLE_YEAR_LAG, NEIS_STALE_CACHE, NEIS_PAGE_LIMIT, etc.) flow through to consumers instead of being swallowed.

• Structured errors — JSON mode returns typed error objects with semantic exit codes (2–10) for script consumption.

📚 Documentation

| Document | Covers | |:---------|:-------| | CLI Reference | Complete command reference — modes, flags, output formats, exit codes | | Operator Runbook | Setup, smoke checks, key rotation, release flow, incident playbooks | | Agent Guide | Surface selection, provider model, metadata contracts, verification | | Agent Recipes | Compact repeatable workflows — onboarding, daily brief, diagnosis, release | | Skills Index | Task → skill routing map for agents | | TUI Handoff | Human shell design contracts, UX boundaries, suggested improvements | | Upstream Verification | Live upstream checks, implementation rules, repo inspections | | Architecture Deep Dive | Full architecture review, packaging, remaining risks |

✅ Validation & Quality Gates

pnpm verify                              # lint + typecheck + build + test
pnpm smoke:live                          # live provider health (no key required)
pnpm smoke:pack:cli                      # packed CLI tarball install + startup
NEIS_API_KEY=<key> pnpm smoke:keyed      # full official NEIS validation

| CI Workflow | Trigger | What it does | |:------------|:--------|:-------------| | ci.yml | Push / PR | Verify on Ubuntu, Windows, macOS · Packed CLI smoke | | live-smoke.yml | Every 6 hours | Live provider smoke · Auto-opens/closes GitHub issues on failure | | release.yml | v* tag | Verify → pack → smoke-install → upload artifact → npm publish |

⚠️ Limitations

[!WARNING] Comcigan is unofficial. It provides practical timetable data but can break without notice if the upstream changes its payload format or endpoints.

[!CAUTION] No-key NEIS is useful but limited. Sample-mode queries may be truncated at 5 rows. A real NEIS_API_KEY is required for production-grade completeness.

• Official NEIS timetable data can lag behind other datasets for the same school and academic year.
• Windows uses DPAPI for local secret storage. Non-Windows environments fall back to plain-text config unless environment variables are used.
• Project and developer identity metadata is embedded in the build and is read-only for users.

Kampus · github.com/4ndrxxs/Kampus · MIT License

Built by Juwon Seo · [email protected]