@bwhichard/varlock-mcp

Local-first, repo-aware MCP server for Varlock.

This package is intended to be configured at the user level in MCP clients (Cursor, VS Code, Claude Code, Codex, Gemini), but it runs locally over stdio.

Install / Configure (User-Level)

This is a local stdio MCP server: your MCP client launches a local process and communicates over stdin/stdout. The server uses the process working directory as the project root, so no path argument is needed for most clients.

Claude Code

claude mcp add --scope user varlock-mcp --transport stdio -- bunx @bwhichard/varlock-mcp

Cursor (~/.cursor/mcp.json)

{
  “mcpServers”: {
    “varlock-mcp”: {
      “command”: “bunx”,
      “args”: [“@bwhichard/varlock-mcp”]
    }
  }
}

VS Code (Copilot MCP) (~/.vscode/mcp.json or workspace .vscode/mcp.json)

VS Code does not set the working directory automatically, so use the ${workspaceFolder} template variable:

{
  “servers”: {
    “varlock-mcp”: {
      “type”: “stdio”,
      “command”: “bunx”,
      “args”: [“@bwhichard/varlock-mcp”, “--root”, “${workspaceFolder}”]
    }
  }
}

Codex / Gemini

{
  “mcpServers”: {
    “varlock-mcp”: {
      “command”: “bunx”,
      “args”: [“@bwhichard/varlock-mcp”]
    }
  }
}

If your client does not have bunx, use npx -y @bwhichard/varlock-mcp instead.

Run

# from a project directory
bunx @bwhichard/varlock-mcp

Security

This MCP server never returns plaintext secret values in tool responses.

Configuration

Optional config files (JSON):

• User: ~/.config/varlock/mcp.json
• Repo: <project-root>/.varlock/mcp.json (overrides user config)

Supported keys:

{
  "entryPaths": ["./"], 
  "publicPrefixes": ["PUBLIC_", "NEXT_PUBLIC_", "VITE_"]
}

Notes:

• entryPaths are passed as Varlock entry points (directories or .env files).
• publicPrefixes are only used for linting suggestions and schema conversion defaults.

Tools

All tools return structured JSON (as a text payload) and never include resolved values.

• schema_discover: Loads the Varlock graph and returns which sources/files are participating (paths only) and the current env flag if present.
• schema_inspect: Returns schema metadata per key (sensitivity, type hints, requiredness, source label), no values.
• schema_doctor: Best-practice linting for .env.schema (sensitivity policy clarity, deprecated decorators, secret-looking tokens in schema/comments, public-prefix drift).
• env_validate: Resolves and validates env; returns per-key status (ok/missing/error) plus error messages, never values.
• scan_secrets: Resolves sensitive values locally and scans files for plaintext occurrences; returns finding locations only (file/line/col + key name).
• audit_schema_drift: Scans code for process.env.X/ENV.X usage and compares to schema keys; returns missing/unused lists and reference locations. For Varlock documentation search, add the hosted Varlock Docs MCP as a separate server:

claude mcp add --scope user --transport http varlock-docs-mcp https://docs.mcp.varlock.dev/mcp

Wizard: .env / .env.example → .env.schema

Three-step interactive flow:

1. schema_convert_start: Provide source env file paths; returns a sessionId, global questions, and a schema preview.
2. schema_convert_answer: Submit answers; returns an updated preview and indicates readiness.
3. schema_convert_commit: Writes the .env.schema only when confirm=true. Uses backups by default and refuses to overwrite unless overwrite=true.

Publishing

Published via GitHub Actions using an npm automation token (NPM_TOKEN repo secret).

• Workflow: .github/workflows/publish-varlock-mcp.yml
• Trigger: push a tag matching varlock-mcp-v* (e.g. varlock-mcp-v0.1.3)