## mcp-tripleshot-http

A clean, Streamable HTTP MCP server (no stdio) that fronts `api.tripleshot.ai` so Claude/Cursor can search prompts and "prompt itself." Built with the MCP SDK’s `StreamableHTTPServerTransport`, handling both SSE (GET) and JSON-RPC (POST).

### What you get (tools)

- **list_communities()**: Return communities from `/api/public/communities`.
- **search_prompts(q, community?, limit?, offset?)**: Search `/api/public/prompts/search`.
- **get_prompt(id)**: Get prompt by ID via `/api/public/prompts/:id`.
- **trending_prompts(community?, limit?)**: Trending via `/api/public/prompts/trending`.
- **featured_prompts(limit?)**: Featured via `/api/public/prompts/featured`.
- **render_prompt(id, variables={})**: Fetches a prompt and fills `{{placeholders}}` in its body.

### Project setup

Requirements: Node 18+.

```bash
git clone <this repo>
cd mcp-tripleshot-http
npm ci
```

`package.json` scripts:

```json
{
  "scripts": {
    "dev": "tsx src/server.ts",
    "build": "tsc -p .",
    "start": "node --enable-source-maps dist/server.js"
  }
}
```

Optional `.env` (create at repo root):

```bash
TRIPLESHOT_BASE=https://api.tripleshot.ai
HTTP_TIMEOUT_MS=15000
PORT=8787
BIND=127.0.0.1
# If you publish this, add a shared secret
MCP_TOKEN=replace-me
```

### Server (Streamable HTTP)

The HTTP endpoint is exposed at `/mcp` using `StreamableHTTPServerTransport`.

- GET `/mcp`: Server-Sent Events stream (keepalive)
- POST `/mcp`: JSON-RPC 2.0 requests

There’s also a health check at `GET /` that returns `{ ok: true, mcp: "/mcp" }`.

### Build & run

```bash
npm run dev
# or
npm run build && npm run start
```

### Smoke tests (local)

```bash
curl http://127.0.0.1:8787/
curl -N -H "Accept:text/event-stream" http://127.0.0.1:8787/mcp
```

If you set `MCP_TOKEN`, include the header:

```bash
curl -H "Authorization: Bearer replace-me" http://127.0.0.1:8787/
```

### Connect clients

#### Cursor (local)

First start the server:
```bash
npm run dev
```

Then add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tripleshot-http": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}
```

With token:

```json
{
  "mcpServers": {
    "tripleshot": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer replace-me" }
    }
  }
}
```

#### Claude Desktop

Claude Desktop requires using `mcp-remote` as a bridge to connect to HTTP-based MCP servers.

Add to your Claude Desktop configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Basic configuration:

```json
{
  "mcpServers": {
    "tripleshot-http": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8787/mcp"
      ]
    }
  }
}
```

With authentication token:

```json
{
  "mcpServers": {
    "tripleshot-http": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8787/mcp",
        "--header",
        "Authorization: Bearer ${MCP_TOKEN}"
      ],
      "env": {
        "MCP_TOKEN": "your-token-here"
      }
    }
  }
}
```

After updating the configuration, restart Claude Desktop to apply changes. The tools will appear automatically in the UI.

### Example model flow

Discover:

```json
{ "tool": "search_prompts", "args": { "q": "next.js auth", "limit": 5 } }
```

Inspect:

```json
{ "tool": "get_prompt", "args": { "id": 82 } }
```

Render / prompt itself:

```json
{
  "tool": "render_prompt",
  "args": { "id": 82, "variables": { "projectName": "Acme", "provider": "Clerk" } }
}
```

Use the rendered text as the next system/assistant message.

### Deploy notes

- Any Node host works (Vercel/Render/Fly/Cloud Run). Ensure keep‑alive for SSE `GET /mcp`.
- If public, set `MCP_TOKEN` and restrict inbound origins/IPs at the proxy.
- If you later add write ops, create a separate admin MCP server.

### License

MIT