Tools

Utility scripts are located in src/tools/.

---

init_mongo.py — provision MongoDB

Sets up the database, its collections/indexes, and optionally an application user — the one-time step before pointing the server at a fresh MongoDB instance.

If the server is already up (even on the `memory` backend), `POST /admin/storage/prepare-mongodb` — surfaced in the dashboard as **Platform Admin → Settings → Prepare a MongoDB instance** — does the same job without SSH access, and covers the *full* current set of collections/indexes the app relies on (this CLI script only covers the original two, `resources`/`namespace_entries` — see [Platform Admin — Preparing MongoDB](/platform-admin/#preparing-mongodb)). The dashboard can also cut the running process over to that target immediately afterward — no restart — via `POST /admin/storage/switch`, see [Platform Admin — Switching the storage backend live](/platform-admin/#switching-the-storage-backend-live). This script is still the only option when nothing is running yet at all.

What gets provisioned

Object	Purpose
Collection resources	resource content + its analysis
Collection namespace_entries	namespace-to-resource membership
Index analysis_idx	sparse, on resources.analysis — speeds up the unanalysed-lookup query
Index ns_idx	on namespace_entries.namespace
Index hash_idx	on namespace_entries.hash
Application user (optional)	readWrite on the target database

Every step is safe to re-run — anything that already exists is reported and skipped rather than recreated.

Usage

# Read connection settings from configs/opentremor-core-local.yaml
python src/tools/init_mongo.py

# Connect with admin credentials explicitly
python src/tools/init_mongo.py --uri mongodb://admin:secret@localhost:27017

# ...and provision an application user in the same run
python src/tools/init_mongo.py \
  --uri mongodb://admin:secret@localhost:27017 \
  --app-user mcp_app \
  --app-password changeme

# See the steps without touching the database
python src/tools/init_mongo.py --plan

# Point at a specific config file
python src/tools/init_mongo.py --config /etc/mcp/config.yaml

Flags

Flag	Default	Description
--config FILE	configs/opentremor-core-local.yaml	config file to read connection settings from
--uri URI	from config	MongoDB URI, admin credentials
--database NAME	from config	target database
--resources-collection NAME	from config	name for the resources collection
--entries-collection NAME	from config	name for the namespace-entries collection
--app-user USER	—	application username to provision
--app-password PASS	—	password for --app-user
--plan	—	print the steps, make no changes

Requirements

pip install pymongo pyyaml
# already covered if you installed via Poetry:
poetry install

Example run

target: mongodb://localhost:27017  (database 'mcp_analyzer')
collections: resources, namespace_entries
application user: mcp_app

proceed? [y/n]: y
created collection 'resources'
created index 'analysis_idx' on 'resources'
created collection 'namespace_entries'
created index 'ns_idx' on 'namespace_entries'
created index 'hash_idx' on 'namespace_entries'
created user 'mcp_app' (readWrite on 'mcp_analyzer')

done.

This bootstraps the core `resources`/`namespace_entries`/`api_keys` collections and their indexes. The rest of the multi-tenant collections (`organizations`, `users`, `memberships`, `installed_analyzers`, `custom_rules`, `llm_credentials`, `jobs`, `usage_events`, `findings`, `integrations`) and their indexes are created automatically by `MongoBackend.setup()` on every application startup — no separate CLI step needed for those.

---

grant_superadmin.py — bootstrap a platform admin

Grants or revokes is_superadmin — a permission axis independent of any org’s role, gating the cross-tenant Platform Admin surface (GET /admin/*). There is no in-app way to mint the first superadmin — POST /admin/users/{user_id}/superadmin itself requires one already — so this script writes the flag directly to MongoDB for an already-registered user (POST /auth/register first if needed). Every superadmin after that can be granted through the API instead.

For a fresh install, `config.auth.default_admin_email`/`default_admin_password` (see [Configuration Reference — auth](/configuration/reference/#auth)) creates a ready-to-use superadmin declaratively at startup — no script run required. Reach for this script when promoting an *existing* user post-install instead.

Usage

# Grant, using settings from the default config file
python src/tools/grant_superadmin.py --email [email protected]

# Revoke
python src/tools/grant_superadmin.py --email [email protected] --revoke

# Explicit URI
python src/tools/grant_superadmin.py --email [email protected] --uri mongodb://localhost:27017

# Preview without making any changes
python src/tools/grant_superadmin.py --email [email protected] --dry-run

Options

Flag	Default	Description
--email EMAIL	(required)	The already-registered user to grant/revoke
--revoke	—	Revoke instead of grant
--config FILE	configs/opentremor-core-local.yaml	YAML config to read connection settings from
--uri URI	from config	MongoDB URI
--database NAME	from config	Target database
--dry-run	—	Report what would change, make no writes

Example output

Grant platform-admin status
  URI:      mongodb://localhost:27017
  Database: mcp_analyzer
  Email:    [email protected]

Connected to MongoDB
Granted platform-admin status for [email protected] (user_id=11a75db9-...).

They'll see it on their next login or POST /auth/session/switch —
is_superadmin is baked into the session JWT at mint time, like org_id/role.