Skip to main content
Glama
raised-hand

raised-hand

Raised Hand Lite

A working, dependency-free prototype of raisedhand.ai — the "find people who are publicly asking for what you sell" pipeline — including a real OAuth 2.1 MCP server so Claude Code or Codex can ask for your leads.

What this is. A reverse-engineering study plus a reimplementation of the architecture and the contract, not of the LinkedIn scraping. See docs/HOW-IT-WORKS.md for the teardown of the real product: stack, endpoints, tool surface, and the business model read from the client bundles.

npm start          # http://localhost:4321  (no install step, no dependencies)
npm test           # 32 tests, node:test
node scripts/smoke.mjs   # proves the OAuth → MCP handshake end to end

Live demo: https://raisedhand-lite.vercel.app — press Find leads now. It runs on a serverless host with an in-memory store, so the demo data resets when the instance goes cold. Run it locally if you want state to persist.

Live view

Lead detail

Outreach, waiting for approval


The idea in one paragraph

Paste a website. It derives what you sell and who buys it. Every day it reads the places your buyers talk, finds the ones who said "we missed 23 calls last week", scores them against your ideal customer, finds an email and phone, and hands you the post plus a drafted message. Nothing sends without your OK, and a reply stops the sequence immediately.

The product is not a list. It is evidence + intent, with the reason attached to every lead.

Related MCP server: FullEnrich MCP

What actually works here

Piece

Status

Ideal customer definition + scorer with per-point reasons

✅ deterministic, tested

Signal ingestion (posted, commented, liked, engaged_competitor, watchlist, new_in_role)

✅ demo generator + POST /api/signals webhook

De-dupe: one person, many signals → one lead with a timeline

✅

Negative list: students, recruiters, other agencies never reach you

✅

Daily run with hour, lead cap, minimum fit, credits

✅

Contact lookup with "verified" flags, never invented

✅ pluggable provider

Outreach sequences: invite → message → follow-up

✅

Human approval gate on every message

✅

Stop on reply

✅

Daily invite cap (10/account)

✅

Remote MCP server with OAuth 2.1 + DCR + PKCE

✅ 12 tools

Agent skill (SKILL.md) teaching safe tool use

✅

Dashboard: live, leads, lead detail, outreach, settings

✅

Actual LinkedIn scraping

❌ deliberately out of scope

The LinkedIn side is intentionally not implemented: it is the part that needs accounts, proxies, rate-limit handling, and a ToS decision. Everything downstream of "a signal exists" is real and runs.

Try the MCP server

claude mcp add --transport http raised-hand http://localhost:4321/mcp

Then /mcp → raised-hand → Authenticate → Allow.

> who came in today?

The agent calls list_leads for today, ranks by icp_fit, and shows the evidence. If it tries to run a search it first tells you what it costs and needs your yes — that behaviour comes from the tool contract, not from good manners:

// tools/call find_leads_now without confirm
"This search would cost 3 credits and produce up to 3 lead(s)... call again with confirm: true."

Twelve tools, same names as the real product:

get_workspace        get_ideal_customer   list_leads        get_lead
rate_lead            set_lead_outcome     list_watchlist    watchlist_add
find_leads_now       check_linkedin_post  look_up_contact   list_suggestions

The OAuth flow, by hand

No SDK, no magic. This is the same sequence any MCP client performs:

# 1. discover
curl -s localhost:4321/.well-known/oauth-authorization-server | jq
# 2. self-register (RFC 7591) — public client, no secret
curl -s -X POST localhost:4321/oauth/register -H 'content-type: application/json' \
  -d '{"client_name":"probe","redirect_uris":["http://127.0.0.1:8765/callback"]}' | jq
# 3. authorize with S256 PKCE, 4. exchange the code, 5. POST /mcp with the bearer
node scripts/smoke.mjs

Unauthenticated calls get the correct challenge:

HTTP/2 401
www-authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp", scope="raisedhand"

Architecture

                    ┌──────────────────────────────┐
  website / ICP ───▶ │  workspace.icp               │
                    └──────────────┬───────────────┘
                                   │
   signals (webhook / demo) ───────┼──▶ group by person ──▶ dedupe ──▶ score
                                   │                                   │
                                   │                          negative list (hard stop)
                                   │                                   │
                                   ▼                                   ▼
                          daily run: hour, cap, min fit, credits ──▶ enrich
                                                                       │
                                                                       ▼
                              leads (evidence + reasons + contacts) ────┤
                                                                       │
                     ┌─────────────────────────────────────────────────┘
                     ▼
   outreach: invite ─▶ message ─▶ follow-up        reply ─▶ stop everything
                     │
                     └─ every message waits in "Ready to send"

   MCP ──▶ same store, read + annotate + draft only, never send

Code map:

src/store.js      atomic JSON store (swap for Convex/Postgres)
src/scoring.js    the whole product: ICP → 0-99 + reasons
src/daily.js      preview (free) vs run (spends), credits, dedupe
src/outreach.js   sequences, approval gate, reply stop, invite cap
src/enrich.js     provider interface, never invents
src/oauth.js      metadata, DCR, PKCE, tokens
src/mcp.js        JSON-RPC, 12 tools, tool contract
src/server.js     router, static UI, API, /mcp
src/cli.js        the same thing in a terminal

Design decisions worth arguing about

Ranking is separate from eligibility. A score is a sort key; eligibility is a gate (fit >= 60 && target title hit). Engagement alone can produce a 62 and still not reach you. The real product says the same thing: "a post counts most, then a comment, then a like."

Preview and run are two functions. previewRun() is free, runDaily() spends. find_leads_now uses the preview to quote a price before asking for confirmation. Cost transparency is a product feature, not a guardrail.

Every point has a sentence. reasons[] is what makes a lead trustworthy, and what lets "mark as not a fit" actually teach the next run.

The agent cannot send. The MCP surface is read + annotate + draft. This is the safety property that makes giving an LLM access to your pipeline reasonable at all.

Lead text is data, not instructions. The shipped SKILL.md says so explicitly, and the MCP server never executes anything from a lead. This prototype shipped that rule because the real one does — it is a good idea.

API (for the dashboard and for webhooks)

GET  /api/state                       everything the UI needs
POST /api/run                         run the daily search
POST /api/preview                     what a run would do, free
POST /api/signals                     ingest 1..n signals   ← point your scraper here
POST /api/sequences                   draft outreach for leadIds
POST /api/messages/:id/approve        the human gate
POST /api/send                        send approved + due
POST /api/leads/:id/rate              good | bad | not_a_fit
POST /api/leads/:id/outcome           responded | interested | booked | converted...
POST /api/leads/:id/replied           stop the sequence
GET  /api/score?title=Owner&...       scoring playground

Ingest example:

curl -X POST localhost:4321/api/signals -H 'content-type: application/json' -d '{
  "kind": "posted",
  "person": {"name":"Dana Whitlock","title":"Founder","company":"Whitlock Dental Studio",
             "companySize":19,"industry":"Dental clinics","geo":"United States",
             "url":"https://www.linkedin.com/in/dana"},
  "text": "We missed 23 calls last week. How are other practices handling this?",
  "url": "https://www.linkedin.com/posts/..."
}'

Data

data/db.json, created on first run. npm run reset reseeds the demo workspace. Set RH_DATA_DIR to move it.

Tests

32 tests covering the parts that are easy to get subtly wrong: the negative list must be a hard stop, COO must not match inside Coordinator, a stale lead must score lower than a fresh one, the second run must not duplicate anyone, a reply must stop everything, PKCE must be enforced, a code must be single-use, and a spending tool must refuse without confirm: true.

Deploy

Single Node process, no build step, no dependencies:

vercel deploy --prod      # this repo is already wired for it (vercel.json)

RH_MEMORY=1 puts the store in memory (VERCEL=1 does the same). Any host with a persistent disk can keep the JSON store by leaving both unset and pointing RH_DATA_DIR at a volume.

This is an independent study for learning and prototyping. It is not affiliated with Raised Hand. The report only uses public, unauthenticated information (HTTP headers, .well-known documents, the marketing site, and client bundles). No account was accessed, nothing was bypassed, and no scraping of LinkedIn is included. If you build the ingestion side, you own the ToS and privacy questions that come with it.

MIT licensed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for AI-native LinkedIn prospecting. It enables lead research, audience building, conversation management, and controlled outreach actions such as messaging and publishing through an OAuth-protected remote endpoint.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search B2B people and companies, enrich contacts with verified emails and mobile phone numbers via waterfall enrichment across 25+ providers, and export results as CSV or JSON. Supports prospecting, org mapping, candidate sourcing, and outreach workflows through OAuth-authenticated remote access from any MCP-compatible client.
      14
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and MCP clients to query and inspect CRM records and create records with workspace attribute values through a single PipMCP API key, with hosted tool discovery and governed execution.
      1,923 npm
      MIT