@jaymin99/preflight-mcp

MCP server that puts Preflight — an AI risk-intelligence layer for your project — inside your coding agent (Claude Code, Cursor, …). It exposes read tools for live project risk context and write tools for recording risk work.

Live on npm: @jaymin99/preflight-mcp. Install via the Quick start below — no clone or build needed. (Package is under the author's personal @jaymin99 scope; the @preflight-ai org scope belongs to a separate account.)

Quick start

1. Get an API key

In the Preflight app: Project → Settings → API Keys → Connect MCP. The key encodes org + project — nothing else to configure. It looks like pfk_….

2. Add the server to your agent

Claude Code — .mcp.json in your project root (or ~/.claude/settings.json):

{
  "mcpServers": {
    "preflight": {
      "command": "npx",
      "args": ["-y", "-p", "@jaymin99/preflight-mcp", "preflight-mcp"],
      "env": {
        "PREFLIGHT_API_KEY": "pfk_your_key_here"
      }
    }
  }
}

Cursor — same object under mcpServers.preflight in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). The app's Settings → MCP panel has a one-click Add to Cursor button and a copy-paste block with your key pre-filled.

Reload the agent. npx fetches the package on first run and caches it.

args is -p @jaymin99/preflight-mcp preflight-mcp (not a bare npx @jaymin99/preflight-mcp) because the package ships two bins — preflight (the CLI) and preflight-mcp (the server). -p <pkg> <bin> names the one to run explicitly.

3. Smoke-test from a terminal (optional)

PREFLIGHT_API_KEY=pfk_your_key npx -y -p @jaymin99/preflight-mcp preflight-mcp

Starts the server on stdio and waits — no crash means the key resolved. Ctrl-C to exit.

How it behaves

The server ships a standing proactive-use policy to the client at connect time (src/instructions.ts), so the agent reaches for Preflight without being asked. The bounding rule:

• Reads fire freely — context, search, spec, ship-check, release gate, verify-fix run on their own the moment a trigger matches.
• Writes propose-then-confirm — creating a finding, KB entry, or document is shown to you in one line first and only runs on your yes. Nothing mutates silently.

Tools

| Tool | Kind | Fires when | | --- | --- | --- | | preflight_get_project_context | read | starting work / "what's risky here?" | | preflight_get_module_context | read | about to edit code in an area | | preflight_validate_spec | read | handed a spec/ticket before building | | preflight_get_spec | read | implementing a feature that has a spec | | preflight_should_ship | read | diff done, before calling it finished | | preflight_get_release_gate | read | deploy/release mentioned | | preflight_verify_fix | read | just fixed a known finding (have its ID) | | preflight_run_draft_review | read | deeper pre-code risk pass (~45s, private) | | preflight_search_findings | read | asking about known issues / dedup before logging | | preflight_create_finding | write | spotted a real risk in code | | preflight_propose_kb_update → preflight_confirm_kb_update | write | learned a durable project fact | | preflight_create_document | write | wrote a project brief worth keeping |

Environment variables

| Var | Required | Default | Notes | | --- | --- | --- | --- | | PREFLIGHT_API_KEY | yes | — | pfk_… from API Keys. Server throws without it. | | PREFLIGHT_SERVER | no | https://preflight.ai | Backend origin. Set http://localhost:3000 to point at local dev. |

Develop (from this repo)

Only needed if you're changing the server itself — end users don't clone.

cd packages/mcp
npm install
npm run dev       # tsup watch — rebuilds dist/ on save
npm test          # vitest run
npm run build     # production build (cjs + esm + dts)

npm test covers behavior formatting, config resolution, review polling, and that the server instructions stays in sync with the toolset (src/__tests__/instructions.test.ts — it fails if a tool is added or renamed without updating the policy).

Point an agent at your local build

To test uncommitted changes before publishing, wire the client at dist/ instead of npm:

{
  "mcpServers": {
    "preflight": {
      "command": "node",
      "args": ["/abs/path/to/preflight-ai/packages/mcp/dist/index.js"],
      "env": {
        "PREFLIGHT_API_KEY": "pfk_your_key_here",
        "PREFLIGHT_SERVER": "http://localhost:3000"
      }
    }
  }
}

Absolute path required — MCP clients don't resolve dist/index.js relative to your repo. A rebuild is picked up on the client's next reload; no config change. Or npm link the package and use "command": "preflight-mcp" (run npm run build after edits; npm unlink -g @jaymin99/preflight-mcp to undo).

Release a new version

# bump "version" in package.json first — npm rejects republishing the same version
npm run build
npm publish --access public   # "publishConfig.access": "public" is already set

Needs an npm token with read-write on the @jaymin99 scope and 2FA-bypass enabled (--//registry.npmjs.org/:_authToken=…), or an interactive npm login + OTP.