Outreacher

An AI-powered lead qualification system with an MCP server for Claude Desktop and a Next.js SaaS frontend — built within 3 days.

All dev tooling runs via Docker. You do not need Go, Node, Bun, goose, or sqlc installed locally.

Developers: see CLAUDE.md for commands, conventions, and test instructions.

[!TIP] This project demonstrates and acts as a foundation boilerplate for 2-mode operation of an AI MCP as:

1. Single-tenant Claude Desktop Go binary (individual use)
2. Multi-tenant Next.js SaaS + chat LLM + MCP Go server (hosted environment)

The project architecture includes:

• AI SDK + assistant-ui chat
• Example MCP development
• Shared backend code for both binary and server operation
• Claude Code (and other development agent) usage and best practices
• Docker best practices for development and production
• Database security role/schema best practices (adopted early for scale)

📸 Demo & Walkthrough

See the full demo with screenshots and flows here:
👉 View Demo Docs

---

Architecture

Claude Desktop
  └── bin/outreacher-mcp-0.1.0-linux-amd64  (Go stdio binary, WSL)
        └── localhost:5432  (standalone postgres, volume: outreacher_standalone_data)

Browser / Next.js frontend
  └── app (Next.js, :3000)
        └── mcp (:3001, Go SSE server, air hot reload)
              └── postgres (internal only, volume: outreacher_postgres-data)

Two runtime modes — standalone binary for Claude Desktop, Docker Compose for development. Important: use separate named volumes for each mode to avoid data directory conflicts.

---

Tech Stack

• Next.js 15 (App Router, Bun)
• Go MCP server (mcp/) — stdio + SSE transports, pgx/v5, sqlc, goose migrations
• PostgreSQL 16 — app schema, named Docker volume
• Docker Compose — dev stack with air hot reload on the Go server

---

DB Users

User	Password	Role
admin	admin	Owns schema, runs DDL and migrations
app	app	Next.js runtime — member of app_crud + direct nextauth grants
mcp	mcp	MCP server runtime — member of app_crud
reporter	reporter	Read-only access — member of app_read

Group roles (no LOGIN) — DEFAULT PRIVILEGES auto-cover new tables/sequences/types:

• app_crud — SELECT/INSERT/UPDATE/DELETE on app schema
• app_read — SELECT on app schema

DATABASE_URL → mcp user (MCP server) or app user (Next.js). DATABASE_ADMIN_URL → admin user (goose only).

---

Schema (app)

Multi-tenancy

Table	Key fields
organizations	id, name, slug (unique), is_system
campaigns	id, organization_id, name, slug, is_default
users	id, email†, slug (unique), name, is_system
organization_memberships	organization_id, user_id, role (owner|admin|member)
campaign_memberships	campaign_id, user_id, role (admin|member|viewer)

Domain (scoped to campaign_id)

Table	Key fields
companies	id, campaign_id, name, domain, industry, linkedin_url
signals	id, description — global, no campaign scope
signal_keywords	signal_id, keyword — global
company_signals	company_id, signal_id
leads	id, campaign_id, name, email†, linkedin_url†, company_id, title, status, score, location, phone
notes	id, lead_id, content, created_at
contact_identifiers	campaign_id, type, value — dedup key, PK is (campaign_id, type, value)

† nullable. Leads are deduplicated by contact_identifiers, not by email.

Lead status flow: new → contacted → qualified → disqualified → converted

---

MCP Tools

Domain tools (all accept optional campaign_id; defaults to startup campaign)

Tool	Description
search_leads	Filter by name, email, status, company, campaign_id
get_lead	Full lead detail with company and notes
update_lead_status	Advance a lead through the status flow
create_followup_note	Append a note to a lead
import_csv	Import from CSV text (auto-detects Gojiberry, Revli formats)
search_companies	Search companies by name or domain
get_company	Full company detail with signals

Campaign management (stdio binary only)

Tool	Description
list_campaigns	List all campaigns for the current org
get_campaign	Get campaign details by id
create_campaign	Create a new campaign under the current org
rename_campaign	Rename a campaign's display name

---

Mode 1 — Claude Desktop (Go binary via WSL)

Build the binary:

npm run build:mcp
# outputs bin/outreacher-mcp-0.1.0-linux-amd64   (stdio, WSL)
#         bin/outreacher-mcp-0.1.0-darwin-arm64   (stdio, macOS Apple Silicon)
#         bin/outreacher-mcp-0.1.0-darwin-amd64   (stdio, macOS Intel)
#         bin/outreacher-mcp-0.1.0-windows-amd64.exe
#         bin/outreacher-server-0.1.0             (SSE server)

Start standalone postgres:

docker run -d --name outreacher-pg --restart always \
  -p 5432:5432 \
  -e POSTGRES_DB=outreacher \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=admin \
  -v outreacher_standalone_data:/var/lib/postgresql/data \
  -v "$(pwd)/postgres/init:/docker-entrypoint-initdb.d" \
  postgres:16-alpine

Run migrations:

PG_IP=$(docker inspect outreacher-pg --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}')
docker run --rm \
  -v "$(pwd)/mcp:/src" -w /src \
  --add-host=postgres:$PG_IP \
  golang:1.24-alpine \
  sh -c 'go run github.com/pressly/goose/v3/cmd/goose@latest \
    -dir migrations postgres \
    "postgresql://admin:admin@postgres:5432/outreacher" up'

Claude Desktop config (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "Outreacher": {
      "command": "wsl.exe",
      "args": [
        "~/Code/outreacher/bin/outreacher-mcp-0.1.0-linux-amd64",
        "--database-url", "postgresql://mcp:mcp@localhost:5432/outreacher",
        "--openai-api-key", "sk-proj-..."
      ]
    }
  }
}

Replace <user> with your WSL username. ANTHROPIC_API_KEY enables LLM-based CSV extraction for unknown formats; omit to use the built-in parsers only. Restart Claude Desktop after saving — the hammer icon confirms tools are connected.

The binary idempotently bootstraps system_default_org, system_default_user, and the Default campaign on first run.

---

Mode 2 — Docker Compose (dev stack)

Copy .env.example to .env and fill in API keys, then:

docker compose up --build -d

Service	Host port	Notes
app	3000	Next.js dev server
mcp	3001	Go SSE server, air hot reload
postgres	—	Internal only

First-time migrations:

docker run --rm --network outreacher_default \
  -v "$(pwd)/mcp:/src" -w /src \
  golang:1.24-alpine \
  sh -c 'go run github.com/pressly/goose/v3/cmd/goose@latest \
    -dir migrations postgres \
    "postgresql://admin:admin@outreacher-postgres-1:5432/outreacher" up'

If the mcp container exited while waiting for migrations, restart it:

docker compose restart mcp

---

Imports

fixtures/imports/ is gitignored — it contains live personal data used for local development and debugging only. Supported formats: Gojiberry, Revli startup contacts, Revli investor contacts, Revli startup companies, Revli investor companies.

© Copyright

© 2026 Vitruvian Technology, Corp. All rights reserved.

This code is provided under a noncommercial license for evaluation and research purposes only.