# contactapi

An open-source API to save contacts. Send a `POST` with an email and any other
JSON fields you want, and they get saved as-is. Manage them with simple CRUD.

Built with [Hono](https://hono.dev) and deployed on [Vercel](https://vercel.com).

- **Landing page & docs** — [`/`](src/pages/home.ts)
- **Log in** — [`/login`](src/pages/login.ts)
- **Sign up** — [`/signup`](src/pages/signup.ts)
- **LLM-friendly docs** — [`/llms.txt`](src/content/llms.ts)

## API overview

The base URL is `https://contactapi.dev` and every request carries your API key
as a Bearer token:

```
Authorization: Bearer YOUR_KEY
```

| Method   | Path                | Key                   | Description                          |
| -------- | ------------------- | --------------------- | ------------------------------------ |
| `POST`   | `/v1/contacts`      | secret or publishable | Create (or upsert) a contact by email |
| `GET`    | `/v1/contacts`      | secret                | List contacts, paginated              |
| `GET`    | `/v1/contacts/:id`  | secret                | Fetch a single contact                |
| `PATCH`  | `/v1/contacts/:id`  | secret                | Update a contact                      |
| `DELETE` | `/v1/contacts/:id`  | secret                | Delete a contact                      |

Contacts are keyed by email — creating one whose email already exists updates it
in place rather than duplicating it. Full reference lives on the landing page and
in [`/llms.txt`](src/content/llms.ts).

There are two kinds of key:

- `ck_secret_…` — secret key, for your backend. Full access to every endpoint.
- `ck_pub_…` — publishable key, for the browser. Can only create contacts and is
  locked to your domains.

## MCP server

AI clients (Claude Desktop, claude.ai custom connectors, Cursor, the MCP
Inspector) can manage your contacts through an [MCP](https://modelcontextprotocol.io)
server at:

```
https://contactapi.dev/mcp
```

Auth is **OAuth 2.1 with dynamic client registration** — point a client at the
URL and it discovers the authorization server, registers itself, and sends you to
log in and approve access; no API key to copy. The server exposes five tools that
mirror the REST API: `list_contacts`, `get_contact`, `create_contact`
(upsert-by-email), `update_contact`, and `delete_contact`. Everything is scoped to
the account you log in as.

The OAuth provider is [Better Auth](https://better-auth.com)'s `mcp` plugin
([`src/auth.ts`](src/auth.ts)); the tools and endpoint wiring live in
[`src/mcp/server.ts`](src/mcp/server.ts) and [`src/index.ts`](src/index.ts).

## Development

Prerequisites: [Vercel CLI](https://vercel.com/docs/cli) installed globally.

```bash
npm install
vc dev
open http://localhost:3000
```

## Build

```bash
npm install
vc build
```

## Deploy

```bash
npm install
vc deploy
```

## License

[MIT](LICENSE.md)