{
  "markdown": "# EnvSpeak\n\nMCP server and CLI that resolves config/env-var cascade across `.env` files, Docker Compose, and Kubernetes — tells AI agents (and you) what a variable actually evaluates to at runtime, and why.\n\nSame problem shape as CSS cascade — several sources, non-obvious precedence rules, and a value that \"wins\" only because of where it's defined — applied to application configuration instead of stylesheets. A sibling project to [stylesafe](https://github.com/Patrizzos/stylesafe) and [stylespeak](https://github.com/Patrizzos/stylespeak), which do the same thing for CSS.\n\n## The problem\n\nA real app's config comes from `.env`, `.env.local`, `.env.production`, `docker-compose.yml` (`environment:` vs `env_file:`), Kubernetes `ConfigMap`/`Secret` objects, and hard-coded fallbacks in code — five-plus layers, each with its own precedence rules that don't compose the way you'd guess. The best-known gotcha: a plain `.env.local` overrides `.env.production` unless you also have a `.env.production.local` — because \"local\" outranks \"environment-specific\" in the conventional dotenv cascade. An agent editing config has no way to know what a variable actually resolves to, or what breaks if it changes one layer.\n\n## Tools\n\n- **`resolve_variable`** — what does `DATABASE_URL` actually evaluate to, and which file wins?\n- **`trace_variable`** — every place this variable is set, across every domain and environment.\n- **`impact_preview`** — if I change this value in this file, what actually changes downstream — and what's shielded by something higher-precedence?\n- **`config_manifest`** — a compressed, whole-project summary: every variable, its sources, and risk hotspots (secrets sitting in a tracked file, variables read in code with no fallback and no source anywhere).\n- **`diff_environments`** — resolve every variable under two environments/services/workloads and see what's actually different between them.\n\n## Install\n\n```bash\nnpm install -g @patrizzos/envspeak\n```\n\n### As an MCP server\n\n```json\n{\n  \"mcpServers\": {\n    \"envspeak\": {\n      \"command\": \"envspeak\"\n    }\n  }\n}\n```\n\n### As a CLI\n\n```bash\nenvspeak resolve DATABASE_URL --environment production\nenvspeak trace LOG_LEVEL\nenvspeak impact --file .env --variable LOG_LEVEL --newValue debug\nenvspeak manifest\nenvspeak diff --a '{\"nodeEnv\":\"development\"}' --b '{\"nodeEnv\":\"production\"}'\n```\n\nIf `--files` is omitted, envspeak auto-discovers `.env*`, Compose, and Kubernetes manifest files under `--projectRoot` (default: current directory). Pass `--files a,b,c` to scope it explicitly — recommended for MCP calls, so the agent controls exactly what's read.\n\n## Precedence conventions encoded\n\n**dotenv** (Next.js/Vite-style, the de facto standard): `process.env` (shell) > `.env.[env].local` > `.env.local` > `.env.[env]` > `.env` > code fallback (`process.env.X || 'default'`). Note `.env.local` outranks `.env.[env]` — the gotcha above.\n\n**Docker Compose**: `docker compose run -e` (CLI) > `environment:` > `env_file:` (last file in the list wins on conflicts) > Dockerfile `ENV` (not analyzed).\n\n**Kubernetes**: inline `env:` always overrides `envFrom:` (bulk `ConfigMap`/`Secret` import; last entry in the list wins among those). Env values are frozen at pod start — editing a referenced `ConfigMap`/`Secret` does not reach a running pod without a restart or rollout. `impact_preview` flags this.\n\nEvery result includes a `confidence` level and a `caveat` string, because a shell-exported or CLI-passed override is always possible and never visible to static analysis — envspeak says so explicitly rather than pretending certainty it doesn't have.\n\n## Security\n\n- **Zero runtime dependencies.** The YAML subset parser used for Compose/Kubernetes files is hand-written rather than pulled in from npm, so there's no third-party supply-chain surface. `npm audit` is clean by construction.\n- **Path-traversal guarded.** File reads are resolved against `projectRoot` and refuse to escape it, even if a tool call is given a crafted relative path.\n- **Prototype-pollution guarded.** Object keys parsed from YAML content (`__proto__`, `constructor`, `prototype`) are never used for property assignment.\n- **Secrets are redacted by default.** Kubernetes `Secret` values are shown only as `ab***yz`, never in full, regardless of which tool surfaces them.\n- **Secret-likelihood heuristics.** Variable names and value shapes (AWS keys, GitHub tokens, PEM blocks, high-entropy credential-shaped strings) are flagged, cross-referenced against `.gitignore`, and surfaced as a `secretFlag` / risk hotspot rather than silently passed through.\n- **Bounded, non-backtracking regexes.** Pattern matching used for code-default scanning caps match length and avoids nested quantifiers to avoid ReDoS on large files.\n- Regardless of these guards, envspeak reads whatever files you point it at — scope the `files` list an agent can pass, the same way you'd scope any tool with filesystem access.\n\n## Development\n\n```bash\nnpm test   # zero dependencies — no install step needed\n```\n\n## License\n\nMIT\n",
  "bytes": 5047,
  "sha": "4cdf383b439480425b1f0be83e1e7974a7857eae489d86f4ad0d53cbe5642a41",
  "repo_slug": "patrizzos/envspeak",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_patrizzos_envspeak_d5dc8012/readme"
}