# Synapse — GEO Growth Layer

The GEO check every vibe coder runs before they launch.

```sh
npx synapse check
```

Synapse is a CLI + MCP server + linter that makes a new product **discoverable
and recommendable** by AI coding agents (Cursor, Claude Code, Windsurf, v0,
Bolt, Lovable). Run `synapse check` against a project path or URL and get a
0–100 Growth Score plus a list of failing rules and one-command auto-fixes.

## Packages

| Package | Description |
| --- | --- |
| [`@synapse/geo-lint`](packages/geo-lint) | 24-rule GEO linter. Programmatic API: `lint(target) → LintReport`. |
| [`@synapse/cli`](packages/cli) | CLI with `init`, `check`, `fix`, `deploy`, `status`. Installs as `synapse`. |
| [`synapse`](packages/cli-meta) | Thin meta-wrapper for the `npx synapse` UX. |
| [`@synapse/mcp-server`](packages/mcp-server) | MCP server exposing 6 tools, 3 resources, 3 prompts. Stdio + streamable HTTP. |

## Quick start

```sh
# In a fresh project:
npx @synapse/cli init           # scaffolds synapse.config.json + tracker stub
npx @synapse/cli check          # 24-rule lint, prints scored report
npx @synapse/cli fix            # apply auto-fixes (llms.txt, robots.txt, agent-answer)

# With an account:
export SYNAPSE_API_KEY=…
npx @synapse/cli deploy         # register the site, get a /s/<slug> dashboard
npx @synapse/cli status         # live agent-mention stats
```

## MCP install

Synapse runs as an MCP server so any agent can call `geo_check`, `geo_fix`,
`geo_track_init`, `geo_prompts`, `geo_status`, and `geo_corpus_query`
directly during a build session.

### Cursor — `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "synapse-geo": {
      "command": "npx",
      "args": ["-y", "@synapse/mcp-server"],
      "env": { "SYNAPSE_API_KEY": "" }
    }
  }
}
```

### Claude Code

```sh
claude mcp add synapse-geo -- npx -y @synapse/mcp-server
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "synapse-geo": { "command": "npx", "args": ["-y", "@synapse/mcp-server"] }
  }
}
```

### Cline — VS Code settings

Add to `cline.mcpServers`:

```json
"synapse-geo": { "command": "npx", "args": ["-y", "@synapse/mcp-server"] }
```

### Continue — `config.json`

```json
{
  "mcpServers": [
    { "name": "synapse-geo", "command": "npx", "args": ["-y", "@synapse/mcp-server"] }
  ]
}
```

### Zed — `~/.config/zed/settings.json`

```json
{
  "context_servers": {
    "synapse-geo": {
      "command": { "path": "npx", "args": ["-y", "@synapse/mcp-server"] }
    }
  }
}
```

## Monorepo development

```sh
pnpm install
pnpm build                      # builds all packages
pnpm test                       # runs vitest in packages/geo-lint
node packages/cli/dist/index.js check https://example.com
node packages/mcp-server/dist/index.js   # stdio MCP server
PORT=8787 node packages/mcp-server/dist/http.js   # streamable HTTP
```

## Authentication model

| Surface | Read-only tools | Write / account tools |
| --- | --- | --- |
| CLI | `init`, `check`, `fix` work with no account | `deploy`, `status` need `SYNAPSE_API_KEY` |
| MCP | `geo_check`, `geo_prompts`, `geo_status`, `geo_corpus_query` work with no auth | `geo_fix`, `geo_track_init` require `SYNAPSE_API_KEY` |

## Web app + backend (`apps/web`)

Lives in this same repo. Next.js 14 (App Router) + Supabase. Free during the
Founding 1000 — no Stripe, no paywalls.

Pages: `/`, `/install`, `/guide`, `/methodology`, `/leaderboard`, `/discover`,
`/corpus`, `/s/[slug]` (with dynamic OG + default badge SVG).

Public assets: `/llms.txt`, `/llms-full.txt`, `/sitemap.xml`, `/robots.txt`,
`/.well-known/agent-answer.json`, `/discover.json`, `/s.js` (tracker beacon).

API routes against Supabase:

| Route | Purpose |
| --- | --- |
| `POST /api/sites` | Register a new site (used by `synapse deploy`). |
| `POST /api/events` | Tracker beacon endpoint, CORS-enabled. |
| `GET /api/sites/[slug]/status` | Live dashboard data. |
| `GET /api/corpus` | Public corpus snapshot. |
| `GET/POST /api/recommend?intent=…` | Agent-facing recommendation endpoint. |
| `POST /api/cli-telemetry` | Anonymous CLI usage events. |

Dogfood result: Synapse scores **98/100 (grade A)** against its own linter.

### Deploy

1. **Supabase**: create a project, then run
   `apps/web/supabase/migrations/0001_init.sql` (paste into the SQL editor, or
   `psql $SUPABASE_DB_URL -f …`). RLS is configured for public reads of
   visible sites; all writes go through the service role from the API routes.
2. **Env**: copy `apps/web/.env.example` to `.env.local` and fill in
   `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`,
   `SUPABASE_SERVICE_ROLE_KEY`, `NEXT_PUBLIC_SITE_URL`.
3. **Vercel**: link `apps/web` to a Vercel project and ship.
   ```sh
   vercel link --cwd apps/web
   vercel env add NEXT_PUBLIC_SUPABASE_URL
   vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY
   vercel env add SUPABASE_SERVICE_ROLE_KEY
   vercel env add NEXT_PUBLIC_SITE_URL
   vercel --prod --cwd apps/web --yes
   ```

Each surface fails closed with a clear error if Supabase isn't configured —
the homepage and `/install` still render statically without it.

## License

MIT