Muhammad Ali

Posted on May 26

I Built an MCP Server That Gives Claude Code Accurate Knowledge of Your Machine — Before It Touches Anything

#claudecode #devtools #mcp #opensource

I started using Claude Code recently and I noticed something that bothered me. Before doing any real work, Claude was wasting a lot of tokens just guessing my system configuration — wrong shell, wrong package versions, wrong CDN URLs. It tried to run bash commands on my Windows machine. It picked outdated CDN links. It assumed the wrong package manager. All of this before it even started the actual task.

That frustration gave me an idea.

The Problem

Every time you start a Claude Code session, Claude has no idea what your machine looks like. It doesn't know if you're on Windows or Linux. It doesn't know which version of Node you have. It doesn't know which CDN is fastest from your location. It figures all of this out by trial and error — and every guess costs tokens.

The worst part is that this happens every single session. The same mistakes, the same wasted tokens, over and over again.

The Idea

What if there was a system that helped AI know exactly what your machine is configured with, before it does anything?

That question led me to build preflight — a two-part system:

A detection script that scans your machine and snapshots your full environment
An MCP server that Claude Code can call to read that snapshot instantly

What It Detects

Running the detection script gives Claude everything it needs:

OS, shell, and execution policy
Node, Python, Flutter, Dart, Git, Docker versions
Android SDK, Java, VS Code extensions
Installed programs — databases, web servers, cloud CLIs, AI tools
Which CDN is actually fastest from your location (measured live)
SSH keys, environment variables, disk space

All of this gets written to ~/.preflight/env-config.json — a single file that lives on your machine and gets updated whenever you run the script.

What the MCP Server Does

The MCP server exposes three tools that Claude Code can call:

get_environment — returns your full machine snapshot. Claude calls this at the start of a session and instantly knows your exact setup. No guessing, no trial and error.

get_package_config — fetches live package versions from npm, PyPI, and pub.dev. So Claude never uses an outdated CDN URL or wrong package version again. It has a static fallback for when your internet is slow, and caches results for one hour.

generate_claude_md — automatically generates a CLAUDE.md file for any project, derived directly from your environment snapshot. Shell rules, package manager, CDN preference, Flutter setup, Windows gotchas — all generated in seconds.

The Token Cost

The whole point of preflight is efficiency. So the MCP server itself is designed to cost almost nothing — around 400 tokens per call. Compare that to the thousands Claude wastes guessing your setup wrong.

The preflight.json Standard

While building this, I realized something bigger. What if every program could register its own configuration with preflight? Instead of preflight hunting for Redis config files or PostgreSQL ports, Redis could just ship a preflight.json that says exactly how it's configured.

{
  "preflight-spec": "1.0",
  "name": "Redis",
  "version": "7.2.0",
  "config": {
    "port": 6379,
    "config_file": "/etc/redis/redis.conf",
    "cli_command": "redis-cli"
  }
}

Preflight discovers these files automatically by scanning your PATH directories. If this standard gets adopted by the community, Claude will know how to use any tool on your machine without any manual setup — ever.

How I Built It

I built preflight using Claude Code itself, autonomously, under my supervision. The irony is not lost on me — I used Claude Code to build a tool that makes Claude Code better.

The whole system was built over a few days. Detection scripts in PowerShell and bash, an MCP server in Node.js, three tools, support for three package registries, cross-platform support, open sourced on GitHub, published on npm.

How to Use It

Step 1 — Run the detection script:

Windows:

powershell -ExecutionPolicy Bypass -File detect.ps1

Mac/Linux:

bash detect.sh

Step 2 — Install the MCP server:

cd mcp-server
npm install

Step 3 — Connect to Claude Code:

claude mcp add preflight-mcp -- node "/path/to/preflight/mcp-server/index.js"

Or install directly from npm:

npx @malikasana/preflight-mcp

That's it. Claude Code now has accurate knowledge of your machine.

Links

If you use Claude Code and you're tired of watching it guess your setup wrong, give preflight a try. And if you maintain a developer tool, consider shipping a preflight.json — it takes five minutes and it helps every AI that ever touches your users' machines.

DEV Community