unicorn-mcp

Model Context Protocol (MCP) server for the Fast Unicorn template (Next.js App Router, tRPC, Prisma, NextAuth, Stripe, next-intl, etc.).

The package is published on npm as unicorn-mcp. You do not add it as a dependency of the Next.js project: you register it in Cursor (or another MCP-capable IDE) so the client runs it with npx. Communication is over stdio (JSON-RPC per MCP).

Connect from Cursor / your IDE

1. Open MCP settings (for example Settings → MCP or the mcp.json your Cursor uses).
2. Add unicorn-mcp inside the mcpServers object. The key ("unicorn-mcp") is only a display name; you can change it.

Example: mcpServers (Windows)

Using cmd often makes npx resolve correctly (same pattern as other MCPs published on npm):

{
  "mcpServers": {
    "unicorn-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "unicorn-mcp@latest"
      ],
      "env": {
        "FAST_UNICORN_ROOT": "C:/absolute/path/to/your/fast-unicorn-project"
      }
    }
  }
}

Example: mcpServers (macOS / Linux)

{
  "mcpServers": {
    "unicorn-mcp": {
      "command": "npx",
      "args": ["-y", "unicorn-mcp@latest"],
      "env": {
        "FAST_UNICORN_ROOT": "/absolute/path/to/your/fast-unicorn-project"
      }
    }
  }
}

Important: set FAST_UNICORN_ROOT (or TEMPLATE_ROOT) to the absolute path to your Fast Unicorn app root on disk. Otherwise the server falls back to relative paths that rarely match your repo from an IDE.

Notes

• Node.js ≥ 18 (for npx).
• Optional web search: BRAVE_API_KEY in the same env block if you want Brave Search; otherwise DuckDuckGo is used (rate limits may apply; retries are already built into the server).

How it works (v3)

1. Startup: the IDE runs npx -y unicorn-mcp@latest, which starts the Node process and an McpServer over StdioServerTransport.
2. Registration: the server exposes 4 tools (guide, ui, explore, research), Markdown resources (fast-unicorn://…), and predefined prompts.
3. Your template on disk: tools that read the repo resolve the root with FAST_UNICORN_ROOT / TEMPLATE_ROOT (recommended) or an unreliable relative fallback without those variables.
4. Cache: some context (file tree, guides by area, research) is kept in memory for a few minutes for speed (src/lib/cache.ts).

The four tools

| Tool | Purpose | |------|---------| | guide | Fast Unicorn knowledge base: returns internal docs, typical paths, patterns, and step-by-step guides. Use topic = area (auth, payments, i18n, email, database, trpc, server-api, deployment, general) or a specific guide id (e.g. new-trpc-router). Without topic, lists everything available. | | ui | UI guide in a shadcn-like style: themes, forms, composition, icons, choosing components. Optional topic: styling, theming, forms, composition, icons, components. Without topic, returns all sections. | | explore | Explores the project at FAST_UNICORN_ROOT: without query, directory tree; with query, text search in files. Useful params: path, depth, scope (src, config, messages, prisma, all). | | research | Product/market research. type: market, competitors, roadmap (use web search + analysis template) or stack (local suggestions without web, from text requirements). |

MCP resources

Markdown under context/ is published as fast-unicorn://<slug> URIs (for example fast-unicorn://server-api). They let the assistant cite long documentation without repeating it on every call.

Built-in prompts

| Prompt | Use | |--------|-----| | init_project | Full flow: research → competitors → roadmap → architecture → kickoff document. | | build_feature | Implement a feature following conventions (asks for guide + ui + explore in order). | | debug_context | Debug an issue (area + symptoms). | | generate_prd | PRD with market context via research. |

Example usage (for client guidance)

Typical goal: “I want to add a protected tRPC mutation that saves data with Prisma and shows the result on the dashboard.”

Recommended flow in the IDE chat

1. Architecture and API context
   Ask the assistant to use guide with topic: "server-api" (or "trpc" if you prefer router/client focus).

2. If screens are involved
   Have it call ui with topic: "forms" or topic: "composition" depending on what you are building.

3. Align with existing code
   Use explore with a query (e.g. a router name or protectedProcedure) to see where similar logic already lives.

4. Implement
   The assistant applies template patterns (use* routers, registration in root.ts, protectedProcedure, src/server/services when needed).

Minimal natural-language “what to ask” example

You can copy and adapt this in Cursor (with MCP already connected):

Use the Fast Unicorn MCP in this order:

1. guide with topic payments to see how Stripe and webhooks are set up.
2. explore with query webhook and scope src to locate the handler.
3. Propose only the minimal change to add a new webhook event and update Prisma.

Another example (product only, no repo changes):

Use research with idea “booking app for hair salons in Mexico”, type market, then type roadmap; summarize as a 3-phase plan.

Example parameters (quick reference)

{ "topic": "auth" }

{ "topic": "styling" }

{ "query": "useStripe", "scope": "src" }

{ "idea": "Invoicing SaaS for freelancers, Spain", "type": "competitors" }

{ "path": "src", "depth": 3 }

Environment variables

| Variable | Purpose | |----------|---------| | FAST_UNICORN_ROOT / TEMPLATE_ROOT | Absolute path to the Fast Unicorn project root (recommended with IDE + npx). | | BRAVE_API_KEY | Brave Search for research with web search (optional; without it DuckDuckGo is used). |

Developing this repository

| Command | Description | |---------|-------------| | npm install | Install dependencies. | | npm run dev | Run with tsx watch. | | npm run build | Compile to dist/. | | npm start | Run node dist/index.js (stdio). | | npm run typecheck | Type checking only. |

Code layout

src/
  index.ts                 # Register tools, resources, prompts
  lib/                     # cache, web search, template root resolution
  tools/
    guide.ts               # guide tool
    ui.ts                  # ui tool
    explore.ts             # explore tool
    research.ts            # research tool
    context/               # legacy internal implementations (used by guide)
    research/              # research helpers (legacy / modular)
  resources/
    template_docs.ts       # Markdown resource registration
  prompts/
    index.ts
context/                   # Packaged Markdown (architecture, auth-guide, …)

License

MIT (see package.json).