# MCP1

A minimal [Model Context Protocol](https://modelcontextprotocol.io/) server named **MCP1** with one skill: **Tell Joke**.

Supports **local stdio** (Cursor subprocess) and **Streamable HTTP** (web deployment).

## Skill: Tell Joke

When invoked, the agent leads an interactive knock-knock joke suitable for a 6-year-old — starting with "Knock knock!" and waiting for the user to play along.

## Tools

| Tool | Description |
|------|-------------|
| `tell_joke` | Invoke the Tell Joke skill and begin a knock-knock joke |
| `list_skills` | List available skills |
| `get_skill` | Load a skill's full `SKILL.md` by id (e.g. `tell-joke`) |

## Local development (stdio)

```bash
node src/index.mjs
```

Or explicitly:

```bash
MCP_TRANSPORT=stdio node src/index.mjs
```

Project config: `.cursor/mcp.json`

## Web deployment (HTTP)

Start the HTTP server locally:

```bash
MCP_TRANSPORT=http PORT=3000 node src/index.mjs
```

Endpoints:

| Path | Method | Purpose |
|------|--------|---------|
| `/mcp` | POST | MCP Streamable HTTP endpoint |
| `/health` | GET | Health check for load balancers |
| `/` | GET | Server info |

### Docker

```bash
docker build -t mcp1 .
docker run -p 3000:3000 mcp1
```

Or with Docker Compose:

```bash
docker compose up --build
```

### Deploy to Render

1. Push this repo to GitHub.
2. Create a new **Web Service** on [Render](https://render.com).
3. Point it at this repo — `render.yaml` is included.
4. After deploy, your MCP URL will be `https://<your-service>.onrender.com/mcp`.

### Optional API key

Set `MCP_API_KEY` to require authentication:

```bash
MCP_API_KEY=my-secret-key MCP_TRANSPORT=http node src/index.mjs
```

Clients must send either:

- `Authorization: Bearer my-secret-key`, or
- `X-API-Key: my-secret-key`

## Connect Cursor to the deployed server

Copy `.cursor/mcp.remote.example.json` into your Cursor MCP config and set your URL:

```json
{
  "mcpServers": {
    "MCP1": {
      "url": "https://your-mcp1-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MCP_API_KEY}"
      }
    }
  }
}
```

Use either:

- **Project config:** `.cursor/mcp.json` in this repo
- **Global config:** `~/.cursor/mcp.json`

Then enable **MCP1** in **Cursor Settings → MCP**.

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
| `PORT` | `3000` | HTTP listen port |
| `HOST` | `0.0.0.0` | HTTP bind address |
| `MCP_PATH` | `/mcp` | MCP endpoint path |
| `MCP_API_KEY` | _(none)_ | Optional bearer/API key |

## Project layout

```
MCP1/
├── .cursor/
│   ├── mcp.json
│   └── mcp.remote.example.json
├── skills/tell-joke/SKILL.md
├── src/
│   ├── core.mjs
│   ├── http.mjs
│   ├── stdio.mjs
│   └── index.mjs
├── Dockerfile
├── docker-compose.yml
├── render.yaml
└── package.json
```