convez.ai
MCP ServerMarketing & VendasIntermediário
Lakshya330-sudo

Leadcraft — Gerador de Leads para Agentes IA

Lakshya330-sudo/leadcraft

Prospecção, enriquecimento e automação de outreach via slash commands

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma agentes IA em copiloto de vendas, descobrindo prospects na web aberta, enriquecendo dados com decision-makers reais e redigindo emails personalizados de prospecção. Funciona em Claude Code e ambientes compatíveis com MCP, sem APIs pagas, SMTP ou scraping de LinkedIn.

Instalação

$npx convez-ai Lakshya330-sudo/leadcraft

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Preencher pipeline de vendas com prospects qualificados automaticamente
  • Gerar emails de cold outreach personalizados baseados em pesquisa web
  • Rastrear e estruturar dados de leads em planilhas sem ferramentas externas pagas

Veredito

Ferramenta pragmática para equipes pequenas e freelancers que vendem via outreach. Forte em automação Web + CSV, mas requer disciplina na qualificação manual dos leads descobertos. Ideal para quem quer evitar SaaS de prospecção caros.

README

A tradução para o português deste README ainda está na fila.

leadcraft

Lead generator plugin for AI coding agents (Claude Code, OpenCode, MCP). Discover prospects, draft personalized cold outreach, track replies — no paid APIs, no SMTP, no LinkedIn scraping.

npm version license node claude code

Tell the agent what you sell. It walks the open web, fills a spreadsheet with 25 prospects, deepens each one with a real decision-maker, and drafts cold email or LinkedIn DMs you can review and send from your own client.

Works in Claude Code (native plugin) and OpenCode / Hermes / any MCP-compatible harness (via the bundled MCP server).


Quickstart

npm install -g leadcraft
leads install

Then restart your AI agent and run:

/icp new           # define your Ideal Customer Profile (interactive)
/find-clients      # discover 25 prospects → data/leads.csv + leads.xlsx
/enrich-lead 1     # find the decision maker, recent signals, email pattern
/write-email 1     # personalized cold-email draft → data/drafts/1-YYYYMMDD.eml

Review the .eml, send it from your own mail client, then log it:

/track-outreach 1 sent
/follow-up 1            # 3 days later — bump on the same thread
/reply-suggest 1        # they replied — classify + draft 2 variants

That's the full loop. Every command above is documented below.


Table of contents


Installation

Option 1 — npm (recommended)

npm install -g leadcraft
leads install

This places the plugin's markdown files at ~/.claude/plugins/leads/ and bootstraps the empty data directory. Restart Claude Code (or your agent) and the 17 slash commands appear.

To install to a custom location:

leads install --target=./my-leads

Option 2 — Manual (git clone)

git clone https://github.com/Lakshya330-sudo/leadcraft.git
cd leadcraft
npm install                 # installs deps + builds the MCP server
node bin/leads.js install   # copies plugin to ~/.claude/plugins/leads/

Option 3 — Symlink for development

git clone https://github.com/Lakshya330-sudo/leadcraft.git
ln -s "$(pwd)/leadcraft" ~/.claude/plugins/leads

Edits to the cloned repo are picked up immediately.


The 7-step workflow

┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│   1. /icp new           Define who you sell to                           │
│           ↓                                                              │
│   2. /find-clients      Discover 25 matching companies                   │
│           ↓                                                              │
│   3. /enrich-lead <id>  Find the decision maker + signals                │
│           ↓                                                              │
│   4. /write-email <id>  Draft personalized cold outreach                 │
│           ↓                                                              │
│   5. (you send the email from your own client — plugin never sends)      │
│           ↓                                                              │
│   6. /track-outreach    Log sent → opened → replied → booked             │
│           ↓                                                              │
│   7. /follow-up         Day-3 bump, day-7 reframe, day-14 break-up       │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

State lives on disk under data/:

  • leads.csv — canonical store, one row per prospect
  • leads.xlsx — auto-regenerated mirror for Excel users
  • outreach.json — append-only event log per lead
  • icps/<slug>.json — saved Ideal Customer Profiles
  • drafts/<id>-<date>.eml — every email draft

Command reference

All 17 commands. Each links to its full markdown body.

Discovery & qualification

CommandWhat it does
/icpDefine, list, or activate an Ideal Customer Profile. Interactive — asks 8 questions and writes data/icps/<slug>.json.
/find-clientsThe headline command. Constructs 6 web-search queries from the active ICP (buying signals + directory + long-tail), parses 25 companies off their own homepages, writes to leads.csv.
/qualify-leadsScore every row's fit_score (0–100) against the active ICP using the 6-component rubric. Re-sorts the spreadsheet by fit.
/enrich-leadDeep-dive on one row: walks /team, /about, /careers, /blog (4-fetch budget), finds the decision maker, infers email pattern, appends buying signals.
/find-decision-makerFocused alternative when /enrich-lead came up short. Tries company pages → wider web search → generates a LinkedIn search URL for manual click-through. Accepts an <id> or a free-text company name.
/research-companyPre-meeting one-pager. Walks 6 pages and produces a markdown brief: what they do, size & stage, recent moves, tech stack, people to know, likely pains, 3 conversation openers. Doesn't touch leads.csv unless you pass --save.

Outreach

CommandWhat it does
/write-emailPersonalized cold-email draft. Three variants: intro (default, 4-part hook→relevance→ask→CTA), value (lead with outcome), casual (peer tone for founder-stage). 120-word body cap, 60-char subject cap, deliverability checklist enforced before save.
/follow-upAuto-picks day-3 / day-7 / break-up based on days-since-last-touch. Day-3 stays on the same thread; day-7 starts a new thread with a different angle; day-14 is the no-guilt-trip break-up. Refuses if the lead has already replied or the sequence is exhausted.
/draft-linkedinLinkedIn DM variant — 300-char hard cap, no signature, mobile-preview-aware (first 80 chars must contain the hook). Generates the LinkedIn search URL for manual sending (plugin never opens LinkedIn).
/reply-suggestPaste an incoming reply. Classifies it into 7 categories (interested-warm, interested-cold, objection, not-now, wrong-person, unsubscribe, auto-reply), drafts two response variants with class-specific tone rules, side-effects status update.

Data operations

CommandWhat it does
/track-outreachLog a status change: sent, opened, replied, booked, lost, nurture. Validates the state-machine transition before writing. Atomic dual-write to outreach.json + leads.csv.
/verify-emailsRegex + DNS MX check. No SMTP probe — too noisy, hurts sender IP reputation. Caches MX results per domain within a run. Writes verdict to notes (email-ok / email-mx-missing / email-syntax-bad).
/dedupe-leadsMerge duplicate rows by domain (default) or email. Survivor chosen by status rank → fit score → most-recent enrichment. Migrates event history from duplicates with a synthetic merge event.
/import-leadsImport an external CSV or XLSX. Auto-detects column mapping (with confirmation prompts for ambiguous ones), normalizes domains, dedupes against existing rows, assigns fresh IDs.
/export-crmExport a CRM-shaped CSV. Three formats: HubSpot (Lifecycle Stage mapping), Pipedrive (Deal Stage), Salesforce (Lead Status, with [Unknown] last-name fallback). Strips ~ from guessed emails for CRM compatibility.

Meta

CommandWhat it does
/lead-statsRead-only pipeline dashboard. ASCII bar-chart funnel, sent→replied / sent→booked rates, median time-to-reply, stalled-leads call-to-action list, top-ICPs leaderboard, data-quality warnings tied to specific remediation commands.
/lead-configView / set plugin defaults — default_n, output format (csv/xlsx/both), source allow/deny list, signature block.

CLI commands (leads ...)

The npm install puts a leads binary on your PATH. Use it for plugin lifecycle, not lead-gen workflow (that's the slash commands).

CommandPurpose
leads installCopy plugin to ~/.claude/plugins/leads/ (override with --target=<path>, force with --force)
leads uninstallRemove the installed plugin (doesn't touch the npm package itself)
leads mcpRun the MCP server over stdio. Configure your MCP client to launch this command.
leads wherePrint the resolved install path
leads doctorDiagnose install state — checks all required files + the MCP server build
leads versionPrint plugin version
leads helpShow this catalogue

How it works

Pure markdown by design

This plugin has no runtime. Slash commands are markdown files; skills (the agent's reference manual) are markdown files; templates (cold-email skeletons) are markdown files. The agent — Claude or any LLM in your harness — reads them and drives the workflow with its native tool calls (WebSearch, WebFetch, Read, Write).

Benefits:

  • Zero install friction for Claude Code users — drop the folder, restart, done.
  • No background processes, no API keys, no SMTP credentials at risk.
  • Source code IS the prompt — when you tweak commands/write-email.md, the next run uses your edits immediately.

The cost: portability beyond Claude Code requires a wrapper. That's what mcp-server/ is.

File layout

leadcraft/
├── .claude-plugin/plugin.json   # manifest
├── CLAUDE.md                    # agent operating guide (data contracts, source policy, status state machine)
├── commands/                    # 17 slash commands
├── skills/                      # 6 reference skills (lead-discovery, email-personalization, outreach-tracking, ...)
├── templates/                   # 7 email/DM templates
├── data/                        # generated at runtime — gitignored
│   ├── leads.csv                # canonical store (source of truth)
│   ├── leads.xlsx               # derived view, auto-regenerated
│   ├── outreach.json            # append-only event log per lead
│   ├── icps/<slug>.json         # saved Ideal Customer Profiles
│   ├── icps/_active.txt         # which ICP is currently active
│   └── drafts/<id>-<date>.eml   # every draft, never sent
├── mcp-server/                  # optional Node MCP wrapper (Phase 7)
├── bin/leads.js                 # the npm CLI
└── package.json                 # npm-installable

Status state machine

Every lead has one status from this set:

new → enriched → drafted → sent ──┬─→ opened
                                  ├─→ replied ──┬─→ booked
                                  │             ├─→ lost
                                  │             └─→ nurture
                                  └─(no reply, time-based)→ (still "sent")

Follow-ups are events, not status changes. A lead at sent who got a day-3 bump is still sent. Full transition table in skills/outreach-tracking/SKILL.md.


Configuration

data/config.json (created on demand by /lead-config):

{
  "default_n":        25,
  "output_format":    "both",
  "source_allowlist": [],
  "source_denylist":  ["upwork.com", "fiverr.com", "linkedin.com"],
  "default_signature": "",
  "max_leads_per_run": 100,
  "follow_up_days":   [3, 7, 14]
}

Edit via /lead-config set <key> <value> or by hand.


Hard rules — what this plugin will never do

These are baked into every command and skill. They're not bugs, they're the contract.

❌Why
Send emails — drafts onlyDrafts give you a review step. Sending requires credentials we don't want to manage.
Scrape LinkedIn / X / FacebookViolates ToS. Where useful, the plugin generates search URLs for you to open manually.
Call paid APIs (Apollo, Clearbit, Hunter, ZoomInfo)The plugin works for free out of the box. Add paid sources later if you want — but not in v1.
Fabricate factsEmpty cells are fine. Made-up contacts, fake fit-notes, hallucinated "buying signals" are not.
SMTP-probe email deliverabilityDamages sender reputation. /verify-emails does syntax + DNS MX only.
Mutate leads.csv non-atomicallyEvery write is temp-file + rename. No partial-state corruption.
Overwrite fit_notes or notesAlways appended with ; separator. History matters.
Skip the deliverability checklist before saving a draftA failing draft is worse than no draft.

MCP integration (OpenCode, Hermes, etc.)

For non-Claude-Code harnesses, run the bundled MCP server:

leads mcp

It exposes:

  • 16 tools — primitives for leads.csv / outreach.json / ICPs / drafts (CRUD)
  • 17 prompts — every slash command, re-exposed by name
  • Read-only resources — every skill, template, and command markdown file under leads://

Add to your MCP client config (example for Claude Desktop / OpenCode):

{
  "mcpServers": {
    "leads": {
      "command": "leads",
      "args": ["mcp"]
    }
  }
}

Full details: mcp-server/README.md.

Architecture note: the MCP server reads and writes the same data/ directory Claude Code does. You can use both surfaces in parallel — they stay in sync via the filesystem.


Troubleshooting

leads install says "Target already exists"

leads uninstall && leads install
# or
leads install --force

leads mcp says "MCP server not built"

If you cloned from git:

npm install   # triggers the workspace build

If you installed from npm and see this, please open an issue — the build should be pre-shipped.

data/leads.xlsx doesn't regenerate

The plugin's pure-markdown side falls back gracefully — leads.csv is canonical and Excel opens CSV directly. To enable xlsx output, the markdown side tries Python+openpyxl or PowerShell ImportExcel. The MCP server uses bundled exceljs and always works.

"No active ICP" errors

Run /icp new to define one, or /icp use <slug> to activate an existing one.

Commands don't appear after leads install

Restart your AI agent. Claude Code reads ~/.claude/plugins/ at startup.


Roadmap

The plugin shipped in 7 phases. All are complete:

PhaseSurfaceStatus
0Plugin skeleton + /icp + data contracts✅
1/find-clients discovery✅
2xlsx generation✅
3/write-email + 3 cold-email variants + 4 follow-up/breakup templates✅
4Enrichment trio: /enrich-lead, /find-decision-maker, /research-company✅
5Tracking & follow-up loop: /track-outreach, /follow-up, /reply-suggest, /draft-linkedin✅
6Quality & data ops: /qualify-leads, /verify-emails, /dedupe-leads, /import-leads, /export-crm, /lead-stats✅
7MCP server for non-Claude harnesses✅

Full design history in CLAUDE.md. Future ideas tracked in GitHub issues.


Contributing

Contributions welcome — especially:

Before submitting:

git clone https://github.com/Lakshya330-sudo/leadcraft.git
cd leadcraft
npm install
node bin/leads.js doctor      # sanity-check

Open a PR against main. No CLA, no formal process — just clear changes and a one-paragraph "why."


License

MIT © Lakshya Rawat

Built with Claude Code. Designed to work everywhere Claude Code doesn't — via MCP.

Ver o original no GitHub

Bom para

Relacionados