PlanB Admin MCP Server

Admin-only Model Context Protocol server that connects to Supabase (service role key) to provide anomaly-detection tools over PlanB backup data.

Features

• MCP stdio server built with @modelcontextprotocol/sdk
• Supabase integration via service role key
• Analytics:
  • planb_admin_find_callbacks_table_anomalies – row-count, bytes-per-row, coverage issues for public.callbacks_data
  • planb_admin_find_file_storage_anomalies – storage usage + large file detection for public.callbacks_app_files

Prerequisites

• Node.js 18+
• Supabase project URL and Service Role key (SUPABASE_SERVICE_ROLE_KEY)
• npm login for deployment (see docs/npm-deployment-guide.md)

Install

cd packages/planb-admin-mcp
npm install

Local Development

# Dev/watch mode (tsx)
SUPABASE_URL="https://<project>.supabase.co" \
SUPABASE_SERVICE_ROLE_KEY="<service-role>" \
npm run dev

Configure your MCP-compatible client (Claude Desktop, Cursor, VS Code MCP extension, etc.) to execute the planb-admin-mcp binary (during dev, that is the tsx src/server.ts process spawned by npm run dev). You should see two tools available:

• planb_admin_find_callbacks_table_anomalies
• planb_admin_find_file_storage_anomalies

Testing the Tools

With the dev server running:

1. Callbacks Table Tool

   {
     "days": 14,
     "zThreshold": 2.5,
     "minRunsPerGroup": 4
   }

   Verify the response contains an anomalies array (empty array means no issues) and cross-check a few entries against Supabase data.

2. File Storage Tool

   {
     "days": 7,
     "storageUsageThreshold": 0.75,
     "largeFileThresholdBytes": 30000000
   }

   Confirm storage_usage ratios and large_file sizes match the rows in callbacks_app_files.

Direct Script Testing (Optional)

Run helper modules without MCP by piping a short TSX script:

Run helper modules without MCP by piping a short TSX script:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npx tsx <<'TS'
import { supabase } from './src/db.js';
import { findCallbacksTableAnomalies } from './src/analytics/callbacksData.js';

const main = async () => {
  const res = await findCallbacksTableAnomalies(supabase, {
    days: 7,
    zThreshold: 3,
    minRunsPerGroup: 5
  });
  console.log(JSON.stringify(res, null, 2));
};

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
TS

Scripted CLI test

A dedicated helper script exercises both anomaly detectors without starting the MCP server:

cd packages/planb-admin-mcp
SUPABASE_URL="https://<project>.supabase.co" \
SUPABASE_SERVICE_ROLE_KEY="<service-role>" \
npm run test:anomalies

Optional overrides (defaults in parentheses):

• SHOW_SAMPLES (true) – fetch sample rows to prove Supabase connectivity (set to false to skip)
• CALLBACKS_SAMPLE_ROWS (2)
• APPFILES_SAMPLE_ROWS (2)
• CALLBACKS_DAYS (7)
• CALLBACKS_Z (3)
• CALLBACKS_MIN (5)
• CALLBACKS_MAX_ROWS (500)
• CALLBACKS_TIMEOUT_MS (20000)
• APPFILES_DAYS (7)
• APPFILES_USAGE (0.8)
• APPFILES_LARGE (50 * 1024 * 1024)
• APPFILES_MAX_ROWS (500)
• APPFILES_TIMEOUT_MS (20000)
• STRESS_TEST (true) – run additional aggressive thresholds unless set to false
• CALLBACKS_STRESS_DAYS (3)
• CALLBACKS_STRESS_Z (1.5)
• CALLBACKS_STRESS_MIN (3)
• CALLBACKS_STRESS_MAX_ROWS (200)
• CALLBACKS_STRESS_TIMEOUT_MS (30000)
• APPFILES_STRESS_DAYS (3)
• APPFILES_STRESS_USAGE (0.6)
• APPFILES_STRESS_LARGE (20 * 1024 * 1024)
• APPFILES_STRESS_MAX_ROWS (200)
• APPFILES_STRESS_TIMEOUT_MS (30000)

Example with overrides:

SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... \
CALLBACKS_SAMPLE_ROWS=5 APPFILES_SAMPLE_ROWS=5 \
CALLBACKS_DAYS=14 CALLBACKS_Z=2.5 \
APPFILES_USAGE=0.75 APPFILES_LARGE=$((30 * 1024 * 1024)) \
npm run test:anomalies

The script first prints sample rows from both Supabase tables (unless SHOW_SAMPLES=false) so you can confirm real data is being fetched, then dumps the baseline/stress anomaly results—perfect for regression checks or verifying credentials before publishing.

Build & Run Compiled Output

npm run build
SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npm start
# or, after build:
SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... npx @knowcode/planb-admin-mcp

Deployment

Follow docs/npm-deployment-guide.md for the full workflow. Quick steps:

cd packages/planb-admin-mcp
./deploy.sh   # prompts for version + commit message, builds, publishes, pushes

Ensure npm whoami succeeds before running the script and that the git tree is clean.

Troubleshooting

• Missing env vars → src/db.ts exits with an error; double-check SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY.
• MCP client can’t connect → run server manually and use the client’s IPC/stdout diagnostics to ensure the executable path is correct.
• Supabase errors → inspect console output; the analytics functions throw with the Supabase error message.