# nexus-mcp

An **MCP (Model Context Protocol) server** that exposes a real sales CRM as tools an AI agent can call — plus a CLI that does the same job with no model involved.

Built to solve an actual problem, not as an exercise. I run a small web-development studio and my CRM had grown to ~270 prospects with long free-text notes that nobody re-read. Prospects who had shown interest were quietly dying in the list, because a spreadsheet only shows you what you remember to look for. The first time I ran this, it surfaced two leads I had abandoned a week earlier.

```
$ nexus-crm hoy

VENCIDOS (1)
────────────
#a3f21c08-4d19-4b7e-9e02-6c1f8b40d772 Estudio Ferrari & Asoc. · Legal · Zárate [Respondió]
    contacto: contacto@ferrari.example.com · seguir: 2026-07-24 · $450000
    vencido hace 3 día(s)

ABANDONADOS — nadie les puso fecha (4)
──────────────────────────────────────
#7b90e4d1-2c53-49aa-8f61-0d5e7a3c9b14 Odontología Norte · Salud · Zárate [Respondió]
    contacto: +54 9 3487 000002 · $590000
...
```

> The output above comes from `demo/seed.sql` — invented businesses, invented phone numbers, reserved `example.com` domains. No client data lives in this repository.

## The five tools

| Tool | What it does |
|---|---|
| `buscar_prospectos` | Free-text search across name, industry, area, contact and notes, with optional filters by status/industry/area |
| `resumen_pipeline` | Pipeline snapshot: count per status, overdue follow-ups, abandoned leads, total value at stake |
| `seguimientos_pendientes` | Who to chase: overdue, upcoming, and **abandoned** — interested, not discarded, and with no follow-up date set |
| `cambiar_estado` | Move a prospect along the pipeline |
| `agregar_nota` | Append a dated entry to the prospect's history, in the same format the CRM's own UI writes |

The third one is the reason this exists. Overdue follow-ups are easy — any list view shows them. Leads with *no date at all* are invisible by construction, and those are the ones that cost money.

## Stack

TypeScript · Node 22 · [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) · Supabase (PostgreSQL) · Zod

Tool inputs are validated with Zod schemas, so the model gets a typed contract and a useful error instead of a silent failure. The server speaks MCP over **stdio**, which is what desktop MCP clients expect.

## Row-level security

The `prospectos` table has RLS enabled. Worth knowing, because it fails quietly: with the publishable key alone, Supabase returns an **empty list rather than an error** — so the tools look like they work and report zero results.

The server signs in with email/password before its first query and holds an authenticated session, which is what the RLS policy checks. Credentials live in `.env`, never in the repo.

## Running it

```bash
npm install
cp .env.example .env    # fill in your Supabase project and login
npm run build
```

**As a CLI:**

```bash
node dist/cli.js hoy
node dist/cli.js resumen
node dist/cli.js buscar odonto
node dist/cli.js estado 42 "Respondió"
node dist/cli.js nota 42 "resent the quote, he'll look at it this week"
```

**As an MCP server**, add it to your client's config:

```json
{
  "mcpServers": {
    "nexus-crm": {
      "command": "node",
      "args": ["/absolute/path/to/nexus-mcp/dist/server.js"]
    }
  }
}
```

Then ask in plain language: *"who should I follow up with today?"*, *"mark Ferrari as replied and note that he asked for the quote again"*.

## Trying it without my data

`demo/seed.sql` creates the table, its RLS policy and 15 fictional prospects — invented names, phone numbers and negotiation notes. Run it in an empty Supabase project, point your `.env` at it, and everything below works against that instead.

## What this is not

It doesn't replace the CRM and it doesn't collect data on its own. It's a query-and-update layer on top of a database that already existed. The CRM UI stays the place where records are created; this is for the question a UI is bad at answering: *what am I forgetting?*

## License

MIT