# CodeDebut MCP server

Ask your AI assistant what launched today. [CodeDebut](https://codedebut.com) is a daily launch board for new
software: makers launch, people upvote, and the #1 of each day becomes the Debut of the Day. This MCP server lets
Claude, ChatGPT, Cursor, VS Code and any other MCP client search those launches, read product pages, find
alternatives and follow the daily ranking from inside a chat.

- **Endpoint:** `https://codedebut.com/api/mcp` (remote, Streamable HTTP, JSON-RPC 2.0)
- **Auth:** none. No account, no API key, no cookies.
- **Access:** read-only. All 10 tools return public data that is also on codedebut.com.
- **Setup page:** https://codedebut.com/mcp · **Server card:** https://codedebut.com/.well-known/mcp/server-card.json
- **Contact:** hello@codedebut.com

This repository holds the server's public contract: the tool catalogue it returns from `tools/list`
([`tools.json`](tools.json)), the registry manifest ([`server.json`](server.json)) and a small stdio bridge
([`index.js`](index.js)) for clients that can only start local servers. The server itself runs on codedebut.com.

## Connect

**Claude Code**

```sh
claude mcp add --transport http codedebut https://codedebut.com/api/mcp
```

Add `--scope user` to have it in every project.

**Claude.ai and Claude Desktop:** Settings → Connectors → Add custom connector. Name it CodeDebut, paste the
URL and leave the OAuth fields empty.

```
https://codedebut.com/api/mcp
```

**ChatGPT:** Settings → Apps → Advanced settings → turn on Developer mode, then create an app named CodeDebut
with the same URL and no authentication.

**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "codedebut": { "url": "https://codedebut.com/api/mcp" }
  }
}
```

**VS Code** (`.vscode/mcp.json`; the top-level key is `servers`)

```json
{
  "servers": {
    "codedebut": { "type": "http", "url": "https://codedebut.com/api/mcp" }
  }
}
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`)

```json
{
  "mcpServers": {
    "codedebut": { "serverUrl": "https://codedebut.com/api/mcp" }
  }
}
```

**Gemini CLI**

```sh
gemini mcp add --transport http codedebut https://codedebut.com/api/mcp
```

**OpenAI Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.codedebut]
url = "https://codedebut.com/api/mcp"
```

**Clients that only run local (stdio) servers**

```json
{
  "mcpServers": {
    "codedebut": { "command": "npx", "args": ["-y", "mcp-remote", "https://codedebut.com/api/mcp"] }
  }
}
```

Or run the bridge in this repo: `git clone https://github.com/kenil9630/codedebut-mcp && cd codedebut-mcp && npm install`,
then point your client at `node /path/to/codedebut-mcp/index.js`. `docker build -t codedebut-mcp .` builds the
same bridge as an image.

**Check it responds**

```sh
curl -s -X POST https://codedebut.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Tools

Exact schemas and annotations are in [`tools.json`](tools.json). Every tool is annotated `readOnlyHint: true`.

| Tool | What it returns | Arguments |
|---|---|---|
| `search_products` | Launches matching keywords (name, tagline, description, tags, maker) | `query`, optional `category`, `pricing`, `limit` |
| `get_product` | One product's full page: description, website, tags, pricing, platforms, maker, launch history with day ranks and upvotes, latest comments | `slug` (or exact name) |
| `find_alternatives` | Products in the same category, closest first (shared tags, then upvotes) | `product`, optional `limit` |
| `browse_category` | Top products in a category, most upvoted first | `category`, optional `pricing`, `limit` |
| `list_categories` | Categories with product counts and page links | none |
| `get_launches` | Every launch on a day, ranked by upvotes. Today's ranks are live; past days are final | optional `date` (YYYY-MM-DD, UTC) |
| `get_debut_of_the_day` | The #1 launch of a day; the latest finished day by default | optional `date` |
| `get_trending` | Most upvoted launches today, this week or this month | optional `period`, `limit` |
| `list_jobs` | Open jobs on the CodeDebut jobs board | none |
| `get_launch_options` | How to launch on CodeDebut: submit link, next free launch day, plans and prices | none |

Results carry `pageUrl` (the product's page on CodeDebut, to cite as the source) and `website` (the product's own
site). Links to products' sites carry `utm_source=codedebut.com&utm_medium=ai_assistant`, so makers can see the
visits that came from assistants.

**Paid placements are labelled.** Featured products are listed first in `search_products`, `browse_category` and
`find_alternatives` results and carry `"featured": true`. Boosted launches carry `"boosted": true`. Payment never
changes a rank or an upvote count.

## Things to ask

- "What launched on CodeDebut today?"
- "Find me an open-source uptime monitor on CodeDebut."
- "Which product was yesterday's Debut of the Day?"
- "What are the alternatives to this week's top AI launch on CodeDebut?"
- "How do I launch my app on CodeDebut, and what does Featured cost?"

## Limits

120 requests a minute per IP address. Over that, the server answers HTTP 429 with `Retry-After: 60`.
The endpoint is stateless: no sessions, and `GET` returns 405 because there is no server-to-client stream.

## Launch your product

Every product on CodeDebut gets a permanent page, and that page is what assistants find through this server.
[Submit yours](https://codedebut.com/submit), free, or see [Featured and Launch Day Boost](https://codedebut.com/pricing).

## Development

```sh
npm install
npm test        # starts the bridge over stdio and calls two tools on the live server
```

Set `CODEDEBUT_MCP_URL` to point the bridge at another endpoint, e.g. a local copy of the site.

## License

[MIT](LICENSE)