preflight-mcp

A Model Context Protocol (MCP) server that gives Claude Code structured, on-demand access to your machine's environment — OS, runtimes, SDKs, editors, browsers, and more.

Without preflight, Claude guesses: wrong package manager, wrong Python version, missing SDKs. Preflight solves this in two parts:

1. A detect script snapshots your environment into ~/.preflight/env-config.json (one-time, re-run when things change)
2. An MCP server exposes tools so Claude can read that snapshot and generate project rules on demand

Quick Start

Step 1 — Run the detect script (one time, re-run when things change)

# Windows
powershell -ExecutionPolicy Bypass -File preflight/detect.ps1

# macOS / Linux
bash preflight/detect.sh

Step 2 — Install the MCP server

npx @malikasana/preflight-mcp

Step 3 — Register with Claude Code

claude mcp add preflight-mcp -- npx @malikasana/preflight-mcp

Restart Claude Code. Done — Claude now knows exactly what's on your machine.

Installation

Using npx (no install required)

# Run directly
npx @malikasana/preflight-mcp

# Or install globally
npm install -g @malikasana/preflight-mcp

From source

# Windows — generate the snapshot first
powershell -ExecutionPolicy Bypass -File "preflight\detect.ps1"

# Install MCP server dependencies
cd preflight-mcp
npm install

# macOS / Linux
bash preflight/detect.sh
cd preflight-mcp && npm install

The snapshot is written to ~/.preflight/env-config.json on all platforms.

Register with Claude Code

Option A — CLI (recommended)

claude mcp add preflight-mcp -- npx @malikasana/preflight-mcp

Option B — Edit settings.json manually

Add to ~/.claude/settings.json (global) or .claude/settings.json (project-level):

{
  "mcpServers": {
    "preflight-mcp": {
      "command": "npx",
      "args": ["@malikasana/preflight-mcp"]
    }
  }
}

After registering, Claude can call get_environment to read your full machine snapshot.

Adding custom fields

The extensions array in ~/.preflight/env-config.json is for tools the detect script doesn't cover. Edit it directly — the detect script leaves this array untouched when it re-runs.

{
  "extensions": [
    {
      "name": "Rust",
      "version": "1.82.0",
      "added_at": "2025-01-15T10:00:00+00:00",
      "description": "Installed via rustup. Toolchain at ~/.cargo/bin."
    },
    {
      "name": "Java",
      "version": "21.0.9",
      "added_at": "2025-01-15T10:00:00+00:00",
      "description": "JBR bundled with Android Studio at /path/to/jbr."
    }
  ]
}

Keeping it current

Re-run the detect script whenever you install new tools, update runtimes, or change SDK paths. The MCP server reads the file fresh on every call — no restart needed.

Layer 1 — Program scanner (v1.3.0)

The detect scripts automatically detect 19 programs and add an installed_programs section to env-config.json:

| Category | Programs | |---|---| | Databases | Redis, PostgreSQL, MongoDB, MySQL, SQLite | | Web servers | Nginx, Apache | | Languages | Rust, Go, Ruby | | AI & ML | Ollama (+ models list), CUDA | | Dev tools | Android Studio, PyCharm, Postman, TablePlus | | Cloud CLIs | AWS CLI, Google Cloud CLI, Azure CLI |

Detection priority: env vars → registry/common paths → PATH lookup. All missing programs are recorded as "not installed" — never throws errors.

preflight.json — self-registration

Any tool can ship a preflight.json in its install directory. The detect scripts discover these automatically and merge them into extensions. See preflight-spec.md for the full schema.

User-configurable fallbacks

Create mcp-server/user-fallback.json to add your own package fallbacks (not committed to git):

{
  "npm":    { "my-private-pkg": { "version": "2.1.0" } },
  "pypi":   { "internal-lib":  { "version": "0.4.1" } },
  "pubdev": { "company_pkg":   { "version": "1.0.0" } }
}

Entries in user-fallback.json override the built-in fallback table for any registry. The file is gitignored — safe for private or internal package names.

Tool reference

| Tool | Description | |------|-------------| | get_environment | Returns the full JSON contents of ~/.preflight/env-config.json | | get_package_config | Fetches latest version and install info for npm (default), PyPI, and pub.dev packages from live registries with 1 hour cache and static fallback. Pass registry: "pypi" or registry: "pubdev" to query Python or Dart/Flutter packages. Extend built-in fallbacks via user-fallback.json. | | generate_claude_md | Generates a CLAUDE.md file in the current working directory with shell rules, package manager, CDN preference, versions, Flutter/Android setup, and Windows gotchas — all derived from your env-config.json |

Usage examples

get_environment

Prompt: Call get_environment to learn what's installed on this machine.

Claude reads ~/.preflight/env-config.json and knows your OS, Node version, Python version, Flutter setup, installed editors, and more — instantly.

get_package_config

Prompt: Use get_package_config with ["three", "gsap", "lenis"]

Returns:

[
  {
    "package": "three",
    "version": "0.184.0",
    "install": "npm install three",
    "cdn": {
      "jsdelivr_esm": "https://cdn.jsdelivr.net/npm/[email protected]/+esm",
      "jsdelivr_bundle": "https://cdn.jsdelivr.net/npm/[email protected]/bundled/three.min.js",
      "unpkg": "https://unpkg.com/[email protected]"
    }
  }
]

Each entry includes the exact pinned version, the npm install command, and CDN URL variants. Results are cached for 1 hour; a static fallback is used if the registry is unreachable.

PyPI (Python packages):

Prompt: Use get_package_config with ["requests", "fastapi"] and registry: "pypi"

Returns:

[
  {
    "package": "requests",
    "version": "2.34.2",
    "install": "pip install requests",
    "registry": "pypi"
  },
  {
    "package": "fastapi",
    "version": "0.115.12",
    "install": "pip install fastapi",
    "registry": "pypi"
  }
]

pub.dev (Dart / Flutter packages):

Prompt: Use get_package_config with ["dio", "riverpod"] and registry: "pubdev"

Returns:

[
  {
    "package": "dio",
    "version": "5.9.2",
    "install": "dio: ^5.9.2",
    "registry": "pubdev",
    "pubspec": true
  },
  {
    "package": "riverpod",
    "version": "3.2.1",
    "install": "riverpod: ^3.2.1",
    "registry": "pubdev",
    "pubspec": true
  }
]

pub.dev results use pubspec.yaml syntax for the install field. Add them directly under dependencies: in your pubspec.yaml, then run flutter pub get.

generate_claude_md

Prompt: Call generate_claude_md to set up project rules for this repo.

Claude writes a CLAUDE.md in your current working directory containing shell rules, package manager preference, CDN latency rankings, detected versions, Flutter/Android paths, and Windows-specific gotchas — all derived automatically from your env snapshot.