#Eko Admin MCP

The eko-admin MCP server exposes admin tools for the Pac-Man progression system. It connects to the Supabase database and Upstash queue, letting you query analytics, simulate tier evaluations, look up users, and trigger bulk operations — all from within Claude Code.

#Setup

The server is registered in .mcp.json and starts automatically when Claude Code launches:

{
  "eko-admin": {
    "type": "stdio",
    "command": "bun",
    "args": ["run", "packages/mcp-admin/src/server.ts"]
  }
}

Prerequisites:

• .env.local at monorepo root with DATABASE_URL and QSTASH_TOKEN
• bun install completed (workspace dependencies resolved)

#Tools

#progression_status

Get progression system analytics across four sections.

Parameter	Type	Default	Description
section	"distribution" | "bottlenecks" | "credits" | "velocity" | "all"	"all"	Which analytics section to fetch

Sections:

Section	What It Shows
distribution	How many users are in each of the 12 tiers
bottlenecks	Which gate thresholds block the most users from advancing
credits	Subscription credit accumulation and redemption rates
velocity	How quickly users advance through tiers over time

Examples:

"Show me the current tier distribution"
→ progression_status { section: "distribution" }

"Which gates are blocking users?"
→ progression_status { section: "bottlenecks" }

"Full progression dashboard"
→ progression_status {}  (defaults to "all")

---

#progression_simulate

Test what tier a hypothetical scorecard would reach. Useful for tuning gate thresholds or answering "what if" questions.

Parameter	Type	Required	Description
points	integer >= 0	Yes	Total points earned
quality_grade_score	number 0-100	Yes	Difficulty-weighted accuracy
topics	integer >= 0	Yes	Distinct topics with 5+ interactions
active_days	integer >= 0	Yes	Active days in last 60 days
c5_completions	integer >= 0	Yes	Completed challenge sets
prestige_count	integer >= 0	No	Prestige level (0 = first run)

Returns: Evaluated tier, gate breakdown (which gates pass/fail), and rewards unlocked at that tier.

Examples:

"What tier does 900 points, 80% quality, 4 topics, 21 active days, 10 completions reach?"
→ progression_simulate {
    points: 900,
    quality_grade_score: 80,
    topics: 4,
    active_days: 21,
    c5_completions: 10
  }

"Same user but on prestige 2"
→ progression_simulate { ..., prestige_count: 2 }

Prestige scaling: When prestige_count > 0, gate thresholds are scaled upward — higher prestiges require more to reach the same tier.

---

#progression_lookup_user

Look up a real user's full progression state by email.

Parameter	Type	Required	Description
email	string (email)	Yes	User's email address

Returns:

• User ID and email
• Current tier (number, name, icon)
• Prestige count and subscription credits
• Full scorecard with last update timestamp
• Tier evaluation against current gates
• Gate breakdown for next tier (what they need to advance)
• Unlocked rewards
• Prestige key trophies

Examples:

"Why is alice@example.com stuck at tier 3?"
→ progression_lookup_user { email: "alice@example.com" }

Check gate_breakdown_next_tier in the response — it shows exactly which gates the user passes and fails for the next tier.

---

#progression_recalculate

Trigger bulk recalculation of all user tiers. Has a built-in dry-run safety mechanism.

Parameter	Type	Required	Description
confirm	boolean	Yes	false = dry run (count only), true = dispatch job

Workflow:

1. Dry run first: progression_recalculate { confirm: false } — returns how many users would be affected
2. Execute: progression_recalculate { confirm: true } — enqueues a BULK_RECALCULATE_PROGRESSION message to the queue

The actual recalculation happens asynchronously via the worker queue.

---

#progression_list_tiers

List all 12 progression tiers with their gate thresholds and reward counts. No parameters.

Returns: Array of tiers, each with:

• Tier number, name, icon key
• Gate thresholds (points, quality, topics, active_days, c5_completions)
• Count of active rewards at that tier

---

#progression_list_rewards

List all tier rewards, optionally filtered to a specific tier.

Parameter	Type	Required	Description
tier_number	integer 1-12	No	Filter to this tier only

Examples:

"What rewards does tier 7 unlock?"
→ progression_list_rewards { tier_number: 7 }

"Show all rewards across all tiers"
→ progression_list_rewards {}

#Scorecard Dimensions

The five dimensions that determine a user's tier:

Dimension	Source	Description
points	SUM of card interaction points	Cumulative challenge points earned
quality_grade_score	Weighted accuracy formula	Difficulty-weighted correctness (0-100)
topics	COUNT DISTINCT topic categories	Topic breadth (requires 5+ interactions per topic)
active_days	COUNT DISTINCT active dates	Engagement consistency over last 60 days
c5_completions	Completed challenge groups	Challenge set mastery

#Architecture

Claude Code
    ↓ stdio
packages/mcp-admin/src/server.ts     ← MCP server entry point
    ↓
packages/mcp-admin/src/tools/        ← Tool registry + implementations
    ↓
@eko/db (progression-queries.ts)     ← Database queries
@eko/shared (progression.ts)         ← Pure evaluation functions
@eko/queue                           ← Queue client for bulk jobs

#Source Files

File	Purpose
packages/mcp-admin/src/server.ts	Server entry point
packages/mcp-admin/src/tools/index.ts	Tool registry
packages/mcp-admin/src/tools/progression.ts	All 6 tool implementations
packages/db/src/drizzle/progression-queries.ts	Database queries
packages/shared/src/progression.ts	evaluateTier, getGateBreakdown, scaleGatesForPrestige