@nex-ai/nex 0.1.65 → 0.2.0

package/README.md

@@ -1,44 +1,61 @@
 # Nex: Compounding Intelligence for AI agents
 
 [![npm version](https://img.shields.io/npm/v/@nex-ai/nex)](https://www.npmjs.com/package/@nex-ai/nex)
-[![GitHub](https://img.shields.io/badge/github-nex--crm%2Fnex--as--a--skill-blue)](https://github.com/nex-crm/nex-as-a-skill)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white)](https://discord.gg/gjSySC3PzV)
 
-Turn all your AI agent conversations into a unified knowledge graph with proactive context surfacing. Supports Claude Code, Codex, OpenClaw, Cursor, OpenCode, etc. Adds additional context from Email, Meetings, Slack, HubSpot, Salesforce.
+Turn all your AI agent conversations into a unified knowledge graph. Supports Claude Code, Codex, OpenClaw, Cursor, OpenCode, etc. Adds additional context from Email, Meetings, Slack, HubSpot, Salesforce.
+
+Tell something to OpenClaw. Ask about it in Claude Code. Reference it from Cursor. Context follows you across tools — no copy-pasting, no re-explaining, no lost context.
 
 <a href="https://discord.gg/gjSySC3PzV"><img src="https://img.shields.io/badge/Join%20our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord" /></a>
 
 Talk to the team, share feedback, and connect with other developers building AI agents with Nex.
 
-**GitHub**: [github.com/nex-crm/nex-as-a-skill](https://github.com/nex-crm/nex-as-a-skill)
+## How It Works
 
-## Install
+```
+You → OpenClaw: "Maria Rodriguez, CTO of TechFlow, wants to expand to Europe in Q3. Budget is $2M."
 
-```bash
-# Install globally
-npm install -g @nex-ai/nex
+You → Claude Code: "What do you know about Maria Rodriguez?"
+Claude Code: "Maria Rodriguez is the CTO of TechFlow. They're planning European expansion
+              in Q3 with a $2M budget."
 
-# Or run directly (no install)
-npx @nex-ai/nex ask "who is Maria?"
+You → Cursor: "Which companies are planning European expansion?"
+Cursor: "TechFlow — Maria Rodriguez (CTO) confirmed Q3 timeline, $2M budget."
 ```
 
+One fact entered once. Available everywhere, instantly.
+
+## Integration Options
+
+| | CLI + MCP Server | OpenClaw Plugin | Claude Code Plugin | Scripts |
+|---|---|---|---|---|
+| **Platforms** | Any terminal, Claude Desktop, ChatGPT, Cursor, Windsurf | OpenClaw | Claude Code CLI | OpenClaw (script-based) |
+| **Auto-recall** | Via `nex recall` / MCP tool calls | Yes (smart filter) | Yes (smart filter) | No (manual) |
+| **Auto-capture** | Via `nex capture` | Yes | Yes | No (manual) |
+| **Notifications** | Daily digest + proactive alerts (Channels API) | No | No | No |
+| **Commands** | 50+ CLI commands, 50+ MCP tools, `nex mcp` | 4 tools + 4 commands | 5 slash commands + MCP | bash scripts |
+| **Setup** | `nex setup` | Copy plugin | `nex setup` | Set `NEX_API_KEY` |
+
 ## Quick Start (Recommended)
 
 ```bash
-# One command to get started — registers, detects platforms, installs hooks, scans files
+# Install and run setup — handles everything in one step
+npm install -g @nex-ai/nex
 nex setup
 ```
 
-`nex setup` handles the base install flow: API key registration or re-keying, platform detection, platform installation, optional first integration connection, file scanning, and config creation.
+`nex setup` registers your API key, auto-detects your AI platforms (Claude Code, Cursor, Windsurf, etc.), installs hooks, scans project files, and creates config. One command, fully configured.
 
 ```bash
-# Now query your knowledge
-nex ask "what's the latest on the Acme deal?"
+# Now use it from any agent
+nex ask "who is Maria Rodriguez?"
+nex remember "Met with Maria, CTO of TechFlow. European expansion Q3, $2M budget."
 ```
 
 ## Copy-Paste Prompt For Any AI Agent
 
-Use this when you want Claude, Codex, Cursor, OpenCode, or another terminal-capable AI agent to do the full Nex bootstrap for you.
+Drop this prompt into any terminal-capable AI agent when you want it to bootstrap Nex for you end to end:
 
 ```text
 Install and fully bootstrap Nex in this project from start to finish.
@@ -62,299 +79,287 @@ Do not stop after partial setup. Only pause if you need my email for registratio
 
 This works best in agents that can run shell commands and open OAuth URLs.
 
+---
+
 <details>
-<summary>Manual setup (if you prefer step-by-step)</summary>
+<summary>Manual setup per platform (if you prefer step-by-step)</summary>
+
+### CLI (any terminal, any AI agent)
 
 ```bash
-# 1. Register for an API key
-nex register --email you@company.com
+npx @nex-ai/nex register --email you@company.com
+```
 
-# 2. Set up your platforms (auto-detects installed tools)
-nex setup
+That's it. Now use it:
 
-# 3. Query your knowledge
-nex ask "what's the latest on the Acme deal?"
-```
+```bash
+# Ask your knowledge graph
+nex ask "who is Maria Rodriguez?"
 
-</details>
+# Ingest information
+nex remember "Met with Maria Rodriguez, CTO of TechFlow. European expansion Q3, $2M budget."
+
+# Or pipe from stdin
+cat meeting-notes.txt | nex remember
+
+# Search CRM records
+nex search "TechFlow"
+
+# CRUD operations
+nex record list person --limit 10
+nex task create --title "Follow up with Maria" --priority high
+nex insight list --last 24h
+
+# Build auto-recall hooks for any agent
+nex recall "what do I know about TechFlow?"  # Returns <nex-context> XML block
 
-## Supported Platforms
+# Build auto-capture hooks
+nex capture "Agent conversation text..."  # Rate-limited, filtered
+```
 
-`nex setup` auto-detects and configures these platforms with full-depth integration:
+Install globally: `npm install -g @nex-ai/nex`
 
-| Platform | Hooks | Plugins | Agents | Workflows | Rules | MCP |
-|----------|-------|---------|--------|-----------|-------|-----|
-| **Claude Code** | SessionStart, UserPromptSubmit, Stop | — | — | 26 slash commands | — | — |
-| **Cursor** | sessionStart, userPromptSubmit, stop | — | — | — | `.cursor/rules/nex.md` | `~/.cursor/mcp.json` |
-| **Windsurf** | pre_user_prompt, post_cascade_response | — | — | /nex-ask, /nex-remember, /nex-search | `.windsurf/rules/nex.md` | `mcp_config.json` |
-| **Cline** | UserPromptSubmit, TaskStart, TaskComplete | — | — | — | `.clinerules/nex.md` | `cline_mcp_settings.json` |
-| **OpenClaw** | auto-recall, auto-capture (plugin) | `openclaw plugins install` (49 tools) | — | — | — | — |
-| **OpenCode** | — | `.opencode/plugins/nex.ts` | — | — | `AGENTS.md` | `opencode.json` |
-| **VS Code** | — | — | `.github/agents/nex.agent.md` | — | `.github/instructions/` | `.vscode/mcp.json` |
-| **Kilo Code** | — | — | `.kilocodemodes` | — | `.kilocode/rules/nex.md` | `.kilocode/mcp.json` |
-| **Continue.dev** | — | — | — | — | `.continue/rules/nex.md` | `mcp.json` |
-| **Zed** | — | — | — | — | `.rules` | `settings.json` |
-| **Claude Desktop** | — | — | — | — | — | `claude_desktop_config.json` |
-| **Aider** | — | — | — | — | `CONVENTIONS.md` | — |
+### MCP Server (Claude Desktop, Cursor, Windsurf)
 
-All MCP-based platforms use the same server entry (bundled in this package):
+The MCP server is bundled inside `@nex-ai/nex`. No separate package needed.
 
 ```json
 {
-  "nex": {
-    "command": "nex-mcp",
-    "env": { "NEX_API_KEY": "sk-..." }
+  "mcpServers": {
+    "nex": {
+      "command": "nex-mcp",
+      "env": { "NEX_API_KEY": "sk-your_key_here" }
+    }
   }
 }
 ```
 
-Or without a global install: `"command": "npx", "args": ["-y", "@nex-ai/nex", "mcp"]`
-
-## Setup Command
+Or without a global install:
 
-```bash
-nex setup                          # Auto-detect platforms, install full stack, scan files, create .nex.toml
-nex setup --platform cursor        # Install for a specific platform only
-nex setup --no-hooks               # Skip hook installation for all platforms
-nex setup --no-plugin              # Skip hooks/commands (alias for --no-hooks)
-nex setup --no-rules               # Skip rules/instruction file installation
-nex setup --no-scan                # Skip file scanning during setup
-nex setup status                   # Show all platforms, install status, and connections
-nex graph                          # Open the workspace graph in your browser
+```json
+{
+  "mcpServers": {
+    "nex": {
+      "command": "npx",
+      "args": ["-y", "@nex-ai/nex", "mcp"],
+      "env": { "NEX_API_KEY": "sk-your_key_here" }
+    }
+  }
+}
 ```
 
-**Default behavior** (no flags):
-- If no API key exists: prompts to register
-- If API key exists: offers to regenerate (picks up latest scopes) or change email
-- Installs the full 6-layer hierarchy for each detected platform: hooks → plugins → agents → workflows → rules → MCP
-- Scans current directory and ingests new/changed files into Nex
-- Creates `.nex.toml` project config with commented defaults
-- Stores config in `~/.nex/config.json`
+No API key? The server starts in registration mode — call the `register` tool with your email.
 
-**Single install**: `npm install -g @nex-ai/nex` bundles everything — hooks, adapters, platform plugins, slash commands, rules, MCP server, and notification channel. No separate packages needed.
+### Proactive Notifications (Claude Code Channels)
 
-**Integration hierarchy** (per platform): Hooks > Custom plugins > Custom agents/modes > Workflows > Rules > MCP. Each platform gets every layer it supports.
+The MCP server includes a built-in notification channel that pushes context updates directly into your Claude Code session — without you having to ask. This uses the [Claude SDK Channels API](https://code.claude.com/docs/en/channels-reference).
 
-## Project Config: `.nex.toml`
+**What you get:**
 
-Per-project settings file created by `nex setup`. All fields are optional.
+| Notification | What it does | Frequency |
+|---|---|---|
+| **Daily digest** | Summarizes all context collected in the last 24 hours: deal updates, new relationships, upcoming events, actionable items | Once per day (on first session start after 24h) |
+| **Proactive alerts** | Pushes new insights as they're discovered — deal changes, relationship shifts, risks, opportunities | Every 15 minutes (configurable) |
 
-```toml
-[auth]
-# api_key = "sk-..."          # Prefer NEX_API_KEY env var or ~/.nex/config.json
+**How to enable:**
 
-[hooks]
-# enabled = true              # Master kill switch for all hooks
+1. Install Nex globally (if not already):
+   ```bash
+   npm install -g @nex-ai/nex
+   ```
 
-[hooks.recall]
-# enabled = true              # Proactive context on every prompt
-# debounce_ms = 10000
+2. Add the MCP server to your project (`.mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "nex": {
+         "command": "nex-mcp",
+         "env": {}
+       }
+     }
+   }
+   ```
 
-[hooks.capture]
-# enabled = true              # Auto-capture on conversation stop
-# min_length = 20
-# max_length = 50000
+3. Start Claude Code with channels enabled:
+   ```bash
+   claude --dangerously-load-development-channels server:nex
+   ```
 
-[hooks.session_start]
-# enabled = true              # Load context on session start
+4. That's it. Notifications arrive as `<channel>` events in your session:
+   ```
+   ← nex: [technical_stack] MCP server utilizes experimental channel capability...
+   ← nex: [deal_update | high] Meridian counter-offer moved to 12% equity split...
+   ```
 
-[scan]
-# enabled = true
-# extensions = [".md", ".txt", ".csv", ".json", ".yaml", ".yml"]
-# ignore_dirs = ["node_modules", ".git", "dist", "build", "__pycache__"]
-# max_files = 1000
-# max_file_size = 100000
-# depth = 2
+**Configuration:**
 
-[mcp]
-# enabled = false             # Set to true when `nex setup` installs MCP for this project/platform
+| Environment variable | Default | Description |
+|---|---|---|
+| `NEX_NOTIFY_INTERVAL_MINUTES` | `15` | How often to poll for new insights |
 
-[output]
-# format = "text"             # "text" | "json"
-# timeout = 120000
+Set it in your `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "nex": {
+      "command": "nex-mcp",
+      "env": { "NEX_NOTIFY_INTERVAL_MINUTES": "5" }
+    }
+  }
+}
 ```
 
-**Resolution order:** CLI flags > `.nex.toml` > env vars > `~/.nex/config.json` > defaults
+**State persistence:** Digest and notification timestamps are stored in `~/.nex/channel-state.json`. Delete this file to force a fresh digest on next session start.
 
-## Commands
+**Requirements:** Claude Code v2.1.80+, claude.ai login (API keys not supported for Channels), `--dangerously-load-development-channels` flag during research preview.
 
-### Knowledge Graph
+### OpenClaw Plugin (auto-recall + auto-capture)
 
 ```bash
-nex ask <query>              # Query with natural language
-nex remember <content>       # Ingest text (meeting notes, emails, docs)
-nex recall <query>           # Query → XML-wrapped for agent injection
-nex capture [content]        # Rate-limited ingestion for agent hooks
-nex artifact <id>            # Check processing status
-nex search <query>           # Search CRM records by name
-nex insight list [--last 24h]  # Recent insights
-nex graph                    # Visualize your workspace graph in the browser
+cp -r openclaw-plugin /path/to/openclaw/plugins/nex
+cd /path/to/openclaw/plugins/nex && bun install && bun run build
 ```
 
-### Integrations
+Add to `openclaw.json`:
 
-```bash
-nex integrate list                  # Show all integrations with connection status
-nex integrate connect gmail         # Connect Gmail via OAuth
-nex integrate connect slack         # Connect Slack
-nex integrate disconnect <id>      # Disconnect by connection ID
+```json
+{
+  "plugins": {
+    "load": { "paths": ["/path/to/plugins/nex"] },
+    "slots": { "memory": "nex" },
+    "entries": {
+      "nex": {
+        "enabled": true,
+        "config": {
+          "apiKey": "sk-your_key_here"
+        }
+      }
+    }
+  }
+}
 ```
 
-Available integrations: `gmail`, `google-calendar`, `outlook`, `outlook-calendar`, `slack`, `salesforce`, `hubspot`, `attio`.
-
-### CRM Records
-
-```bash
-nex object list              # List object types (person, company, deal)
-nex record list person --limit 10
-nex record create person --data '{"name":"Jane Doe"}'
-nex record upsert person --match email --data '{"name":"Jane","email":"jane@co.com"}'
-nex record update <id> --data '{"phone":"+1234"}'
-nex record delete <id>
-nex record timeline <id>
-```
+See [`openclaw-plugin/README.md`](openclaw-plugin/README.md) for details.
 
-### Tasks & Notes
+### Claude Code Plugin (auto-recall + auto-capture)
 
 ```bash
-nex task create --title "Follow up" --priority high --due 2026-04-01
-nex task list --assignee me --search "follow up"
-nex task update <id> --completed
-nex note create --title "Call notes" --content "..." --entity <record-id>
+cd claude-code-plugin && bun install && bun run build
 ```
 
-### Relationships & Lists
+Add hooks to `~/.claude/settings.json`:
 
-```bash
-nex rel list-defs
-nex rel create <record-id> --def <def-id> --entity1 <id1> --entity2 <id2>
-nex list list person
-nex list add-member <list-id> --parent <record-id>
-nex list-job create "enterprise contacts in EMEA"
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "NEX_API_KEY=sk-your_key node /path/to/claude-code-plugin/dist/auto-recall.js",
+        "timeout": 10000
+      }]
+    }],
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "NEX_API_KEY=sk-your_key node /path/to/claude-code-plugin/dist/auto-capture.js",
+        "timeout": 5000,
+        "async": true
+      }]
+    }]
+  }
+}
 ```
 
-### File Scanning
-
-On session start, Nex automatically scans project files and ingests changed content using concurrent workers (5 parallel requests). After ingestion, compounding intelligence jobs are triggered automatically to generate patterns and playbook rules.
+Slash commands and MCP server:
 
 ```bash
-nex scan                    # Scan current directory (up to 1000 files)
-nex scan --max-files 500    # Limit files per scan
-nex scan --force            # Re-scan all files (ignore manifest)
-nex scan --dry-run          # Preview what would be scanned
+cp claude-code-plugin/commands/*.md ~/.claude/commands/    # /nex:recall, /nex:remember, /nex:scan, /nex:entities
+claude mcp add nex -- nex-mcp                               # Full toolset
 ```
 
-**Default text-based extensions:** `.md`, `.txt`, `.csv`, `.json`, `.yaml`, `.yml`
+See [`claude-code-plugin/README.md`](claude-code-plugin/README.md) for details.
 
-**Document formats** (handled separately): `.docx`, `.doc`, `.odt`, `.xlsx`, `.xls`, `.pptx`, `.ppt`, `.pdf`
+### Scripts (OpenClaw script-based)
 
-Configure via `.nex.toml` `[scan]` section or environment variables (`NEX_SCAN_ENABLED`, `NEX_SCAN_EXTENSIONS`, etc.).
-
-### Proactive Context
-
-Nex surfaces relevant knowledge graph context on every prompt — not just questions. When you say "fix the migration script" or "deploy to staging", the system automatically injects entity insights, knowledge insights, and playbook patterns from your knowledge graph.
-
-Context is injected as `<nex-context>` blocks that AI agents use naturally without explicitly referencing the source. Only trivial inputs (yes/ok/lgtm) are skipped.
-
-### Transcript Capture
-
-At session end, the full conversation transcript is automatically ingested into the knowledge graph. This captures complete decision trails, code discussions, and debugging sessions — not just the last message.
-
-### MCP Server & Notifications
+For OpenClaw agents without the plugin, bash scripts provide direct API access:
 
 ```bash
-nex mcp                         # Start the embedded MCP server (stdio)
-MCP_TRANSPORT=http nex mcp      # Start with HTTP transport
-```
-
-#### Proactive Notifications (Claude Code Channels)
-
-The MCP server pushes context updates directly into your Claude Code session using the [Channels API](https://code.claude.com/docs/en/channels-reference). No polling commands needed — insights arrive automatically while you work.
+# Register and get API key
+bash scripts/nex-openclaw-register.sh your@email.com "Your Name"
 
-**Two notification types:**
+# Query context
+printf '{"query":"who is Maria?"}' | bash scripts/nex-api.sh POST /v1/context/ask
 
-- **Daily digest** — Comprehensive summary of all context collected in the last 24 hours (deal changes, new relationships, upcoming events, actionable items). Fires once per day on session start.
-- **Proactive alerts** — New insights pushed every 15 minutes: relationship changes, deal updates, risks, opportunities. Configurable via `NEX_NOTIFY_INTERVAL_MINUTES`.
-
-**Quick setup:**
-
-```bash
-# 1. Add MCP server to your project
-cat > .mcp.json << 'EOF'
-{
-  "mcpServers": {
-    "nex": { "command": "nex-mcp", "env": {} }
-  }
-}
-EOF
+# Ingest text
+printf '{"content":"Meeting notes..."}' | bash scripts/nex-api.sh POST /v1/context/text
 
-# 2. Start Claude Code with channels
-claude --dangerously-load-development-channels server:nex
+# Scan project files
+bash scripts/nex-scan-files.sh --dir . --max-files 10
 ```
 
-Notifications appear as `<channel source="nex">` events in your session. Claude reads them automatically and incorporates the context.
-
-**Customize frequency:**
+See the [scripts directory](scripts/) for details.
 
-```json
-{
-  "mcpServers": {
-    "nex": {
-      "command": "nex-mcp",
-      "env": { "NEX_NOTIFY_INTERVAL_MINUTES": "5" }
-    }
-  }
-}
-```
+</details>
 
-**Force a fresh digest:** `rm ~/.nex/channel-state.json`
+## Shared Config
 
-**Requirements:** Claude Code v2.1.80+, claude.ai login, `--dangerously-load-development-channels` during research preview.
+All surfaces share configuration for cross-tool compatibility:
 
-### Config & Sessions
+| File | Purpose | Shared by |
+|------|---------|-----------|
+| `~/.nex-mcp.json` | API key + workspace info | All surfaces |
+| `~/.nex/file-scan-manifest.json` | File change tracking | All surfaces |
+| `~/.nex/rate-limiter.json` | Rate limit timestamps | OC, MCP, CC |
+| `~/.nex/recall-state.json` | Recall debounce state | CC |
 
-```bash
-nex config show              # Resolved config (key masked)
-nex config set default_format text
-nex config path              # ~/.nex/config.json
-nex session list             # Stored session mappings
-nex session clear
-```
+Register once via any surface → all other surfaces pick up the key automatically.
 
-## Global Flags
+## Architecture
 
 ```
---api-key <key>     Override API key (env: NEX_API_KEY)
---format <fmt>      json | text (default for integrate list) | quiet
---timeout <ms>      Request timeout (default: 120000)
---session <id>      Session ID for multi-turn context
---debug             Debug output on stderr
+                    ┌─────────────────────┐
+                    │   Nex Context Graph  │
+                    │  (people, companies, │
+                    │  insights, tasks...) │
+                    └──────────┬──────────┘
+                               │
+      ┌────────────────────────┼────────────────────────┐
+      │              │                   │              │
+  ┌───▼────┐  ┌─────▼───────┐  ┌───────▼──────┐  ┌───▼──────────┐
+  │  CLI   │  │  MCP Server │  │  OpenClaw    │  │  Claude Code │
+  │  50+   │  │  50+ tools  │  │  Plugin     │  │  Plugin      │
+  │  cmds  │  │  + scan     │  │  + recall   │  │  + recall    │
+  └───┬────┘  └─────┬───────┘  └──────┬──────┘  └──────┬───────┘
+      │             │                 │                 │
+  Any agent    Claude Desktop    OpenClaw agents   Claude Code
+  Aider        ChatGPT          Clawgent          Any project
+  Codex        Cursor            WhatsApp
+  Custom       Windsurf
 ```
 
-## Stdin Support
+## Environment Variables
 
-`ask`, `remember`, and `capture` read from stdin when no argument is provided:
+| Variable | Required | Default |
+|----------|----------|---------|
+| `NEX_API_KEY` | Yes (or register) | — |
+| `NEX_DEV_URL` | No (dev only) | `https://app.nex.ai` |
+| `NEX_SCAN_ENABLED` | No | `true` |
+| `NEX_SCAN_EXTENSIONS` | No | `.md,.txt,.rtf,.html,.htm,.csv,.tsv,.json,.yaml,.yml,.toml,.xml,.js,.ts,.jsx,.tsx,.py,.rb,.go,.rs,.java,.sh,.bash,.zsh,.fish,.org,.rst,.adoc,.tex,.log,.env,.ini,.cfg,.conf,.properties` |
+| `NEX_SCAN_MAX_FILES` | No | `5` |
+| `NEX_SCAN_DEPTH` | No | `20` |
+| `NEX_SCAN_MAX_FILE_SIZE` | No | `100000` (bytes) |
+| `NEX_SCAN_IGNORE_DIRS` | No | `node_modules,.git,dist,build,.next,__pycache__,vendor,.venv,.claude,coverage,.turbo,.cache` |
+| `NEX_NOTIFY_INTERVAL_MINUTES` | No | `15` |
 
-```bash
-cat meeting-notes.txt | nex remember
-echo "what happened today?" | nex ask
-git diff | nex capture
-```
+## Testing
 
-## Exit Codes
+- **Shims**: `npm test` (syntax validation of bin/ shims)
+- **OpenClaw plugin**: `cd openclaw-plugin && npx vitest run`
+- **Claude Code plugin**: `cd claude-code-plugin && bun test`
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error (server error, rate limit, invalid input) |
-| 2 | Auth error (no API key, invalid key, 401/403) |
+## License
 
-## Development
-
-```bash
-bun install
-bun run build     # TypeScript → dist/
-bun run dev       # Run TS directly (no build)
-bun test          # Unit + integration tests
-NEX_DEV_URL=http://localhost:30000 nex ask "test"  # Local API
-```
+MIT

package/bin/nex-mcp.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Thin shim for nex-mcp — delegates to nex-cli mcp.
+ *
+ * This entry point exists for MCP registry compatibility.
+ * Platforms like Claude Desktop install MCP servers via: npx @nex-ai/nex
+ * which resolves to this shim, which delegates to the nex-cli binary.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const args = ["mcp", ...process.argv.slice(2)];
+
+function tryExec(command, commandArgs) {
+  try {
+    execFileSync(command, commandArgs, { stdio: "inherit" });
+    return true;
+  } catch (err) {
+    if (err.status !== null && err.status !== undefined) {
+      process.exit(err.status);
+    }
+    return false;
+  }
+}
+
+if (tryExec("nex-cli", args)) {
+  process.exit(0);
+}
+
+const commonPaths = ["/usr/local/bin/nex-cli"];
+if (process.env.HOME) {
+  commonPaths.push(`${process.env.HOME}/.local/bin/nex-cli`);
+}
+for (const p of commonPaths) {
+  if (existsSync(p) && tryExec(p, args)) {
+    process.exit(0);
+  }
+}
+
+console.error(`
+  nex-cli binary not found.
+
+  Install it with:
+    curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-cli/main/install.sh | sh
+
+  Then run your command again.
+`);
+process.exit(1);