envspeak
EnvSpeak
MCP 서버 및 CLI로, .env 파일, Docker Compose, Kubernetes 전반의 config/env-var 캐스케이드를 해석합니다 — AI 에이전트(그리고 여러분)에게 변수가 런타임에 실제로 평가되는 값과 그 이유를 알려줍니다.
CSS 캐스케이드와 동일한 문제 형태 — 여러 소스, 비직관적인 우선순위 규칙, 정의된 위치 때문에 "승리"하는 값 — 을 스타일시트 대신 애플리케이션 구성에 적용한 것입니다. CSS에 대해 동일한 작업을 수행하는 stylesafe 및 stylespeak의 자매 프로젝트입니다.
문제
실제 앱의 구성은 .env, .env.local, .env.production, docker-compose.yml (environment: vs env_file:), Kubernetes ConfigMap/Secret 객체, 코드의 하드코딩된 폴백에서 비롯됩니다 — 5개 이상의 레이어로, 각각 예상한 대로 조합되지 않는 자체 우선순위 규칙을 가집니다. 가장 잘 알려진 함정: .env.production.local도 함께 있지 않다면 일반 .env.local이 .env.production을 덮어씁니다 — 관례적인 dotenv 캐스케이드에서 "local"이 "환경별"보다 우선하기 때문입니다. 구성을 편집하는 에이전트는 변수가 실제로 무엇으로 해석되는지, 또는 한 레이어를 변경하면 무엇이 깨지는지 알 방법이 없습니다.
Related MCP server: @mcpx-digital/env-check
도구
resolve_variable—DATABASE_URL이 실제로 평가되는 값은 무엇이며, 어떤 파일이 우선할까요?trace_variable— 이 변수가 설정된 모든 위치를 모든 도메인과 환경에 걸쳐 추적합니다.impact_preview— 이 파일에서 이 값을 변경하면 다운스트림에서 실제로 무엇이 바뀌며, 더 높은 우선순위의 무언가에 의해 보호되는 것은 무엇일까요?config_manifest— 압축된 전체 프로젝트 요약: 모든 변수, 해당 소스, 위험 지점(추적되는 파일에 있는 비밀값, 폴백도 소스도 없이 코드에서 읽히는 변수).diff_environments— 두 환경/서비스/워크로드에서 모든 변수를 해석하고 실제로 무엇이 다른지 확인합니다.
설치
npm install -g @patrizzos/envspeakMCP 서버로
{
"mcpServers": {
"envspeak": {
"command": "envspeak"
}
}
}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"}'--files를 생략하면 envspeak는 --projectRoot(기본값: 현재 디렉터리) 아래의 .env*, Compose, Kubernetes 매니페스트 파일을 자동으로 발견합니다. --files a,b,c를 전달하여 명시적으로 범위를 지정하세요 — MCP 호출에 권장되며, 에이전트가 정확히 무엇을 읽을지 제어할 수 있습니다.
인코딩된 우선순위 규칙
dotenv (Next.js/Vite 스타일, 사실상의 표준): process.env (셸) > .env.[env].local > .env.local > .env.[env] > .env > 코드 폴백 (process.env.X || 'default'). .env.local이 .env.[env]보다 우선한다는 점에 유의하세요 — 위에서 언급한 함정입니다.
Docker Compose: docker compose run -e (CLI) > environment: > env_file: (충돌 시 목록의 마지막 파일이 우선) > Dockerfile ENV (분석되지 않음).
Kubernetes: 인라인 env:는 항상 envFrom:을 덮어씁니다 (대량 ConfigMap/Secret 가져오기; 그중에서 목록의 마지막 항목이 우선). 환경 변수 값은 파드 시작 시 고정됩니다 — 참조된 ConfigMap/Secret을 편집해도 재시작이나 롤아웃 없이는 실행 중인 파드에 도달하지 않습니다. impact_preview가 이를 표시합니다.
모든 결과에는 confidence 수준과 caveat 문자열이 포함됩니다. 셸에서 내보내거나 CLI로 전달된 오버라이드는 항상 가능하며 정적 분석에는 절대 보이지 않기 때문입니다 — envspeak는 가지지 못한 확신을 가장하기보다 이를 명시적으로 밝힙니다.
보안
런타임 의존성 제로. Compose/Kubernetes 파일에 사용되는 YAML 부분집합 파서는 npm에서 가져오는 대신 직접 작성되었으므로 제3자 공급망 표면이 없습니다.
npm audit은 구조적으로 깨끗합니다.경로 탐색 방지. 파일 읽기는
projectRoot를 기준으로 해석되며, 도구 호출에 조작된 상대 경로가 주어져도 이를 벗어나지 않습니다.프로토타입 오염 방지. YAML 콘텐츠에서 파싱된 객체 키(
__proto__,constructor,prototype)는 속성 할당에 절대 사용되지 않습니다.비밀값은 기본적으로 마스킹됩니다. Kubernetes
Secret값은 어떤 도구가 표시하든ab***yz형태로만 표시되며 전체가 노출되지 않습니다.비밀값 가능성 휴리스틱. 변수 이름과 값 형태(AWS 키, GitHub 토큰, PEM 블록, 고엔트로피 자격 증명 형태 문자열)가 플래그로 표시되고,
.gitignore와 교차 참조되어 조용히 통과되는 대신secretFlag/ 위험 지점으로 표면화됩니다.제한적이고 역추적 없는 정규식. 코드 기본값 스캔에 사용되는 패턴 매칭은 일치 길이를 제한하고 중첩 수량자를 피하여 대용량 파일에서 ReDoS를 방지합니다.
이러한 보호 장치와 무관하게 envspeak는 지정한 파일을 모두 읽습니다 — 에이전트가 전달할 수 있는
files목록의 범위를 파일시스템 접근 권한이 있는 도구를 범위 지정하는 것과 같은 방식으로 제한하세요.
개발
npm test # zero dependencies — no install step needed라이선스
MIT
Available Tools
5 toolsconfig_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Investigate alerts, run root-cause analysis, and ask production questions with Resolve.
Find your AI agent's likely failure mode, get runtime settings, and clarify ambiguous prompts.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides 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.10Apache 2.0
- AlicenseAqualityCmaintenanceCompares 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.3MIT
- AlicenseNot gradedqualityBmaintenanceChecks 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.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT