# Forency — Website Technology Forensics

Detect the technology stack behind any website: CMS, ecommerce, JavaScript frameworks, analytics, CRM, marketing automation, payments, chat, CDN, and hosting. Built for AI agents first (MCP server), humans second (REST API + playground).

- **Live:** [forency.io](https://forency.io)
- **Docs:** [forency.io/docs](https://forency.io/docs)
- **MCP server:** [`forency-mcp`](packages/mcp) on npm

## Why

BuiltWith's API starts at $295/mo, Wappalyzer's at $250/mo, and neither ships an MCP server. Forency covers the ~100 technologies that actually drive prospecting and competitive research, starts free, and tops out at $49/mo.

## Stack

| Layer | Choice |
|-------|--------|
| App | Next.js 16 (App Router, TypeScript, Tailwind 4) on Vercel |
| Detection | In-house engine over a curated fingerprint set derived from [webappanalyzer](https://github.com/enthec/webappanalyzer) (GPL-3.0) |
| Database | Postgres (Neon) via Prisma 7 |
| Auth | Auth.js v5 — GitHub + Google |
| Billing | Stripe Checkout subscriptions + webhook |
| MCP | `packages/mcp` — TypeScript, stdio, published to npm |

## Layout

```
app/
  page.tsx              landing + free playground
  pricing/ docs/ dashboard/
  api/
    v1/lookup   POST {url}   → metered, Bearer key
    v1/batch    POST {urls}  → up to 25 URLs
    scan        playground (no key, 3/day per IP)
    key         issue/rotate a user's API key
    stripe/     checkout · portal · webhook
    auth/       Auth.js handlers
lib/
  engine/       detect.ts · curated-list.ts · custom-patterns.ts · fingerprints.json
  api-auth.ts   key auth + atomic monthly metering
  plans.ts keys.ts prisma.ts stripe.ts
packages/mcp/   the published MCP server
scripts/
  build-fingerprints.ts   regenerate fingerprints.json from upstream
  eval-engine.ts          detection accuracy harness (25 known sites)
  test-funnel.ts          end-to-end: key → free tier → 429 → upgrade
  test-mcp.ts             drives the MCP server over stdio
```

## Local development

```bash
npm install
cp .env.example .env          # fill in the values

# local Postgres
docker run -d --name forency-pg \
  -e POSTGRES_USER=forency -e POSTGRES_PASSWORD=forency -e POSTGRES_DB=forency \
  -p 5433:5432 postgres:16-alpine

npx prisma migrate dev
npm run dev
```

## Verification

```bash
npx tsx scripts/eval-engine.ts              # detection accuracy (25/25 expected)
npx tsx scripts/eval-engine.ts example.com  # scan one site, full JSON

# with the dev server running:
npx tsx scripts/test-funnel.ts              # billing funnel end to end
cd packages/mcp && npm run build && cd ../..
npx tsx scripts/test-mcp.ts                 # MCP server over stdio
```

## Refreshing detection

`lib/engine/fingerprints.json` is a vendored snapshot. To pull upstream changes or add technologies, edit `lib/engine/curated-list.ts` and run:

```bash
npx tsx scripts/build-fingerprints.ts
```

The script fails loudly if a curated name doesn't exist upstream and suggests near matches. Tier-1 technologies that upstream detects poorly get overlays in `lib/engine/custom-patterns.ts`.

## License

Application code: MIT. Detection patterns derive from [webappanalyzer](https://github.com/enthec/webappanalyzer) (GPL-3.0) and are used server-side; they are not redistributed in the npm package.