nexus-toolkit 2.1.0__tar.gz

nexus_toolkit-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nexus MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexus_toolkit-2.1.0/PKG-INFO

@@ -0,0 +1,566 @@
+Metadata-Version: 2.4
+Name: nexus-toolkit
+Version: 2.1.0
+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 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:
+
+```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: pip (simplest)
+
+```bash
+pip install git+https://github.com/rcdelacruz/nexus-mcp.git@multi-source-ingestion
+```
+
+### Option 2: uvx (faster, isolated)
+
+```bash
+# 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
+
+```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 .
+```
+
+---
+
+## Configuration
+
+### Claude Code (CLI)
+
+```bash
+# 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:
+
+```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@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`
+
+```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](#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.