# FrontAgent > Frontend AI coding agent platform with CLI, VS Code extension, desktop app, MCP server, RAG planning, Skills, SDD guardrails, browser automation, and LoRA planner models | 面向前端工程的 AI Agent 平台，支持 CLI、VS Code 插件、桌面端、MCP 服务、RAG、Skills、SDD、浏览器自动化与 LoRA 规划模型 - **Type:** MCP server - **Install:** `agentstack add mcp-ceilf6-frontagent` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ceilf6](https://agentstack.voostack.com/s/ceilf6) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ceilf6](https://github.com/ceilf6) - **Source:** https://github.com/ceilf6/FrontAgent - **Website:** https://marketplace.visualstudio.com/items?itemName=ceilf6.frontagent ## Install ```sh agentstack add mcp-ceilf6-frontagent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # FrontAgent [](https://www.npmjs.com/package/frontagent) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) > Enterprise-grade frontend AI coding agent and MCP-powered automation system - constrained by Specification Driven Development (SDD) for controlled planning, code generation, browser-aware execution, and repository workflows [中文文档](docs/README-CN.md) | [Quick Start](docs/QUICKSTART.md) | [Architecture](docs/architecture.md) | [Design Doc](docs/design.md) FrontAgent is an open-source AI coding agent for frontend engineering. It helps teams build, modify, validate, and ship web applications through an agentic CLI, VS Code extension, desktop app, local MCP server, RAG planning, browser-aware automation, and SDD guardrails. > **Distilled Planner Models**: FrontAgent's Planner stage has been distilled into Hugging Face planner assets collected under [FrontAgent: Frontend Engineering Agent](https://hf.co/collections/ceilf6/frontagent-frontend-engineering-agent). Load the published adapters on their supported Qwen Coder base models to generate frontend execution plans directly, without calling large LLM APIs. The training workflow, prompts, evaluation scripts, and Hugging Face release metadata live in [models/frontagent-planner](models/frontagent-planner). Use FrontAgent when you need a frontend AI agent that can: - Generate and refactor React, TypeScript, Vite, Tailwind CSS, and modern web UI code from structured execution plans. - Run as an AI agent CLI, VS Code AI extension, desktop agent app, or stdio MCP server for Claude Desktop, Cursor, Codex, and other MCP hosts. - Combine repository-aware RAG, Filesense navigation, facts memory, and module dependency tracking to reduce path hallucinations. - Execute browser-aware validation, page inspection, shell commands, and git/gh repository workflows behind explicit safety controls. - Enforce Specification Driven Development (SDD), minimal patches, self-healing error recovery, and quality gates for production frontend teams. - Use distilled Qwen Coder planner models from Hugging Face for local or lower-cost frontend execution planning. - ✅ **Two-Stage Architecture** - Separate planning and execution to avoid JSON parsing errors and enable dynamic code generation - ✅ **Phase-Based Execution** - Steps grouped by phases with error recovery within each phase - ✅ **Self-Healing** - Tool Error Feedback Loop automatically analyzes errors and generates fix steps - ✅ **Facts Memory** - Structured facts-based context system for precise project state tracking - ✅ **Module Dependency Tracking** - Automatic import/export parsing to detect path hallucinations - ✅ **Hallucination Prevention** - Multi-layer hallucination detection and interception - ✅ **SDD Constraints** - Specification Driven Development as hard constraints for agent behavior - ✅ **MCP Protocol** - Controlled tool invocation via Model Context Protocol - ✅ **Minimal Changes** - Patch-based code modifications with rollback support - ✅ **Web Awareness** - Understand page structure through browser MCP - ✅ **Shell Integration** - Terminal command execution (requires user approval) - ✅ **Pre-Planning Scan** - Scan project structure before planning to generate accurate file paths - ✅ **Auto Port Detection** - Automatically detect dev server ports from config files - ✅ **Remote Hybrid RAG** - Full-repository indexing with submodule exclusion, combining BM25 keyword search and embedding-based semantic search - ✅ **Filesense Navigation** - Budgeted current-repository navigation with generated schemas and notes - ✅ **LangGraph Engine (Optional)** - Switchable graph-based execution engine with optional checkpoints - ✅ **Planner Skills Layer** - Reusable planning skills for task decomposition and phase injection - ✅ **Distilled Planner Assets** - Repository-native training, evaluation, and release assets for the Hugging Face Planner model collection - ✅ **Skill Lab** - Benchmark, improve, and promote content skills with local eval suites - ✅ **VS Code Sidebar** - Marketplace extension with task runs, SDD helpers, secure settings, and run logs - ✅ **OSS Harness** - Local contract, quality, GitNexus, and workflow gates for maintainer-friendly changes - ✅ **Repository Management Phase** - Auto git/gh workflow after acceptance (commit, push, PR) - ✅ **Cross-Session Memory** - Four-phase memory system (preload, runtime recall, post-task persistence, structured storage) that persists project facts, error resolutions, and dependency state across runs ## Current Release Snapshot The repository is currently aligned on `frontagent@2.1.1` for both the npm CLI package and the VS Code extension. - Runtime requirements: Node.js `>=20.0.0`; VS Code extension engine `^1.120.0`. - Build output: `pnpm build` builds the monorepo, bundles the CLI, syncs the VS Code version, and packages `apps/vscode/frontagent-2.1.1.vsix`. - Quality gates: `pnpm quality:predev`, `pnpm quality:precommit`, `pnpm quality:ci`, and `pnpm quality:local` combine contract checks, linting, typechecking, tests, workflow tests, and build verification. - v2.1.1 focus: smaller agent/executor/context/Filesense/memory/runtime/webview modules, hardened VS Code webview nonce generation, restored GitNexus contract checks, and expanded focused tests. ## Three Ways to Use FrontAgent FrontAgent supports terminal, VS Code, and standalone desktop workflows: - **CLI**: use `fa init`, `fa run`, RAG commands, Skill Lab, and automation-friendly workflows directly from your terminal. - **VS Code Extension**: use the FrontAgent sidebar task console to run tasks, attach the current file or selection, provide a browser URL, review phase/step progress, approve sensitive actions, initialize/validate SDD, and open run logs from inside VS Code. - **Desktop App**: a standalone Electron GUI (`apps/desktop`) that reuses the same Node runtime spine — a Task Console for launching tasks, watching live phase/step telemetry, and approving sensitive actions, plus a Settings panel for the LLM provider/model. Install the VS Code extension from the Marketplace by searching for `FrontAgent` or the extension id `ceilf6.frontagent`. ### Desktop App The desktop client is a sandboxed Electron window wired to the real runtime (`window.frontagent` → IPC → `runFrontAgentTask`); it persists settings under your OS user-data directory and degrades gracefully if the runtime is unavailable. - **Download**: grab the unsigned per-platform archive `frontagent-desktop-${version}-${os}-${arch}.zip` from the [GitHub Releases](https://github.com/FrontAgent/FrontAgent/releases) page (published automatically for each `v*` tag), unzip, and launch the `frontagent` executable. The LLM API key is read from the environment (`PROVIDER_API_KEY` / `API_KEY`); set provider/model/base URL in the in-app Settings panel. - **Build locally**: `pnpm --filter @frontagent/desktop package` produces an unpacked app under `apps/desktop/release/`, and `pnpm --filter @frontagent/desktop dev` runs it against the Vite dev server. The `release` script (`pnpm --filter @frontagent/desktop run release`) produces the distributable zip. > Desktop archives are currently unsigned; code signing, notarization, and native installers (dmg/nsis/AppImage) are planned follow-ups. ## CLI Quick Start ```bash # 1. Install globally via npm npm install -g frontagent # or using pnpm pnpm add -g frontagent # or using yarn yarn global add frontagent # 2. Configure LLM (supports OpenAI and Anthropic) # OpenAI config export PROVIDER="openai" export BASE_URL="https://api.openai.com/v1" export MODEL="gpt-4" export API_KEY="sk-..." # Or Anthropic config export PROVIDER="anthropic" export BASE_URL="https://api.anthropic.com" export MODEL="claude-sonnet-4-20250514" export API_KEY="sk-ant-..." # 3. Navigate to your project directory and initialize SDD cd your-project fa init # 4. Let AI help you complete tasks fa run "Create a user login page" fa run "Optimize homepage loading performance" fa run "Add dark mode support" # Use LangGraph engine + checkpoint (optional) fa run "Add route guards and open a PR" --engine langgraph --langgraph-checkpoint ``` ## MCP Server FrontAgent can run as a local stdio MCP Server for MCP hosts such as Claude Desktop, Cursor, Codex, and other clients that can launch a command-based MCP server. MCP mode exposes FrontAgent's upper-level agent capabilities only. It does not expose raw internal tools such as `read_file`, `apply_patch`, `run_command`, browser tools, or `rag_query` directly to the external host. ### Start the Server ```bash # Use the installed CLI fa mcp serve # Or run from a source checkout after pnpm build node /absolute/path/to/FrontAgent-app/apps/cli/dist/index.js \ mcp serve ``` By default, FrontAgent resolves the project root from the MCP host's workspace roots when the host exposes exactly one file root. If host roots are unavailable, it falls back to the MCP server process current working directory. Use `--project-root` only when you want to pin the server to a specific project, or when the host exposes multiple workspace roots and FrontAgent cannot choose safely: ```bash fa mcp serve --project-root /absolute/path/to/your-project ``` One MCP server process is bound to one resolved project root. Useful server options: ```bash fa mcp serve \ --engine native \ --security-mode balanced \ --rag-repo https://github.com/ceilf6/Lab.git \ --rag-branch main \ --filesense-enabled true \ --log-file .frontagent/runs/mcp-server.log ``` ### Host Configuration Most MCP hosts use the same `mcpServers` shape. Start with the simple config: ```json { "mcpServers": { "frontagent": { "command": "fa", "args": ["mcp", "serve"] } } } ``` If your host UI has separate fields, use: - Command: `fa` - Args: `mcp`, `serve` Do not put `fa mcp serve` into the command field as one string. If the host reports `command "fa" not found` or `env: node: No such file or directory`, the GUI host probably does not inherit your terminal shell `PATH`. Then use absolute paths: ```bash which node which fa ``` ```json { "mcpServers": { "frontagent": { "command": "/opt/homebrew/bin/node", "args": ["/opt/homebrew/bin/fa", "mcp", "serve"] } } } ``` If you are using a source checkout instead of a globally linked package, point `node` at the built CLI file after `pnpm build`: ```json { "mcpServers": { "frontagent": { "command": "/opt/homebrew/bin/node", "args": [ "/absolute/path/to/FrontAgent-app/apps/cli/dist/index.js", "mcp", "serve" ] } } } ``` For direct LLM fallback, pass environment variables through the host config: ```json { "mcpServers": { "frontagent": { "command": "fa", "args": ["mcp", "serve"], "env": { "PROVIDER": "openai", "BASE_URL": "https://api.openai.com/v1", "MODEL": "gpt-4", "API_KEY": "sk-..." } } } } ``` Examples of where to put the config: - Claude Desktop: add the server under `mcpServers` in `claude_desktop_config.json`. - Cursor: add the server under `mcpServers` in your Cursor MCP config, for example `.cursor/mcp.json`. - Codex or other MCP hosts: use the same command, args, and env values in the host's MCP server configuration surface. ### Exposed MCP Tools FrontAgent exposes six MCP tools: - `frontagent_status`: returns project root, SDD status, visible skills, LLM backend status, RAG status, and run-log directory. - `frontagent_run_task`: runs a full FrontAgent task. Inputs include `task`, `type`, `files`, `url`, `sddPath`, and `securityMode`. - `frontagent_plan_task`: generates a FrontAgent execution plan without executing tools or writing files. - `frontagent_validate_sdd`: validates the project SDD file. - `frontagent_list_skills`: lists visible content skills. - `frontagent_init_sdd`: creates an SDD template. Existing files are not overwritten unless `force=true`. `frontagent_run_task` returns structured JSON text with: ```json { "success": true, "taskId": "task_...", "output": "...", "error": null, "duration": 1234, "runLogPath": "/absolute/path/.frontagent/runs/...", "executedStepsSummary": [], "securityDecisions": [] } ``` ### LLM Backend Behavior MCP mode uses `auto` LLM backend selection: 1. If the host supports MCP Sampling, FrontAgent asks the host model through `sampling/createMessage`. 2. If Sampling is unsupported or unavailable, FrontAgent falls back to direct LLM configuration. Direct fallback uses the same environment variables and flags as `fa run`: ```bash export PROVIDER="openai" export BASE_URL="https://api.openai.com/v1" export MODEL="gpt-4" export API_KEY="sk-..." ``` Read-only tools such as `frontagent_status`, `frontagent_list_skills`, `frontagent_validate_sdd`, and `frontagent_init_sdd` do not require LLM configuration. `frontagent_run_task` and `frontagent_plan_task` require either host Sampling support or a valid direct LLM fallback. ### Security Model MCP mode keeps FrontAgent's internal safety boundary: - External MCP hosts cannot directly call internal file, shell, browser, or RAG tools. - Internal file writes, shell commands, browser actions, and other side effects still go through `SecurityManager`. - The default security mode is `balanced`. - Because stdio MCP does not provide FrontAgent's interactive approval UI, any action that requires an `ask` decision fails closed. - `frontagent_init_sdd` only writes SDD files inside the configured project root. ## Remote RAG FrontAgent now supports a full remote repository knowledge base flow for planning and code generation: - It syncs the remote repository into `.frontagent/rag-cache/repo` - It indexes the full repository by chunk, and automatically excludes Git submodule paths - It runs BM25 keyword retrieval and embedding-based semantic retrieval in parallel - It applies metadata filters to each candidate list, then fuses the ranked results - Built indexes and embedding vectors are cached under `.frontagent/rag-cache` Default knowledge source: - Repository: `https://github.com/ceilf6/Lab.git` - Source mode: `git` by default; when `FRONTAGENT_OPENVIKING_ENDPOINT` is configured FrontAgent defaults to `composite` (`OpenViking` first, Git RAG fallback) CLI options: ```bash fa run "Explain React setState behavior" \ --provider openai \ --base-url https://yunwu.ai/v1 \ --api-key YOUR_TOKEN \ --rag-repo https://github.com/ceilf6/Lab.git \ --rag-branch main \ --rag-keyword-candidates 40 \ --rag-semantic-candidates 40 \ --rag-keyword-weight 0.45 \ --rag-semantic-weight 0.55 # When provider=openai, RAG embeddings inherit the same base-url/api-key by default. # Override them only if your embedding endpoint is different. fa run "Explain React setState behavior" \ --provider openai \ --base-url https://yunwu.ai/v1 \ --api-key YOUR_TOKEN \ --rag-embedding-model text-embedding-3-small \ --rag-embedding-batch-size 32 \ --rag-embedding-timeout-ms 30000 # Use Weaviate as the semantic vector store (BM25 stays local) fa run "Explain React setState behavior" \ --provider openai \ --base-url https://yunwu.ai/v1 \ --api-key YOUR_TOKEN \ --rag-embedding-model text-embedding-3-small \ --rag-vector-store-provider weaviate \ --rag-weaviate-url http://127.0.0.1:8080 \ --rag-weaviate-collection-prefix FrontAgentRagChunk \ --rag-weaviate-batch-size 64 \ --rag-weaviate-timeout-ms 30000 # Use OpenViking Wiki as the primary knowledge provider, with Git RAG fallback fa run "Where is FrontAgent RAG implemented?" \ --rag-source composite \ --open-viking-endpoint https://openviking.example.com/query \ --open-viking-corpus wiki \ --open-viking-namespace docs/openviking \ --open-viking-l1-entry docs/openviking/frontagent-l1.md # Require OpenViking only and disable Git fallback fa run "Where is FrontAgent RAG implemented?" \ --rag-source openviking \ … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ceilf6](https://github.com/ceilf6) - **Source:** [ceilf6/FrontAgent](https://github.com/ceilf6/FrontAgent) - **License:** MIT - **Homepage:** https://marketplace.visualstudio.com/items?itemName=ceilf6.frontagent Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ceilf6-frontagent - Seller: https://agentstack.voostack.com/s/ceilf6 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.