msstate-policies-mcp

MCP server exposing seven Mississippi State University content domains: Operating Policies (https://www.policies.msstate.edu/current), six academic-date sources (registrar academic + exam calendars, university holidays, graduate school PDFs, financial aid, housing), the course catalog with prereq DAG, emergency guidance, tuition & fees, online programs, and dining venues with per-day hours. Unofficial — not affiliated with MSU. Always verify against the official source.

Current version: v1.2.8 (2026-05-22). Trust-surface follow-up #2: closes 5 live-investigation defects (synonyms wire leak, citation_card hard-coded "high" confidence, plan_semester Worker CPU crash, online deadline parser accepting garbage text, HR leave returning empty accruals with no forwarding path) + a side-finding (msstate-policies/package.json test script omitted tests/hr/*.test.ts — 50 tests were silently absent since v1.2.6). No new tools. Security score 330 → 335 via SYN7. Prior release: v1.2.7 (2026-05-21). Trust-surface follow-up to v1.2.6: extends citation_card to know about the HR domain (silently returned confidence: "none" for every HR claim despite the corpus being loaded — bug introduced in v1.2.6 when HR was added without extending citation_card); fixes a stale HR slug-map drift in the Worker (5 of 10 HR benefit categories returned page: null on the hosted Worker); tightens the relatedForms keyword extractor. No new tools, no security-score change. v1.2.6 (2026-05-20). Adds 4 new HR tools over a new baked hr_services corpus block from hrm.msstate.edu: find_msu_hr_info, find_msu_hr_form, get_msu_hr_benefit, list_msu_hr_contacts. Security score 315 → 330 via HR1-HR6. v1.2.5 (2026-05-19). Adds the catalog-only plan_semester tool: department + completed courses → up to 3 candidate course bundles within a credit-hour window. v1.2.4 (2026-05-19) adds two derived tools over the existing online corpus: match_online_program (profile → ranked shortlist) and estimate_program_cost (slug + credits → total-cost rollup). v1.2.3 (2026-05-19) adds the citation_card meta-tool — splits an answer into sentence-level claims and returns one citation card per claim across all 7 corpora with source_url + last_updated + confidence. v1.2.0 (2026-05-18) adds anonymous-aggregate Worker telemetry (Cloudflare Analytics Engine; k-anonymity enforced at query time). v1.1.1 fixed the fuzzy program resolver and added list_programs_by_staff. v1.1.0 added the dining module (2 tools, daily-refreshed corpus, status_now in America/Chicago). v1.0.0 added the online module (4 tools). Calendar retrieval uses BM25 over a 4-field weighted index where the synonyms field is populated at build time by Anthropic Claude Haiku — runtime stays pure BM25 with zero third-party API calls.

This is the publishable npm package and the Claude Code plugin source. See the repository root README for the user-facing walkthrough, install paths, and what to expect from a response.

Install (plain MCP)

npx -y msstate-policies-mcp

…or from a local checkout:

node /path/to/msstate-mcp/msstate-policies/dist/index.js

Tools (33)

Policies (4): search_policies, get_policy, chain_find_relevant_policies, cite_policy Calendars (2, v0.4.0+, synonyms-aware in v0.5.0): find_msu_date, get_msu_calendar Courses (4, v0.6.0+, prereq diagnostics in v0.9.0, semester planner in v1.2.5): search_msu_courses, get_msu_course, get_msu_course_graph, plan_semester Emergency (4, v0.7.0): get_msu_emergency_guideline, list_msu_emergency_types, find_msu_severe_weather_refuge, get_msu_emergency_contacts Tuition (4, v0.8.0): get_msu_tuition_rate, get_msu_enrollment_fees, find_msu_tuition_faq, list_msu_tuition_campuses Online (7, v1.0.0 + v1.1.1 + v1.2.4): list_online_programs, get_online_program, get_online_admissions_process, find_online_info, list_programs_by_staff, match_online_program, estimate_program_cost Dining (2, v1.1.0): list_msu_dining_locations, get_msu_dining_hours HR (4, v1.2.6): find_msu_hr_info, find_msu_hr_form, get_msu_hr_benefit, list_msu_hr_contacts Citation (1, v1.2.3): citation_card Diagnostics (1): health_check

See the root README for tool descriptions and example responses.

Environment variables

Runtime (consumer-facing)

| Variable | Effect | |---|---| | MSSTATE_POLICIES_RETRIEVAL | bm25 (default) / embed / hybrid. Policy search only. See root README for the comparative-eval rationale. | | OPENAI_API_KEY | Required at runtime when MSSTATE_POLICIES_RETRIEVAL is embed or hybrid (for query embedding). Otherwise unused. | | MSSTATE_POLICIES_CACHE | Set to disk to enable cross-platform on-disk cache for policy PDFs (24h TTL) via env-paths. Default in-memory only. Calendar rows use in-memory TTL only (24h stable sources, 6h housing). |

Calendar retrieval is always BM25-with-synonyms at runtime — no API key, no env var, no cost. Synonyms ship inside the package's dist/calendar-synonyms.json sidecar.

Build-time (rebuilders only)

| Variable | Required when | Effect | |---|---|---| | ANTHROPIC_API_KEY | Running node scripts/build-worker-corpus.mjs | Generates v0.5.0 synonyms. Never read at runtime — mechanically enforced by SYN4 in tools/security-checklist.sh. |

All logging goes to stderr only — stdout is reserved for MCP JSON-RPC framing.

Scripts

npm run build         # bundle src/ → dist/index.js (CJS)
npm run typecheck     # tsc --noEmit
npm test              # tsx --test tests/*.test.ts
npm run audit:pdfs    # download + parse all current PDFs (live; writes eval/audit-*.csv)
npm run embeddings    # build dist/embeddings.json for POLICY search (needs OPENAI_API_KEY)
npm run eval          # run the policy eval harness against the live MCP (--suite=<name> to target a specific module suite)
npm run eval:synonyms # v0.5.0 calendar synonyms eval — pure BM25, zero API cost
                      # Deterministic suites (CI-gated): courses, emergency, tuition, dining, adversarial
                      # Manual suites (live-scrape MSU): dates, policies (--suite=policies needs ANTHROPIC_API_KEY)
npm run bundle        # build the Claude Project starter zip (released as dist-bundle/)

Full corpus rebuild (Worker + sidecar) — runs scrape + v0.5.0 paraphrase pass:

export ANTHROPIC_API_KEY=sk-ant-...
node ../scripts/build-worker-corpus.mjs

Cached by content hash — incremental rebuilds re-paraphrase only changed rows (typically <$0.05). Full rebuild: ~$0.50, ~25 minutes (concurrency 2, tuned for Anthropic tier-1 rate limits).

Maintainers: see ../docs/BUILD.md for architecture, decision history, eval methodology, and open issues.

License

MIT.