nexus-toolkit 2.1.0

Hybrid search, retrieval, and Figma Make boilerplate generation MCP server

Nexus MCP Server

The Hybrid Search, Retrieval & Code Generation Engine for AI Agents.

Nexus is a local Model Context Protocol (MCP) server that combines semantic web search, documentation-optimised reading, and a Design → Production Code pipeline powered by golden path conventions. Feed it a Figma Make export, a text description, or an existing codebase — get back clean, runnable production code in your chosen stack.

---

Features

1. Hybrid Search (nexus_search)

• General mode — broad web search for news, articles, and general information
• Docs mode — filters to technical domains (readthedocs, github, stackoverflow, official docs)

2. Intelligent Reading (nexus_read)

• General focus — cleans articles, strips ads and navigation
• Code focus — retains only headers, code blocks, and tables; perfect for API docs
• Auto-detect — switches to code focus automatically on technical sites like GitHub

3. Design-to-Code Pipeline (7 tools)

Three ways to start, one shared pipeline to finish:

flowchart LR
    A1["ingest_figma_zip\n(Figma Make export)"]
    A2["ingest_from_prompt\n(text description)"]
    A3["ingest_from_codebase\n(existing project)"]

    B["remap_to_golden_path\n(seed boilerplate + queue)"]
    C["Golden Path Agent\n(LLM transforms each component)"]
    D["validate_output\n(static analysis)"]
    E["package_output\n(ZIP to disk)"]

    A1 --> B
    A2 --> B
    A3 --> B
    B --> C --> D --> E

Golden Path	Stack
nextjs-fullstack	Next.js 16.1, React 19.2, Tailwind v4, tRPC v11, Prisma v7, NextAuth v5, Zustand v5
nextjs-static	Next.js 16.1, React 19.2, Tailwind v4, static export
t3-stack	T3 conventions (src/ layout), tRPC + Prisma + NextAuth + Zustand, Tailwind v4
vite-spa	Vite 6, React 19.2, Tailwind v4, React Router v7, TanStack Query
monorepo	Turborepo, apps/web + apps/marketing, shared packages/ui + packages/db
full-stack-rn	Turborepo, apps/web (Next.js 16 + Supabase API) + apps/mobile (Expo 54 bare + NativeWind), shared packages
full-stack-flutter	Turborepo, apps/web (Next.js 16 + Supabase API) + apps/mobile (Flutter 3.32 + Riverpod + go_router), shared packages

4. Privacy & Cost

• No API keys required — uses DuckDuckGo for search and standard HTTP for reading
• Runs locally — your data stays on your machine until sent to the LLM

---

Installation

Prerequisites: Python 3.10+

Option 1: pip (simplest)

pip install git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion

Option 2: uvx (faster, isolated)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion nexus-mcp

Option 3: Development install

git clone https://github.com/rcdelacruz/nexus-mcp.git
cd nexus-mcp
uv sync          # or: python3 -m venv .venv && source .venv/bin/activate && pip install -e .

---

Configuration

Claude Code (CLI)

# uvx (recommended)
claude mcp add nexus -- uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion nexus-mcp

# local dev
claude mcp add nexus --scope project -- \
  $(pwd)/.venv/bin/python $(pwd)/nexus_server.py

claude mcp list   # verify: nexus - ✓ Connected

n8n (HTTP / streamable-http)

Run the server in HTTP mode so n8n can reach it over the network:

# Development (dev install)
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
  .venv/bin/python nexus_server.py

# uvx
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
  uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion nexus-mcp

In n8n, set the MCP Client node Endpoint URL to:

http://<server-ip>:3900/mcp

Note: The server binds to 0.0.0.0 so it is reachable from n8n on any interface. stateless_http is enabled, so tool calls work without a prior MCP initialize handshake (required for n8n SSH nodes that call the server directly via curl/HTTP).

---

Claude Desktop / Cursor

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion", "nexus-mcp"]
    }
  }
}

---

Usage

CLI (nexus)

The nexus CLI lets you run the full Design-to-Code pipeline from the terminal — no MCP client required. It ships alongside the MCP server in the same package.

Prerequisites

• nexus-mcp installed (any method from Installation)
• claude CLI installed and authenticated (required for the transform step)

Claude CLI lookup order

The nexus transform command finds claude in this order:

1. --claude-path <path> flag
2. CLAUDE_PATH environment variable
3. System PATH (which claude)
4. ~/.local/bin/claude (standard Claude Code install on macOS/Linux)

Commands

Command	Description
nexus ingest zip <zip>	Ingest a Figma ZIP export
nexus ingest prompt "<desc>"	Ingest from a text description
nexus ingest codebase <dir>	Ingest an existing project for migration
nexus remap <project>	Seed boilerplate + write transformation queue
nexus transform <project>	Process queue files with Claude (LLM step)
nexus validate <project>	Validate generated files for production readiness
nexus package <project>	Package output into a ZIP
nexus run zip <zip>	Full pipeline from a Figma ZIP (all steps)
nexus run prompt "<desc>"	Full pipeline from a text description
nexus run codebase <dir>	Full pipeline from an existing codebase

All commands read/write to /tmp/nexus-<project-name>/ automatically.

Step-by-step workflow

# 1. Ingest
nexus ingest zip ~/Downloads/mydesign.zip \
  --golden-path nextjs-fullstack \
  --project-name myapp

# 2. Seed boilerplate + generate queue
nexus remap myapp --prompt "add dark mode support"

# 3. LLM transformation (calls claude CLI automatically)
nexus transform myapp

# 4. Validate
nexus validate myapp

# 5. Package
nexus package myapp --output-dir ~/Desktop/

One-liner (full pipeline)

nexus run zip ~/Downloads/mydesign.zip \
  --golden-path nextjs-fullstack \
  --project-name myapp \
  --output-dir ~/Desktop/

nexus run prompt "A SaaS dashboard with sidebar nav, stats cards, and a data table" \
  --golden-path nextjs-fullstack \
  --project-name my-saas

nexus run codebase ~/Projects/old-react-app \
  --golden-path nextjs-fullstack \
  --project-name migrated-app

Note: nexus run is fully automated — ingest → remap → claude transform → validate → package with no manual steps. Requires claude CLI installed and authenticated.

Options reference

nexus transform / nexus run *

Flag	Default	Description
--model, -m	claude-sonnet-4-6	Claude model to use for transformation
--claude-path	(auto-detect)	Explicit path to the claude CLI

nexus remap

Flag	Description
--prompt	Extra instructions passed to the LLM agent (e.g. "use Inter font")

nexus package / nexus run *

Flag	Description
--output-dir, -o	Copy the final ZIP to this directory (default: stays in /tmp/)

Environment variables

Variable	Description
CLAUDE_PATH	Path to the claude CLI binary (overridden by --claude-path)

---

MCP (Claude Code / n8n)

The MCP server is unchanged — all 7 pipeline tools remain available as before. The CLI and MCP server share the same codebase; both entry points call the same underlying functions.

---

Search & Read

How do I use asyncio.gather in Python? Check the docs.

Nexus calls nexus_search(mode="docs") then nexus_read(focus="code") — you get only the function signature and examples, not the surrounding prose.

---

Design-to-Code Pipeline

Starting point A — Figma Make export

If you have a Figma Make export unzipped locally:

I have a Figma Make export at /Users/me/Downloads/figma-export.
Turn it into a Next.js fullstack app called "dashboard-app".

Or provide the ZIP as base64:

base64 -i figma-export.zip | pbcopy   # macOS — copy to clipboard

Here is my Figma Make export as base64: <PASTE>
Project name: dashboard-app, golden path: nextjs-fullstack

Starting point B — Text description (no Figma file needed)

Build a SaaS landing page with a hero section, features grid, pricing table,
testimonials, and footer. Use nextjs-static. Call it "my-landing".

Nexus calls ingest_from_prompt, infers the components from your description, and queues each one for the LLM agent to create from scratch.

For a bare scaffold with no UI:

Scaffold a clean nextjs-fullstack starter called "my-app". No design yet.

Starting point C — Existing project migration

Migrate my existing React app at /Users/me/projects/old-app
to nextjs-fullstack conventions. Call the output "new-app".

Nexus calls ingest_from_codebase, reads your source files, skips config/tooling (golden path boilerplate replaces those), and queues each component for the agent to rewrite to golden path standards while preserving UI and logic.

Finishing the pipeline

In all three cases, Claude chains the pipeline automatically:

1. Ingestion tool produces a manifest
2. remap_to_golden_path seeds boilerplate + queues components for the agent
3. The golden path agent transforms each component
4. validate_output checks for errors (broken imports, missing files, etc.)
5. package_output zips everything up

# The ZIP is saved to disk automatically — Claude will show the zip_path
cp /tmp/nexus-my-app/my-app.zip ~/Desktop/
unzip ~/Desktop/my-app.zip && cd my-app
pnpm install && pnpm dev

---

Tool Reference

Search tools

nexus_search(query, mode?)

Parameter	Type	Default	Description
query	string	required	Search query
mode	string	"general"	"general" or "docs"

nexus_read(url, focus?)

Parameter	Type	Default	Description
url	string	required	URL to fetch
focus	string	"auto"	"general", "code", or "auto"

---

Pipeline tools

ingest_figma_zip(zip_base64?, project_dir?, golden_path, project_name?)

Reads a Figma Make export — either as a base64 ZIP string or a local directory path. Classifies files into components, pages, styles, and assets.

Parameter	Type	Description
zip_base64	string	Base64-encoded ZIP from Figma Make
project_dir	string	Path to an already-unzipped Figma Make directory
golden_path	string	Target stack (see golden paths table above)
project_name	string	Output project slug (default: "my-app")

Provide either zip_base64 or project_dir, not both.

---

ingest_from_prompt(description, golden_path, project_name?, pages?, components?)

Generates a pipeline manifest from a text description — no Figma file needed.

Parameter	Type	Description
description	string	Natural language description of what to build
golden_path	string	Target stack
project_name	string	Output project slug (default: "my-app")
pages	string[]	Optional explicit page names, e.g. ["HomePage", "AboutPage"]. Auto-inferred if omitted.
components	string[]	Optional explicit component names, e.g. ["HeroSection", "Footer"]. Auto-inferred if omitted.

Use this for:

• Scaffold only — short description like "scaffold a nextjs-static starter" with no pages/components → produces boilerplate with no queued UI work
• Description-driven — describe the UI you want → components are inferred and created from scratch by the agent

---

ingest_from_codebase(project_dir, golden_path, project_name?)

Migrates an existing project to a golden path.

Parameter	Type	Description
project_dir	string	Absolute path to the existing project root
golden_path	string	Target stack to migrate toward
project_name	string	Output project slug (default: source directory name)

Config and tooling files (package.json, tsconfig.json, etc.) are automatically excluded — the golden path boilerplate versions replace them. Source components and pages are queued for the agent to rewrite to golden path conventions while preserving UI and logic.

Skips: node_modules, .next, dist, build, generated, .git, .turbo, and other build output directories.

---

remap_to_golden_path(manifest_json, user_prompt?)

Seeds the golden path reference boilerplate, classifies Figma/prompt/codebase files, and writes one queue file per component for the LLM agent to process.

Parameter	Type	Description
manifest_json	string	JSON returned by any of the three ingestion tools
user_prompt	string	Optional extra instructions, e.g. "use Inter font", "add dark mode"

Input: manifest from any ingestion tool Output: _nexus_cache pointer + instructions to spawn the golden path agent

---

validate_output(file_tree_json)

Runs static analysis on the generated file tree before packaging. Checks for:

• Missing required files (per manifest.json)
• Broken @/ imports
• Leftover Figma artifacts (React.FC, bare import React, inline styles)
• Missing "use client" on components that use hooks or event handlers
• Default exports in components/ (should be named exports)
• oklch() color usage (must be hsl())
• tailwind.config references (disallowed in Tailwind v4)
• Hardcoded hex colors in TSX files
• process.env in vite-spa (must be import.meta.env.VITE_*)
• Unsafe browser globals (localStorage, sessionStorage) without SSR guards
• console.log/warn/error calls left in production code
• Orphan files, duplicate paths, unprocessed queue files

Input: summary JSON from remap_to_golden_path Returns: { "passed": bool, "error_count": N, "warning_count": N, "errors": [...], "warnings": [...] }

---

package_output(file_tree_json)

Zips the generated file tree into an archive on disk. Orphan files (unreachable from entry points and not config/passthrough) are automatically stripped before packaging.

Input: summary JSON from remap_to_golden_path Returns: { "zip_path": "/tmp/nexus-<name>/<name>.zip", "total_files": N, "stripped_files": [...], "files": [...], "size_bytes": N, "instructions": "..." }

---

update_file_in_tree(path, content, nexus_cache)

Writes a transformed file's content back into the cached file tree. Intended for API-only clients (e.g. n8n) that cannot write to the filesystem directly.

Parameter	Type	Description
path	string	Relative file path matching the queue item (e.g. "components/ui/button.tsx")
content	string	Fully transformed file content
nexus_cache	string	_nexus_cache value from remap_to_golden_path (e.g. "/tmp/nexus-my-app")

Note: The standard Claude Code pipeline writes files directly using its own file tools — this tool is only needed by headless/API integrations.

---

Project Structure

nexus-mcp/
├── nexus_server.py              # MCP server entry point (nexus-mcp)
├── nexus_cli.py                 # CLI entry point (nexus)
├── tools/
│   ├── search.py                # nexus_search + nexus_read
│   └── figma/
│       ├── __init__.py          # Registers all pipeline tools
│       ├── ingest.py            # ingest_figma_zip
│       ├── prompt_ingest.py     # ingest_from_prompt
│       ├── codebase_ingest.py   # ingest_from_codebase
│       ├── remap.py             # remap_to_golden_path
│       ├── validate.py          # validate_output
│       ├── package.py           # package_output
│       └── filetree.py          # update_file_in_tree
├── golden_paths/
│   ├── nextjs-fullstack/
│   │   ├── manifest.json        # Stack metadata, routing, required files, classification rules
│   │   └── reference/           # Boilerplate seeded at pipeline start
│   ├── nextjs-static/
│   ├── t3-stack/
│   ├── vite-spa/
│   ├── monorepo/
│   ├── full-stack-rn/           # Next.js web + Expo mobile monorepo
│   └── full-stack-flutter/      # Next.js web + Flutter mobile monorepo
├── .claude/agents/              # Per-golden-path LLM transformation agents
│   ├── nextjs-fullstack.md
│   ├── nextjs-static.md
│   ├── t3-stack.md
│   ├── vite-spa.md
│   ├── monorepo.md
│   ├── full-stack-rn.md
│   └── full-stack-flutter.md
├── tests/
│   ├── test_figma_pipeline.py
│   ├── test_nexus_server.py
│   ├── test_improvements.py     # 41 unit/integration tests for pipeline improvements
│   └── test_mcp_protocol.py     # 17 MCP protocol-layer tests via FastMCP.call_tool()
├── GOLDEN_PATH_GUIDE.md         # Decision guide: which golden path to choose
├── ADDING_GOLDEN_PATHS.md       # Developer guide: adding new golden paths / language support
├── MAINTENANCE.md               # Quarterly upkeep: version bumps, known breaking patterns
├── pyproject.toml
└── README.md

---

Testing

# Run all tests
uv run pytest tests/ -v

# Run only pipeline tests
uv run pytest tests/test_figma_pipeline.py -v

# Run only server tests
uv run pytest tests/test_nexus_server.py -v

# Run pipeline improvement tests (41 tests)
uv run pytest tests/test_improvements.py -v

# Run MCP protocol tests (17 tests)
uv run pytest tests/test_mcp_protocol.py -v

---

Further Reading

Document	Purpose
GOLDEN_PATH_GUIDE.md	Decision tree and use-case profiles for choosing a golden path
ADDING_GOLDEN_PATHS.md	How to add a new golden path or extend to other languages/frameworks
MAINTENANCE.md	Version upkeep, quarterly sweep process, known breaking patterns
VERIFICATION.md	Step-by-step server connection and tool verification

---

Contributing

Contributions are welcome. Please ensure:

• All tests pass: uv run pytest tests/
• New features include tests
• Version changes in reference/package.json are reflected in the corresponding .claude/agents/{name}.md Stack table (see MAINTENANCE.md)

---

License

MIT License — see LICENSE for details.