Skip to main content
Glama

EnvSpeak

MCP-Server und CLI, die die Config-/Env-Var-Kaskade über .env-Dateien, Docker Compose und Kubernetes hinweg auflösen — und KI-Agenten (und dir) sagen, was eine Variable zur Laufzeit tatsächlich ergibt und warum.

Dieselbe Problemform wie die CSS-Kaskade — mehrere Quellen, nicht offensichtliche Vorrangregeln und ein Wert, der nur deshalb „gewinnt", weil er an einer bestimmten Stelle definiert ist — angewendet auf Anwendungskonfiguration statt auf Stylesheets. Ein Schwesterprojekt zu stylesafe und stylespeak, die dasselbe für CSS tun.

Das Problem

Die Konfiguration einer echten App stammt aus .env, .env.local, .env.production, docker-compose.yml (environment: vs. env_file:), Kubernetes-ConfigMap/Secret-Objekten und hartkodierten Fallbacks im Code — fünf oder mehr Ebenen, jede mit eigenen Vorrangregeln, die sich nicht so kombinieren lassen, wie man vermuten würde. Der bekannteste Stolperstein: Eine einfache .env.local überschreibt .env.production, es sei denn, man hat zusätzlich eine .env.production.local — weil „local" in der konventionellen dotenv-Kaskade Vorrang vor „umgebungsspezifisch" hat. Ein Agent, der die Konfiguration bearbeitet, hat keine Möglichkeit zu wissen, was eine Variable tatsächlich ergibt oder was kaputtgeht, wenn er eine Ebene ändert.

Related MCP server: @mcpx-digital/env-check

Tools

  • resolve_variable — was ergibt DATABASE_URL tatsächlich, und welche Datei gewinnt?

  • trace_variable — jede Stelle, an der diese Variable gesetzt ist, über alle Domänen und Umgebungen hinweg.

  • impact_preview — wenn ich diesen Wert in dieser Datei ändere, was ändert sich tatsächlich nachgelagert — und was wird durch etwas mit höherer Priorität abgeschirmt?

  • config_manifest — eine komprimierte Gesamtübersicht des Projekts: jede Variable, ihre Quellen und Risiko-Hotspots (Geheimnisse in einer versionierten Datei, Variablen, die im Code ohne Fallback und ohne irgendeine Quelle gelesen werden).

  • diff_environments — löse jede Variable unter zwei Umgebungen/Diensten/Workloads auf und sieh, was tatsächlich unterschiedlich ist.

Installation

npm install -g @patrizzos/envspeak

Als MCP-Server

{
  "mcpServers": {
    "envspeak": {
      "command": "envspeak"
    }
  }
}

Als CLI

envspeak resolve DATABASE_URL --environment production
envspeak trace LOG_LEVEL
envspeak impact --file .env --variable LOG_LEVEL --newValue debug
envspeak manifest
envspeak diff --a '{"nodeEnv":"development"}' --b '{"nodeEnv":"production"}'

Wenn --files weggelassen wird, erkennt envspeak automatisch .env*-Dateien, Compose- und Kubernetes-Manifestdateien unter --projectRoot (Standard: aktuelles Verzeichnis). Übergib --files a,b,c, um den Bereich explizit einzuschränken — empfohlen für MCP-Aufrufe, damit der Agent genau kontrolliert, was gelesen wird.

Kodierte Vorrangkonventionen

dotenv (Next.js/Vite-Stil, der De-facto-Standard): process.env (Shell) > .env.[env].local > .env.local > .env.[env] > .env > Code-Fallback (process.env.X || 'default'). Beachte: .env.local hat Vorrang vor .env.[env] — der Stolperstein von oben.

Docker Compose: docker compose run -e (CLI) > environment: > env_file: (bei Konflikten gewinnt die letzte Datei in der Liste) > Dockerfile-ENV (nicht analysiert).

Kubernetes: Inline-env: überschreibt immer envFrom: (Massenimport von ConfigMap/Secret; bei diesen gewinnt der letzte Eintrag in der Liste). Env-Werte werden beim Pod-Start eingefroren — das Bearbeiten einer referenzierten ConfigMap/Secret erreicht einen laufenden Pod nicht ohne Neustart oder Rollout. impact_preview markiert das.

Jedes Ergebnis enthält einen confidence-Grad und einen caveat-String, weil eine per Shell exportierte oder per CLI übergebene Überschreibung immer möglich und für statische Analyse nie sichtbar ist — envspeak sagt das explizit, statt eine Sicherheit vorzutäuschen, die es nicht hat.

Sicherheit

  • Keine Laufzeitabhängigkeiten. Der für Compose-/Kubernetes-Dateien verwendete YAML-Teilparser ist handgeschrieben und wird nicht von npm bezogen, sodass es keine Angriffsfläche durch Drittanbieter in der Lieferkette gibt. npm audit ist konstruktionsbedingt sauber.

  • Gegen Path-Traversal geschützt. Dateilesevorgänge werden gegen projectRoot aufgelöst und weigern sich, es zu verlassen, selbst wenn einem Tool-Aufruf ein präparierter relativer Pfad übergeben wird.

  • Gegen Prototype-Pollution geschützt. Objektschlüssel, die aus YAML-Inhalten geparst werden (__proto__, constructor, prototype), werden niemals für Eigenschaftszuweisungen verwendet.

  • Geheimnisse werden standardmäßig geschwärzt. Kubernetes-Secret-Werte werden nur als ab***yz angezeigt, niemals vollständig, unabhängig davon, welches Tool sie anzeigt.

  • Heuristiken zur Geheimnis-Wahrscheinlichkeit. Variablennamen und Wertformen (AWS-Keys, GitHub-Tokens, PEM-Blöcke, Strings mit hoher Entropie, die wie Zugangsdaten aussehen) werden markiert, mit .gitignore abgeglichen und als secretFlag/Risiko-Hotspot angezeigt, statt stillschweigend durchgereicht zu werden.

  • Begrenzte, nicht-backtrackende Regexes. Das für das Scannen von Code-Defaults verwendete Pattern-Matching begrenzt die Trefferlänge und vermeidet verschachtelte Quantoren, um ReDoS bei großen Dateien zu vermeiden.

  • Trotz dieser Schutzmaßnahmen liest envspeak jede Datei, auf die du es richtest — begrenze die files-Liste, die ein Agent übergeben kann, so, wie du jedes Tool mit Dateisystemzugriff begrenzen würdest.

Entwicklung

npm test   # zero dependencies — no install step needed

Lizenz

MIT

Available Tools

5 tools
config_manifestB

Compressed, project-wide summary of every config variable found — sources, domains, and risk hotspots (likely secrets in tracked files, variables read in code with no source). Load once per session instead of repeated resolve_variable calls.

Inputs: files (required), projectRoot, maxVariables.

diff_environmentsA

Resolves every variable under two different environment/service/workload selectors and reports what differs between them.

Inputs: files (required), environmentA (required), environmentB (required), variables, +1 more.

impact_previewB

Predicts which environments/services/workloads are actually affected if a variable's value in one file is changed (or removed) — including which contexts are shielded by a higher-precedence source.

Inputs: file (required), files (required), variable (required), newValue, +1 more.

resolve_variableA

Resolves what a config/env variable actually evaluates to across dotenv, docker-compose, and Kubernetes sources, and which source wins.

Inputs: files (required), variable (required), service, workload, +3 more.

trace_variableA

Lists every place a variable is defined or read across dotenv, compose, k8s, and code, and what wins in each discovered environment/service/workload context.

Inputs: files (required), variable (required), projectRoot.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    Most tools are clearly separated by purpose: manifest summarizes, impact previews, diff compares, and trace enumerates. The only real overlap is between resolve_variable and trace_variable, since both explain precedence and 'what wins,' though one targets the final value and the other targets all definition/read locations.

    Naming Consistency3/5

    resolve_variable and trace_variable follow a clean verb_noun pattern, but config_manifest and impact_preview are noun compounds, and diff_environments uses a terse verb. The names are readable and descriptive, but the naming convention is not uniform across the set.

    Tool Count5/5

    Five tools is well-scoped for a read-only environment/config analysis server. Each tool covers a distinct analytical need without redundancy or bloat, and the count feels intentional rather than thin or excessive.

    Completeness5/5

    The set covers the full analysis workflow: resolving a single variable, tracing all usages, generating a project-wide manifest, predicting change impact, and diffing environments. No obvious missing operation is needed for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides AI coding agents with structured, evidence-based diagnostics about the local development environment, detecting tech stack, runtime mismatches, dependency state, services, ports, and Git status without exposing secrets or using network calls.
      10
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Compares a project's .env file against its .env.example template to surface missing, extra, and empty keys, flag empty required variables, and produce paste-safe key inventories for tickets or sharing. Runs entirely on local files with every value redacted, so secrets are never echoed or uploaded.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Checks which .env, .git, keys and source maps Cloudflare Pages, Vercel, Netlify or Firebase would publish, before and after deploy. CLI, live probe, Claude Code hook, MCP server and GitHub Action.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables scanning a repository's source files for actual environment variable reads and diffing those names against .env.example or .env.sample. Returns a deterministic JSON report with the sync verdict, counts, and findings for used-but-undocumented, documented-but-unused, and missing-example vars, without ever reading values.
      60 npm
      MIT