preview

Potassium MCP Companion Suite

An independent, modular toolkit for scene inspection, map/recording forensics, Luau static analysis, and AI-assisted scripting workflows — built for creators, auditors, and tinkerers who want clarity without the cloud.

Welcome to the Potassium MCP Companion Suite, a distinct and expanded sibling project inspired by the original potassium-mcp concept. Where the original focused on tight, independent utilities, this repository evolves the idea into a full-spectrum companion: a set of decoupled micro-tools that speak a common dialect, share a consistent interface philosophy, and can be composed like LEGO bricks to inspect, analyze, transform, and document scene data, saved maps, session recordings, and Luau source.

Think of it less as a single application and more as a workbench: each tool is a chisel, a caliper, a magnifying glass. You pick the one you need, use it, and put it back. No monolith. No forced telemetry. No lock-in.

🧭 Why This Exists

Most tooling in this space is either too heavy, too opinionated, or too coupled to a single runtime. The Potassium MCP Companion Suite takes the opposite stance: small, sharp, independent instruments that each do one job well and hand off cleanly to the next.

If a scene is a city, then this suite gives you the surveyor's theodolite, the auditor's ledger, the linguist's grammar book, and the architect's sketchpad — all in one drawer, none welded together.

The result is a workflow that feels less like operating a machine and more like conducting an orchestra.

✨ Feature List

🧩 Modular micro-tools — every module runs standalone or as part of a pipeline
🖥️ Responsive UI — adapts fluidly from ultrawide monitors to compact laptops
🌍 Multilingual support — locale bundles for major world languages, extensible by design
🛰️ Offline-first philosophy — analysis runs locally; the network is optional, never mandatory
🔍 Scene diffing — compare two scene snapshots and surface meaningful deltas
🗺️ Saved map parsing — read, normalize, and re-emit map structures
🎞️ Recording timeline reconstruction — replay event streams as structured data
🧠 Luau static analysis — type inference hints, dead code detection, taint-style flow tracing
🤖 AI-assisted scripting bridge — optional adapter that turns natural language into Luau scaffolds
🧪 Deterministic outputs — same input, same result, every time
📦 Zero-glue composition — modules communicate through a shared, documented schema
🔐 Local-only by default — nothing leaves your machine unless you explicitly export it
🧾 Audit-friendly logs — every transformation is recorded in a readable journal
♿ Accessibility-aware design — keyboard-first navigation, high-contrast themes
🌐 SEO-conscious documentation — discoverable, human-readable, machine-friendly
🕒 Around-the-clock assistance channels — see Support Model

🏗️ Architecture Overview

The suite follows a hub-and-spoke philosophy. A lightweight core provides:

Schema Registry — canonical definitions for scenes, maps, recordings, and Luau ASTs
Journal — append-only log of every operation, useful for reproducibility
Locale Resolver — loads translation bundles on demand
Adapter Layer — pluggable interfaces for AI providers, exporters, and importers

Each spoke — Inspector, Forensics, Analyzer, Bridge — depends on the core but never on each other. You can remove any spoke and the rest keep working. That is the point.

🔬 Core Modules

🧿 Scene Inspector

The Scene Inspector is your magnifying glass. It walks a scene graph, enumerates entities, and produces a normalized report covering:

Entity hierarchy and parent-child relationships
Property snapshots with type annotations
Material and texture references
Transform matrices in human-readable form
Suspicious or anomalous node patterns flagged for review

Use it to answer questions like "What changed between build 41 and build 42?" or "Why does this scene feel heavier than it looks?"

🗺️ Map & Recording Forensics

This module handles saved maps and session recordings as first-class citizens.

Decode map archives into structured tiles and metadata
Reconstruct recording timelines into ordered event streams
Compute coverage statistics — which regions were visited, which were ignored
Detect gaps, jumps, and out-of-order anomalies
Export to CSV, JSON, or a compact binary form for archival

If the Scene Inspector is the magnifying glass, this is the forensic lab: patient, precise, unflinching.

🧬 Luau Static Analysis

A static analyzer tailored to Luau's idioms:

Type inference hints without requiring annotations
Dead code and unreachable branch detection
Taint-style flow tracing for suspicious data paths
Module dependency graphs
Style linting with configurable rulesets
Safe refactor suggestions with before/after previews

The goal is not to nag. The goal is to illuminate.

🤖 AI-Assisted Scripting Bridge

An optional, adapter-based bridge that turns intent into scaffolding:

Describe a behavior in plain language; receive a Luau skeleton
Iteratively refine via structured prompts
All generated code is linted by the analyzer before it ever reaches you
Providers are pluggable: bring your own, or run fully local

The bridge is deliberately opt-in. The suite works perfectly without it, and always will.

🎨 Interface & UX

Responsive UI across desktop and tablet form factors
Dark, light, and high-contrast themes
Keyboard-first — every action reachable without a pointer
Command palette with fuzzy search
Session restore — pick up where you left off
Exportable reports in multiple formats

The interface aims to feel like a well-organized workshop, not a cockpit. Tools are where you expect them, labeled clearly, and never hidden behind nested menus.

🌍 Multilingual Support

Locale bundles ship for:

English
Español
Français
Deutsch
Português
日本語
한국어
简体中文
Русский

Adding a new language is a matter of dropping a JSON bundle into the appropriate directory and registering it in the locale manifest. Community contributions are welcome and encouraged.

🛎️ Support Model

Assistance is available around the clock, every day of the year. Channels include:

📖 Comprehensive in-repo documentation
💬 Discussion forums monitored continuously
🐛 Issue tracker with triage within one business day
📚 Example galleries and walkthroughs

Support is community-driven and maintained by the same people who use the tools daily. That is not a marketing line — it is the operating principle.

🗺️ Roadmap 2026

Q1 2026 — Stabilize schema registry v2; publish migration guide
Q2 2026 — Ship recording diff viewer with side-by-side timelines
Q3 2026 — Expand Luau analyzer with cross-module taint tracing
Q4 2026 — Release plugin SDK for third-party spokes

Dates are intentions, not contracts. Progress is tracked openly.

🔎 SEO & Discoverability Notes

This project is documented with discoverability in mind. If you arrived here searching for terms like scene inspection toolkit, map recording analyzer, Luau static analysis, AI-assisted scripting bridge, or modular forensics utilities, you are in the right place. Documentation uses natural language, meaningful headings, and structured metadata — no keyword stuffing, no dark patterns.

⚠️ Disclaimer

This project is an independent, community-driven toolkit. It is not affiliated with, endorsed by, or sponsored by any platform, engine, or vendor whose file formats it may read or write. All trademarks belong to their respective owners.

Users are responsible for ensuring their use of these tools complies with applicable terms of service, local laws, and ethical norms. The maintainers provide this software as-is, without warranty of any kind, express or implied.

Nothing in this repository is intended to circumvent protections, bypass safeguards, or enable misuse. If a use case feels ambiguous, ask first — the community is friendly.

📄 License

Released under the MIT License. See the full text here:

LICENSE

potassium-scene-lens