# mcp-server

A starter [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, built with the official TypeScript SDK.

It ships with two example tools:

- `echo` — echoes a message back to the caller (useful for testing connectivity)
- `get_time` — returns the current date/time, optionally in a given IANA timezone

Use these as templates, then add your own tools in `src/index.ts`.

## Getting started

```bash
npm install
npm run build
npm start
```

The server communicates over stdio, so it's meant to be launched by an MCP client (e.g. Claude Desktop, Claude Code) rather than run standalone.

## Development

```bash
npm run dev   # watch mode, recompiles on change
```

Test interactively with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npm run build
npm run inspector
```

## Connecting to an MCP client

Add an entry pointing at the built server, e.g. for Claude Desktop's `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"]
    }
  }
}
```

### Registering with the Claude Code CLI

You can also register this server (or any third-party MCP server) with the `claude mcp add` command instead of editing a client's config file by hand:

```bash
# This project, at user scope (available in every project on your machine)
claude mcp add mcp-server -s user -- node /absolute/path/to/mcp-server/build/index.js
```

The same pattern works for other MCP servers distributed via npm. A couple of examples:

[Perplexity's MCP server](https://github.com/perplexity-ai/mcp-server) (requires an API key):

```bash
claude mcp add perplexity -s user --env PERPLEXITY_API_KEY="your-api-key" -- npx -y @perplexity-ai/mcp-server
```

[Playwright's MCP server](https://github.com/microsoft/playwright-mcp) (browser automation, no API key needed):

```bash
claude mcp add playwright -s user -- npx -y @playwright/mcp@latest
```

- `-s user` registers the server at user scope (all projects); use `-s project` to scope it to the current repo instead.
- `--env KEY=value` passes environment variables (e.g. API keys) to the server process.
- Everything after `--` is the command used to launch the server.
- Replace `"your-api-key"` with a real key from the provider's dashboard — a placeholder value will cause auth failures.

## Project structure

```
src/
  index.ts     # server entry point: tool definitions + handlers
build/         # compiled output (generated, gitignored)
```

## Adding a new tool

1. Add its JSON schema to the `TOOLS` array in `src/index.ts`.
2. Handle it in the `CallToolRequestSchema` switch statement.
3. Validate its arguments with a [zod](https://zod.dev) schema, as the examples do.
4. Rebuild (`npm run build`) and reconnect your MCP client.