Metadata-Version: 2.4
Name: nexus-toolkit
Version: 2.1.3
Summary: Hybrid search, retrieval, and Figma Make boilerplate generation MCP server
Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://nexus.coderstudio.co
Project-URL: Repository, https://github.com/rcdelacruz/nexus-mcp
Project-URL: Issues, https://github.com/rcdelacruz/nexus-mcp/issues
Project-URL: Changelog, https://github.com/rcdelacruz/nexus-mcp/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: ddgs>=1.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Dynamic: license-file

# Nexus — Enterprise Dev Toolkit

> **The Hybrid Search, Retrieval & Design-to-Code Engine for AI Agents.**

Nexus 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.

**Two ways to use Nexus:**

| Mode | How | Best for |
|------|-----|----------|
| **CLI** (`nexus`) | Install via one-liner, run from terminal | Local development, standalone use |
| **MCP server** (`nexus-mcp`) | Add to Claude Code / n8n / Claude Desktop | AI agent workflows, n8n automation |

---

## 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:

```mermaid
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: One-liner (recommended)

```bash
curl -fsSL https://nexus.coderstudio.co/install.sh | bash
```

### Option 2: pip / uv

```bash
pip install nexus-toolkit
# or
uv tool install nexus-toolkit
```

### Option 3: Development install

```bash
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 .
```

### Server / n8n (install from git for latest)

```bash
uvx --reinstall --from git+https://github.com/rcdelacruz/nexus-mcp@main nexus-mcp
systemctl --user restart nexus-sse
```

---

## Configuration

### Claude Code (CLI)

```bash
# uvx (recommended)
claude mcp add nexus -- uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git@main 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:

```bash
# 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@main 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`

```json
{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rcdelacruz/nexus-mcp.git@main", "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](#installation))
- [`claude` CLI](https://claude.ai/code) 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

```bash
# 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)

```bash
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:
```bash
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

```bash
# 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

```bash
# 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](GOLDEN_PATH_GUIDE.md) | Decision tree and use-case profiles for choosing a golden path |
| [ADDING_GOLDEN_PATHS.md](ADDING_GOLDEN_PATHS.md) | How to add a new golden path or extend to other languages/frameworks |
| [MAINTENANCE.md](MAINTENANCE.md) | Version upkeep, quarterly sweep process, known breaking patterns |
| [VERIFICATION.md](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](LICENSE) for details.
