FAI Quick Start
From zero to running FAI Engine in 5 minutes — install, validate, explore, build.
Prerequisites
Before starting, verify you have the required tools installed:
# Published packages require Node.js 18 or newernode --versionnpm --version
# Required: VS Code with GitHub Copilotcode --version
# Optional: Azure CLI (for deployment steps)az --versionIf any command fails, install the missing tool before continuing. Use an active Node.js LTS release for current security and ecosystem support.
Step 1: Install the MCP Server
The FAI MCP Server connects compatible MCP clients to the FrootAI knowledge base. The published package declares Node.js 18 or newer; install the current release globally when you want one executable shared across workspaces:
# Install the current FAI MCP Server release globallynpm install --global frootai-mcp@latest
# Verify the published version and executablenpm view frootai-mcp versionGet-Command frootai-mcp # PowerShell# command -v frootai-mcp # bash/zshExpected Output
The registry reports a version and your shell resolves the frootai-mcp executable.
Troubleshooting
If you get EACCES permission errors on macOS/Linux, use sudo npx frootai-mcp@latest or fix npm global permissions. On Windows, run the terminal as Administrator.
Step 2: Install the Essentials Plugin
The essentials plugin bundles the most-used agents, instructions, and skills into a single installable package. It sets up your .github/ directory with core primitives:
# Install the fai-essentials pluginnpx frootai install fai-essentials
# What gets created:# .github/agents/fai-architect.agent.md# .github/agents/fai-code-reviewer.agent.md# .github/instructions/typescript-waf.instructions.md# .github/instructions/python-waf.instructions.md# .github/skills/fai-play-initializer/SKILL.md# .github/copilot-instructions.mdExpected Output
✓ Installed fai-essentials (2 agents, 2 instructions, 1 skill)
Troubleshooting
If .github/ already exists, the installer merges non-conflicting files and skips existing ones. To force overwrite, use npx frootai install fai-essentials --force.
Step 3: Validate Primitives
Run the validator to confirm all installed primitives have correct frontmatter, naming conventions, and schema compliance:
# Validate all primitives in the workspacenpm run validate:primitives
# Or run directlynode scripts/validate-primitives.js --verboseExpected Output
Scanning primitives... ✓ 2 agents — all valid ✓ 2 instructions — all valid ✓ 1 skill — all valid ✓ 0 hooks — none found ✓ 0 errors, 0 warnings
Troubleshooting
Common errors: missing description in agent frontmatter (must be 10+ chars), incorrect file naming (must be lowercase-hyphen), skill folder name not matching name field in SKILL.md.
Step 4: Run FAI Engine on a Play
The FAI Engine reads a fai-manifest.json and resolves all referenced primitives, knowledge modules, WAF pillars, and guardrails. Test it against the built-in Enterprise RAG play:
# Load and verify Play 01 — Enterprise RAGnode engine/index.js \ solution-plays/01-enterprise-rag/fai-manifest.json \ --statusExpected Output
FAI Engine v2.x.x Loading: solution-plays/01-enterprise-rag/fai-manifest.json Play: 01-enterprise-rag Version: 1.0.0 Knowledge: R2 (RAG), O4 (Azure AI) WAF: security, reliability, cost-optimization Primitives: 3 agents, 2 instructions, 2 skills Guardrails: groundedness ≥ 0.8, safety ≥ 0.9 Status: ✓ All references resolved
Troubleshooting
If you see “unresolved reference” errors, the referenced primitive file may be missing. Run npm run validate:primitives first to identify gaps.
Step 5: Explore the Marketplace
Browse 77+ plugins, search the knowledge base, and discover solution plays:
# List all available pluginsnpx frootai list
# Search for RAG-related resourcesnpx frootai search "RAG architecture"
# Install a specific pluginnpx frootai install enterprise-rag
# View play detailsnpx frootai play 01 --detailsExpected Output (list)
FAI Marketplace — plugins available enterprise-rag RAG with Azure AI Search + OpenAI smart-chatbot Multi-turn conversational AI document-processor Invoice and form extraction ... Use: npx frootai install <name>
What's Next?
You now have the FAI ecosystem running locally. Here are the recommended next steps:
Follow the End-to-End Workshop (L15) to create a complete solution play from scratch — manifest, primitives, deployment, evaluation.
Read the Primitive Primer (L1) to understand agents, instructions, skills, hooks, and how they wire together.
See the Configuration Guide (L4) to set up openai.json, guardrails.json, and model parameters for your use case.
Open Copilot Chat and ask questions — the MCP tools give Copilot direct access to the FrootAI knowledge base.
Quick Reference
| Command | Purpose |
|---|---|
| npx frootai-mcp@latest | Install/update MCP Server |
| npx frootai install <plugin> | Install a marketplace plugin |
| npm run validate:primitives | Validate all primitives in workspace |
| node engine/index.js <manifest> --status | Load and verify a solution play |
| npx frootai list | Browse marketplace plugins |
| npx frootai search <query> | Search knowledge base |
Project Structure After Setup
After completing all 5 steps, your workspace will have this structure:
your-project/├── .github/│ ├── agents/│ │ ├── fai-architect.agent.md│ │ └── fai-code-reviewer.agent.md│ ├── instructions/│ │ ├── typescript-waf.instructions.md│ │ └── python-waf.instructions.md│ ├── skills/│ │ └── fai-play-initializer/│ │ └── SKILL.md│ └── copilot-instructions.md├── config/│ ├── openai.json│ └── guardrails.json└── solution-plays/ └── 01-enterprise-rag/ └── fai-manifest.jsonThe .github/ directory holds all primitives recognized by GitHub Copilot. The config/ directory holds TuneKit runtime configuration. Solution plays reference both through the manifest.
Common Pitfalls
The FAI Engine requires Node.js 18+. If you see syntax errors on startup, check node --version. Recommend v22 LTS.
Primitives must live under .github/ for Copilot to detect them. If agents aren't appearing in chat, check the directory path.
Agent description must be 10+ characters. File names must be lowercase-hyphen. WAF values must be from the 6-pillar set.
Restart VS Code after installing the MCP server. Check the Output panel → GitHub Copilot for connection logs. Ensure no firewall blocks localhost stdio.