MCP Tool Reference

Envark exposes 9 MCP tools that AI assistants can use to analyze and manage environment variables. Each tool returns structured JSON data that the AI formats for human consumption.

Tool Index

get_env_map

Complete variable inventory

get_env_risk

Risk analysis

get_missing_envs

Missing variables

get_duplicates

Duplicate finder

get_undocumented

Undocumented variables

get_env_usage

Variable deep dive

get_env_graph

Dependency graph

validate_env_file

File validation

generate_env_template

Template generation

get_env_map

Returns the complete environment variable map for the project, with optional filtering.

Input Schema

{
  "projectPath": "string (optional)",
  "filter": "all | missing | unused | risky | undocumented (optional)"
}

Parameters:

projectPath — Path to project directory. Defaults to current working directory.
filter — Filter variables by status:
- all (default) — All variables
- missing — Used in code but not defined
- unused — Defined but never used
- risky — Critical or high risk level
- undocumented — Not in .env.example

Output Schema

{
  "summary": {
    "totalEnvVars": 24,
    "defined": 20,
    "used": 22,
    "missing": 3,
    "undocumented": 5,
    "dead": 2,
    "critical": 1
  },
  "variables": [
    {
      "name": "DATABASE_URL",
      "definedIn": [".env", ".env.local"],
      "usedIn": ["src/db.ts", "src/migrations/run.ts"],
      "languages": ["typescript"],
      "hasDefault": false,
      "isDocumented": true,
      "riskLevel": "medium",
      "issueCount": 1
    }
  ],
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 1834
  }
}

Example Usage

Ask your AI:

“Show me all environment variables in my project”

“What variables are missing?”

“Which variables are defined but never used?“

get_env_risk

Returns environment variables sorted by risk level with detailed issue explanations.

Input Schema

{
  "projectPath": "string (optional)",
  "minRisk": "info | low | medium | high | critical (optional)"
}

Parameters:

projectPath — Path to project directory. Defaults to current working directory.
minRisk — Minimum risk level to include. Defaults to info (shows all).

Output Schema

{
  "summary": {
    "critical": 2,
    "high": 1,
    "medium": 5,
    "low": 8,
    "info": 10
  },
  "riskReport": [
    {
      "name": "STRIPE_SECRET_KEY",
      "riskLevel": "critical",
      "issues": [
        {
          "type": "MISSING",
          "severity": "critical",
          "message": "Used in code but never defined",
          "recommendation": "Add STRIPE_SECRET_KEY to your .env file"
        }
      ],
      "usageCount": 3,
      "files": ["src/payments/stripe.ts", "src/api/checkout.ts"]
    }
  ],
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": true,
    "duration": 245
  }
}

Risk Levels

Level	Description
critical	Used but never defined, no default. Will cause runtime crashes.
high	Secret-like names in committed files, or multiple usages with no default
medium	Used without definition but has default value
low	Undocumented or minor issues
info	Fully configured, no issues

Example Usage

“Are there any critical environment variable issues?”

“Show me variables with high security risk”

“What are the most dangerous variables in my project?“

get_missing_envs

Returns environment variables used in code but never defined anywhere, with no default value. These will cause runtime crashes.

Input Schema

{
  "projectPath": "string (optional)"
}

Output Schema

{
  "missing": [
    {
      "name": "API_SECRET",
      "usages": [
        {
          "file": "src/api/auth.ts",
          "line": 42,
          "context": "const secret = process.env.API_SECRET;"
        }
      ],
      "usageCount": 3,
      "languages": ["typescript"],
      "dangerLevel": "critical"
    }
  ],
  "totalMissing": 3,
  "willCauseRuntimeCrash": 2,
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 1523
  }
}

Danger Levels

critical — Used in 3+ places. Guaranteed production crash.
high — Used in 1-2 places. Will crash when that code path executes.

Example Usage

“What environment variables am I missing?”

“Will my app crash due to missing env vars?”

“Show me undefined environment variables”

get_duplicates

Finds environment variables with conflicting definitions across multiple .env files, and similar variable names that might represent the same concept.

Input Schema

{
  "projectPath": "string (optional)"
}

Output Schema

{
  "duplicates": [
    {
      "variableName": "DATABASE_URL",
      "type": "value_conflict",
      "values": [
        {
          "file": ".env",
          "value": "postgresql://localhost/dev"
        },
        {
          "file": ".env.production",
          "value": "postgresql://prod-server/db"
        }
      ],
      "recommendation": "Consolidate DATABASE_URL to have the same value across all .env files, or use environment-specific values intentionally."
    },
    {
      "variableName": "DB_URL",
      "type": "similar_name",
      "similarNames": ["DB_URL", "DATABASE_URL", "DB_CONNECTION_STRING"],
      "recommendation": "Consider standardizing these variable names: DB_URL, DATABASE_URL, DB_CONNECTION_STRING. They may represent the same concept."
    }
  ],
  "valueConflicts": 1,
  "similarNameGroups": 1,
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": true,
    "duration": 892
  }
}

Duplicate Types

value_conflict — Same variable defined with different values in multiple files
similar_name — Variables with similar names (e.g., DB_URL vs DATABASE_URL)

Example Usage

“Are there any conflicting environment variable definitions?”

“Do I have duplicate or similar variable names?”

“Check for environment variable name inconsistencies”

get_undocumented

Returns environment variables not present in .env.example or lacking documentation.

Input Schema

{
  "projectPath": "string (optional)"
}

Output Schema

{
  "undocumented": [
    {
      "name": "REDIS_URL",
      "usedIn": ["src/cache.ts", "src/sessions.ts"],
      "languages": ["typescript"],
      "usageContext": "const redis = new Redis(process.env.REDIS_URL);",
      "suggestedDescription": "Redis connection string",
      "isSecret": false
    }
  ],
  "totalUndocumented": 5,
  "hasEnvExample": true,
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 1234
  }
}

Example Usage

“What environment variables are missing from .env.example?”

“Which variables need documentation?”

“Show me undocumented environment variables”

get_env_usage

Deep dive into a specific environment variable — shows every usage, risk profile, and recommendations.

Input Schema

{
  "variableName": "string (required)",
  "projectPath": "string (optional)"
}

Parameters:

variableName — Name of the environment variable to analyze (required)
projectPath — Path to project directory. Defaults to current working directory.

Output Schema

{
  "found": true,
  "variable": {
    "name": "DATABASE_URL",
    "definitions": [
      {
        "file": ".env",
        "line": 12,
        "language": "env",
        "context": "DATABASE_URL=postgresql://localhost/dev",
        "hasDefault": false
      }
    ],
    "usages": [
      {
        "file": "src/db/connection.ts",
        "line": 5,
        "language": "typescript",
        "context": "const db = new Database(process.env.DATABASE_URL);",
        "hasDefault": false
      }
    ],
    "riskLevel": "medium",
    "issues": [
      {
        "type": "NO_DEFAULT",
        "message": "Used without fallback value",
        "recommendation": "Add a default value or validation"
      }
    ],
    "summary": {
      "totalUsages": 8,
      "totalDefinitions": 1,
      "languages": ["typescript", "javascript"],
      "hasDefault": false,
      "isDocumented": true,
      "definedInEnvFile": true,
      "definedInExample": true
    },
    "recommendations": [
      "Add a fallback value for development",
      "Consider using a validation library like zod"
    ]
  },
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": true,
    "duration": 456
  }
}

Example Usage

“Show me everywhere DATABASE_URL is used”

“What does the JWT_SECRET variable do?”

“Analyze the API_KEY environment variable”

get_env_graph

Returns the dependency graph of environment variables — shows which ones cluster together, which are load-bearing, and which are isolated.

Input Schema

{
  "projectPath": "string (optional)"
}

Output Schema

{
  "graph": {
    "nodes": [
      {
        "name": "DATABASE_URL",
        "usageCount": 8,
        "fileCount": 5,
        "cluster": "Database",
        "isLoadBearing": true,
        "connections": 3
      }
    ],
    "edges": [
      {
        "from": "DATABASE_URL",
        "to": "DB_POOL_SIZE",
        "weight": 5,
        "sharedFiles": ["src/db/connection.ts", "src/db/pool.ts"]
      }
    ],
    "adjacencyList": {
      "DATABASE_URL": ["DB_POOL_SIZE", "DB_SSL_MODE"],
      "DB_POOL_SIZE": ["DATABASE_URL"]
    }
  },
  "clusters": [
    {
      "name": "Database",
      "variables": ["DATABASE_URL", "DB_POOL_SIZE", "DB_SSL_MODE"],
      "size": 3,
      "description": "Database connection and configuration"
    }
  ],
  "loadBearingVars": ["DATABASE_URL", "API_KEY"],
  "isolatedVars": ["FEATURE_FLAG_X"],
  "stats": {
    "totalNodes": 24,
    "totalEdges": 45,
    "totalClusters": 6,
    "avgConnections": 3.75
  },
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 1987
  }
}

Graph Concepts

Node — An environment variable
Edge — Connection between variables (used in same files)
Cluster — Group of related variables (e.g., all database config)
Load-bearing — Variables used in many files (critical infrastructure)
Isolated — Variables with no connections to others

Example Usage

“Show me the dependency graph of environment variables”

“Which variables are most critical to my app?”

“How are my environment variables related?“

validate_env_file

Validates a .env file against codebase requirements. Finds variables in the file that code never uses, variables code needs that aren’t in the file, and variables with empty or placeholder values.

Input Schema

{
  "envFilePath": "string (required)",
  "projectPath": "string (optional)"
}

Parameters:

envFilePath — Path to the .env file to validate (relative to project or absolute)
projectPath — Path to project directory. Defaults to current working directory.

Output Schema

{
  "valid": false,
  "envFilePath": ".env",
  "results": {
    "passed": [
      {
        "variable": "PORT",
        "status": "pass",
        "value": "3000"
      }
    ],
    "warnings": [
      {
        "variable": "UNUSED_VAR",
        "status": "warning",
        "issue": "Defined in env file but never used in code",
        "suggestion": "Remove if not needed, or verify it's used indirectly",
        "value": "some-value"
      }
    ],
    "failed": [
      {
        "variable": "API_KEY",
        "status": "fail",
        "issue": "Placeholder value detected",
        "suggestion": "Replace with actual production value",
        "value": "your-api-key-here"
      },
      {
        "variable": "DATABASE_URL",
        "status": "fail",
        "issue": "Used in code but missing from env file",
        "suggestion": "Add this variable to your env file"
      }
    ]
  },
  "summary": {
    "total": 15,
    "passed": 10,
    "warnings": 2,
    "failed": 3,
    "unusedInFile": 2,
    "missingFromFile": 1
  },
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": true,
    "duration": 678
  }
}

Validation Statuses

Status	Description
pass	Variable is properly defined and used
warning	Non-critical issue (e.g., unused variable)
fail	Critical issue (e.g., placeholder value, missing variable)

Example Usage

“Validate my .env file”

“Is my .env.production file correct?”

“Check if .env has all required variables”

generate_env_template

Scans the entire codebase and generates a complete .env.example file from scratch. Groups variables by cluster, adds inferred descriptions, and marks which are required vs optional.

Input Schema

{
  "projectPath": "string (optional)",
  "outputPath": "string (optional)"
}

Parameters:

projectPath — Path to project directory. Defaults to current working directory.
outputPath — Path to write the generated file. If not provided, only returns content without writing.

Output Schema

{
  "content": "# Environment Variables\n# Generated by Envark\n...",
  "variableCount": 18,
  "clusterCount": 5,
  "requiredCount": 8,
  "optionalCount": 10,
  "writtenTo": ".env.example",
  "metadata": {
    "projectPath": "/path/to/project",
    "scannedFiles": 127,
    "cacheHit": false,
    "duration": 2134
  }
}

Generated Content Example

.env.example (generated)

# Environment Variables
# Generated by Envark
#
# Required variables are marked with [REQUIRED]
# Optional variables (with defaults) are marked with [OPTIONAL]

# ============================================
# Database
# ============================================

# Database connection string [REQUIRED]
DATABASE_URL=your-secret-here

# Database host address [OPTIONAL]
DB_HOST=localhost

# Database port number [OPTIONAL]
DB_PORT=5432

# ============================================
# Authentication
# ============================================

# Secret key for JWT token signing [REQUIRED]
JWT_SECRET=your-secret-here

# Session secret for cookie encryption [REQUIRED]
SESSION_SECRET=your-secret-here

# ============================================
# API
# ============================================

# Stripe payment configuration [REQUIRED]
STRIPE_SECRET_KEY=your-secret-here

# SendGrid email service configuration [OPTIONAL]
SENDGRID_API_KEY=

Example Usage

“Generate a .env.example file for my project”

“Create an environment template”

“What should my .env.example look like?”

Common Parameters

All tools support these optional parameters:

projectPath

Type: string
Default: Current working directory
Description: Path to the project to analyze

Example:

{
  "projectPath": "/Users/alex/projects/my-app"
}

Metadata Response

All tools return a metadata object with:

{
  "projectPath": "/path/to/project",
  "scannedFiles": 127,
  "cacheHit": true,
  "duration": 1234
}

projectPath — Resolved absolute path to the project
scannedFiles — Number of files scanned
cacheHit — Whether results were loaded from cache
duration — Time taken in milliseconds

Error Handling

All tools return errors in this format:

{
  "error": "Error message describing what went wrong"
}

Common errors:

Project not found — Invalid projectPath
Permission denied — Can’t read project files
Invalid parameter — Missing required parameter or invalid value

Performance Tips

Use caching

Envark automatically caches scan results in .envark/cache.json. The cache is invalidated when:

Any source file changes (checked via mtime)
Any .env file changes
Cache is older than 1 hour

For best performance, run multiple tools in sequence — later tools will use the cached scan.

Filter early

When you only need specific variables, use the filter parameter in get_env_map rather than retrieving all variables and filtering in the AI.

// Good - filter server-side
{ "filter": "missing" }

// Less efficient - retrieve all, filter client-side
{ "filter": "all" }

Configure .gitignore properly

Ensure your .gitignore excludes large directories:

node_modules/
.git/
dist/
build/
.next/
coverage/

Envark respects .gitignore by default.

Next Steps

Setup Guide

Configure Envark in your IDE

Usage Examples

See real conversations using these tools

Get Started

Core Features

CLI Reference

MCP Integration

Guides

​Tool Index

get_env_map

get_env_risk

get_missing_envs

get_duplicates

get_undocumented

get_env_usage

get_env_graph

validate_env_file

generate_env_template

​get_env_map

​Input Schema

​Output Schema

​Example Usage

​get_env_risk

​Input Schema

​Output Schema

​Risk Levels

​Example Usage

​get_missing_envs

​Input Schema

​Output Schema

​Danger Levels

​Example Usage

​get_duplicates

​Input Schema

​Output Schema

​Duplicate Types

​Example Usage

​get_undocumented

​Input Schema

​Output Schema

​Example Usage

​get_env_usage

​Input Schema

​Output Schema

​Example Usage

​get_env_graph

​Input Schema

​Output Schema

​Graph Concepts

​Example Usage

​validate_env_file

​Input Schema

​Output Schema

​Validation Statuses

​Example Usage

​generate_env_template

​Input Schema

​Output Schema

​Generated Content Example

​Example Usage

​Common Parameters

​projectPath

​Metadata Response

​Error Handling

​Performance Tips

​Next Steps

Setup Guide

Usage Examples

Build docs developers (and LLMs) love

Tool Index

get_env_map

Input Schema

Output Schema

Example Usage

get_env_risk

Input Schema

Output Schema

Risk Levels

Example Usage

get_missing_envs

Input Schema

Output Schema

Danger Levels

Example Usage

get_duplicates

Input Schema

Output Schema

Duplicate Types

Example Usage

get_undocumented

Input Schema

Output Schema

Example Usage

get_env_usage

Input Schema

Output Schema

Example Usage

get_env_graph

Input Schema

Output Schema

Graph Concepts

Example Usage

validate_env_file

Input Schema

Output Schema

Validation Statuses

Example Usage

generate_env_template

Input Schema

Output Schema

Generated Content Example

Example Usage

Common Parameters

projectPath

Metadata Response

Error Handling

Performance Tips

Next Steps