Docs — CLI, MCP Server & AI Agent Tools

Developer documentation for the First Break AI CLI tool, MCP server, and agentic AI tools. Install, configure, and use the @aiedx/firstbreakai npm package to check your environment, track progress, validate exercises, and integrate AI agents with your IDE. First Break AI is completely agentic — powered by AI agents and the Model Context Protocol.

Developer Docs — AI Agent Tools

Everything you need to use First Break AI from the terminal, your AI IDE, or any AI agent. Completely agentic — powered by MCP and AI agent-driven tooling.

First Break AI is completely agentic — every part of the cohort is powered by AI agents. It ships two developer tools:

CLI (@aiedx/firstbreakai) — a terminal tool with built-in AI agent capabilities: check your environment, scaffold a blog, track cohort progress, validate exercises, and ask the AI assistant.
MCP server — the same CLI doubles as a local Model Context Protocol server for Cursor, Claude Desktop, Claude Code, and other AI IDEs. Your AI agent can call cohort tools directly.

Both are part of the same npm package. Install once, use everywhere. The cohort teaches agentic AI by having you use the same AI agent tools you learn about.

Get started

Prerequisites

Node.js 18 or later (check with node --version)
A terminal (macOS Terminal, iTerm, Windows Terminal with WSL, or any Linux terminal)

Install

Install globally so you can run firstbreakai from anywhere:

npm install -g @aiedx/firstbreakai

Or run any command without installing:

npx @aiedx/firstbreakai doctor

Verify

firstbreakai doctor

You should see a checklist of tools (Git, Python, Quarto, HuggingFace CLI, Node.js, Cursor/VS Code) with a pass/fail status for each.

CLI reference

`firstbreakai doctor`

Checks your development environment for every tool the cohort needs.

firstbreakai doctor

Output:

  First Break AI — Environment Check

  ✓ Git v2.41.0
  ✓ Python v3.11.1
  ✓ Quarto v1.8.24
  ✓ HuggingFace CLI v0.28.1
  ✓ Node.js v22.2.0
  ✓ Cursor detected

  All checks passed — you're ready for the cohort!

Each failing check includes an install link.

`firstbreakai status`

Shows your cohort progress — which steps are complete, which are pending.

firstbreakai status

Output:

  First Break AI — Your Progress

  ✓ Step 0: Join Discord & create accounts (5/15/2026)
  ✓ Step 1: First use of AI for coding (5/20/2026)
  ○ Step 2: Run a model locally
      · HuggingFace Beyond Upload
      · Qwen3 Fundamentals
  ○ Step 3: Inference deep dive (coming soon)
  ...

  2/7 steps completed

Progress is stored locally in ~/.firstbreakai.json.

`firstbreakai done <step>`

Marks a step as complete.

firstbreakai done 1

  ✓ Step 1: First use of AI for coding — marked complete!
  Next up: Step 2 — Run a model locally

`firstbreakai init`

Scaffolds a new Quarto blog in the current directory — the starting point for Step 1.

mkdir my-ai-blog && cd my-ai-blog
firstbreakai init

Creates _quarto.yml, index.qmd, and first-post.qmd. Then:

quarto preview        # preview locally
git init && git add . && git commit -m "Initial blog"

Full guide: Lesson 0 — Welcome

`firstbreakai open <page>`

Opens a cohort page in your default browser.

firstbreakai open roadmap
firstbreakai open discord
firstbreakai open lessons

Available pages: home, roadmap, checklist, lessons, setup, blog, discord, repo, office

`firstbreakai next`

Opens the next incomplete step in your browser, based on your local progress.

firstbreakai next

`firstbreakai ask "<question>"`

Sends your question to the FBA AI assistant and prints the answer in your terminal.

firstbreakai ask "How do I download a model from HuggingFace?"
firstbreakai ask "What is GGUF?"

This calls the remote FBA MCP server — requires an internet connection.

`firstbreakai validate <step>`

Runs local, deterministic checks for a cohort step. No LLM, no network required — just file and tool presence checks.

cd ~/my-ai-blog
firstbreakai validate 1

Step 1 checks:

_quarto.yml exists and has type: website
At least one .qmd file exists
Git repo initialized with a GitHub remote
At least one commit

Step 2 checks:

run.c or run binary exists and is executable
config.json (model config) exists
Tokenizer file exists (tokenizer.json or tokenizer.model)
Model weights file exists (.bin or .safetensors)

If you’re logged in, results are also saved to your profile on the FBA server.

`firstbreakai login`

Authenticates via Discord OAuth. Opens your browser, you approve, and a token is saved locally.

firstbreakai login

Login is optional — all local commands work without it. Login enables saving validation results to your server-side profile.

MCP server — AI agent integration

The same @aiedx/firstbreakai package doubles as a local MCP server. This lets AI agents in Cursor, Claude Desktop, Claude Code, or any MCP-capable tool call cohort commands directly — making First Break AI one of the first fully agentic learning platforms.

Setup for Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "firstbreakai": {
      "command": "npx",
      "args": ["@aiedx/firstbreakai", "mcp"]
    }
  }
}

Setup for Claude Desktop

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "firstbreakai": {
      "command": "npx",
      "args": ["@aiedx/firstbreakai", "mcp"]
    }
  }
}

Setup for Claude Code

claude mcp add firstbreakai -- npx @aiedx/firstbreakai mcp

Or add to .mcp.json:

{
  "mcpServers": {
    "firstbreakai": {
      "command": "npx",
      "args": ["@aiedx/firstbreakai", "mcp"]
    }
  }
}

MCP tools reference

Once configured, your AI assistant can call these tools:

Tool	Description	Example prompt
`cohort_doctor`	Check dev environment	“Check if I have all the tools for First Break AI”
`cohort_status`	Show progress	“What’s my cohort progress?”
`cohort_done`	Mark step complete	“Mark step 1 as done”
`cohort_validate`	Run validation checks	“Validate my Step 1 work”
`cohort_open`	Open a cohort page	“Open the First Break AI roadmap”
`cohort_next`	Open next step	“What should I work on next?”
`cohort_ask`	Ask the AI assistant	“Ask FBA how GGUF quantization works”

Local MCP vs remote MCP — two AI agent backends

First Break AI has two MCP servers (AI agent backends):

	Local MCP (this package)	Remote MCP (FBA server)
Transport	stdio (runs on your machine)	Streamable HTTP
Install	`npm install -g @aiedx/firstbreakai`	Paste URL in your AI tool
URL	N/A (local process)	`https://fba-mcp.throbbing-thunder-4d33.workers.dev/mcp`
Tools	`cohort_doctor`, `cohort_status`, `cohort_done`, `cohort_validate`, `cohort_open`, `cohort_next`, `cohort_ask`	`ask`, `find`, `do`, `validate`, `next`
Runs offline	Yes (except `cohort_ask`)	No
Use case	Personal dev workflow	Cohort-wide Q&A, enrollment, server-side validation

You can use both — they complement each other. The local MCP agent checks your files and environment; the remote MCP agent answers questions from the cohort knowledge base. Together they make First Break AI a completely agentic learning experience.

Configuration

Progress file

All local state is stored in ~/.firstbreakai.json:

{
  "version": 1,
  "learner_id": null,
  "access_token": null,
  "steps": {
    "0": { "done": true, "at": "2026-05-15T10:00:00Z" },
    "1": { "done": true, "at": "2026-05-20T14:30:00Z" }
  }
}

learner_id and access_token are set after firstbreakai login
steps tracks which steps you’ve completed locally
Delete this file to reset all progress

Environment variables

Variable	Default	Description
`TERM_PROGRAM`	(auto)	Used to detect Cursor / VS Code in `doctor`

No other environment variables are required.

Package details

Field	Value
Package	`@aiedx/firstbreakai`
Version	0.1.0
License	MIT
Node.js	>= 18
Repository	github.com/thefirehacker/firstbreakai
Homepage	cohort.bubblnet.com
Author	First Break AI

Dependencies

The CLI has only two runtime dependencies:

chalk — terminal colors
open — cross-platform browser opener

Everything else uses Node.js built-in modules (fs, path, http, child_process).

Troubleshooting

firstbreakai: command not found — Make sure you installed globally: npm install -g @aiedx/firstbreakai. Or use npx @aiedx/firstbreakai <command>.

doctor says HuggingFace CLI not found — Install it: pip install huggingface_hub[cli]

validate fails but I’ve done the step — Make sure you run validate from the correct directory (your blog folder for Step 1, your model folder for Step 2).

ask returns a connection error — The ask command needs internet access to reach the FBA server. Check your connection.

MCP server not appearing in Cursor — Make sure the mcp.json config is valid JSON. Restart Cursor after adding the config. Check with npx @aiedx/firstbreakai mcp in a terminal to verify the package loads.

What’s next

Roadmap — see all six steps of the cohort
Checklist — accounts and tools to set up
Lessons — start learning
Discord — join the community