npm package: @knowcode/planb-admin-mcp
Description: PlanB Admin MCP server for backup and file anomalies (Supabase-backed).
Latest version: 0.1.1

# 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

```bash
cd packages/planb-admin-mcp
npm install
```

## Local Development

```bash
# 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**
   ```json
   {
     "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**
   ```json
   {
     "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:

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
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.