# hello-world

A minimal MCP server you can deploy to [Volken](https://volken.dev) in about five
minutes. It exposes three trivial tools so you can see the whole loop end to end:
deploy from GitHub, connect an AI client, watch the calls land.

| Tool | Does |
|---|---|
| `echo` | Returns the message you send it |
| `add` | Adds two numbers |
| `current_time` | Returns the current time as ISO 8601 |

The server speaks the MCP Streamable HTTP transport at the root path and listens on
the port Volken provides in `PORT` (it falls back to `8080` locally).

## Deploy it

You need Node.js 20+, a GitHub account, and an AI client (Claude Desktop, Claude
Code, or Cursor).

1. **Make it yours.** Click **Use this template** (or fork), then clone your copy.

2. **Install the CLI and sign in:**

   ```bash
   npm install -g volken
   volken login
   ```

3. **Initialise and deploy:**

   ```bash
   volken init
   volken deploy
   ```

   `volken init` detects the runtime and writes your `volken.toml`. `volken deploy`
   builds from your repository and prints your endpoint and a gateway token.

4. **Connect an AI client:**

   ```bash
   volken connect --install --token <your-token>
   ```

   Restart the client, then ask it to "add 2 and 3" or "what time is it".

5. **Watch the calls:**

   ```bash
   volken calls --tail
   ```

## Run it locally

```bash
volken dev
```

This runs the server in the MCP Inspector so you can call the tools from a browser
before you deploy.

## Add your own tool

Each tool is a `server.registerTool(name, config, handler)` call in
[`src/index.ts`](src/index.ts). Copy one, give it a name, an input schema, and a
handler, then redeploy.

## Learn more

- Volken docs: https://docs.volken.dev
- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk