MCP server for the Kicksite martial-arts-school management API. Exposes tools to read and write dojo data including students, prospects, memberships, billing, invoices, classes, attendance, belt promotions, communications, and notes.
Solid foundation with clear verb-noun naming (health_check, list_students, get_student, search_students, create_student, update_student_status, list_prospects). All 7 tools have descriptions (avg ~180 chars, within 10-1024 baseline). All parameters have type definitions and descriptions. However, descriptions contain example invocations (e.g., 'Example: list_students(status="Active", program_id=3, per_page=100)') which violates the pattern:tool-description rule against embedding example values, LLMs may reuse them literally. Output schemas are not documented in the source. Error handling is present (typed exceptions, audit logging) but recovery guidance is minimal. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels (READ_ONLY vs WRITE).
Create a new active student record (skipping the prospect/trial funnel). Use when: "import this student from a spreadsheet", "back-fill a record that was lost during a migration", or "promote a prospect to active student directly". For the standard lead-to-student path, prefer create_prospect and let the Kicksite UI graduate the trial. Example: create_student(first_name="Sarah", last_name="Patel", email="[email protected]", program_id=3, location_id=1).
Fetch one student by id. Use when: "show me the profile for student 1234", "get the belt rank and program for student 5678". Example: get_student(student_id=1234).
Confirm credentials work and return the authenticated school profile. Use this first whenever the rest of the tools return auth errors - it surfaces the real problem in one round-trip.
List prospects (leads in the trial funnel) at the school (paged). Use when: "show me all active trial prospects", "list leads from the Westside location this month", "what prospects are in Trial status?". Example: list_prospects(status="Trial", per_page=100). status filter accepts "Lead" / "Appointments" / "Trial" / "Archived". Pass status=None to include all.
Descriptions embed example invocations (e.g., 'Example: list_students(status="Active", program_id=3)') which LLMs may reuse literally instead of adapting to context. Replace with enum constraints and formal parameter descriptions.
Output schemas are not documented in source code. LLMs cannot plan downstream calls or extract required fields (e.g., student_id from create_student response). Add explicit return type documentation.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear risk levels declared (READ_ONLY vs WRITE). Agents cannot distinguish safe from destructive operations without explicit hints.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | <=2025-11-25 | v2 |
List active students at the school (paged). Use when: "show me my active students", "list students in the Adult Karate program", "who is enrolled at the Westside location?". Example: list_students(status="Active", program_id=3, per_page=100). status filter accepts "Active" / "Frozen" / "Inactive". Pass status=None to include all.
Search students by free-text (name / email / phone / member number). Use when: "find all students named Patel", "look up student by phone 555-1234", "find student by email sarah@...". Example: search_students(query="Patel").
Change a student's status: Active, Frozen, or Inactive. Use when: "freeze student 1234 for the summer", "mark student 5678 as inactive - they moved away", "reinstate student 4321 from Frozen to Active". Example: update_student_status(student_id=1234, status="Frozen").
Error handling raises typed exceptions (KicksiteAuthError, KicksiteNotFoundError, etc.) but recovery guidance is generic. 'Resource not found' does not suggest calling search_students() or list_students() to discover valid IDs.
Parameters like 'status' accept free-form strings ('Active', 'Frozen', 'Inactive') documented in descriptions but not declared as enums in JSON Schema. LLMs may hallucinate invalid values.