# mcp-demo-server

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server built with
TypeScript and the official `@modelcontextprotocol/sdk`. It exposes a set of tools an LLM
client (Claude Desktop, Claude Code, or any other MCP-compatible client) can call: a
SQLite-backed task manager, a calculator, and a tool that reports the server's own metadata.

## What is MCP?

Model Context Protocol is an open protocol that standardizes how applications provide context
and capabilities (tools, resources, prompts) to LLMs. An MCP **server** exposes a set of
**tools** with typed input schemas; an MCP **client** (like Claude Desktop or Claude Code)
discovers those tools and lets the model call them, receiving structured results back.
Communication typically happens over stdio (a local subprocess) or HTTP.

This project focuses on the tools side of the protocol: input validation, error handling, and
testable business logic decoupled from the transport layer.

## Stack

- Node.js + TypeScript (strict mode)
- `@modelcontextprotocol/sdk` (official TypeScript SDK)
- `zod` for input schema validation
- `better-sqlite3` for persistence
- `vitest` for unit tests
- ESLint + Prettier

## Project structure

```
src/
  server.ts          # MCP server bootstrap (stdio transport, tool registration)
  db.ts              # SQLite connection + schema
  tools/
    tasks.ts          # task CRUD business logic
    calculator.ts      # arithmetic operations
    serverInfo.ts       # server metadata
  types/
    task.ts            # Task type + zod schemas
  lib/
    result.ts           # Result<T> type used for standardized success/error returns
tests/
  tasks.test.ts
  calculator.test.ts
  serverInfo.test.ts
```

Each tool's logic lives in a plain function that takes a database/context and typed input and
returns a `Result<T>` (`{ ok: true, data }` or `{ ok: false, error }`). `server.ts` is the only
file that talks to the MCP SDK — it wires those functions to `registerTool`, so the logic can be
unit tested without spinning up a server or a transport.

## Running locally

```bash
npm install
npm run build
npm start        # runs the compiled server over stdio
```

For development without a build step:

```bash
npm run dev       # runs src/server.ts directly via tsx
```

The server communicates over stdio, so running it directly in a terminal will just sit there
waiting for JSON-RPC messages on stdin — that's expected. It's meant to be launched by an MCP
client, not run interactively.

## Testing with Claude Code

Add the server to Claude Code's MCP config, pointing at the built entrypoint:

```bash
claude mcp add mcp-demo-server -- node /absolute/path/to/mcp-demo-server/dist/server.js
```

Or, for a project-scoped config, add to `.mcp.json`:

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

Then ask Claude to use the tools, e.g. "create a task called 'write the report'" or "what's
23 * 47?". Any other MCP client (Claude Desktop, MCP Inspector, etc.) can connect the same way
via stdio.

## Running the test suite

```bash
npm test          # run once
npm run test:watch
npm run lint
npm run format:check
```

## Tools

### `task_create`

Creates a new task.

**Input**

```json
{ "title": "Write the report", "description": "Q3 summary" }
```

**Output**

```json
{
  "id": 1,
  "title": "Write the report",
  "description": "Q3 summary",
  "status": "pending",
  "createdAt": "2026-01-15 10:00:00",
  "updatedAt": "2026-01-15 10:00:00"
}
```

### `task_list`

Lists tasks, optionally filtered by status (`pending`, `in_progress`, `done`).

**Input**

```json
{ "status": "pending" }
```

**Output**: array of task objects (same shape as `task_create`).

### `task_get`

Fetches a single task by id.

**Input**

```json
{ "id": 1 }
```

**Output**: a task object, or an error result if the id doesn't exist.

### `task_update`

Updates one or more fields of an existing task. Omitted fields are left unchanged.

**Input**

```json
{ "id": 1, "status": "done" }
```

**Output**: the updated task object.

### `task_delete`

Deletes a task by id.

**Input**

```json
{ "id": 1 }
```

**Output**

```json
{ "id": 1 }
```

### `calculate`

Performs a basic arithmetic operation (`add`, `subtract`, `multiply`, `divide`) on two numbers.

**Input**

```json
{ "operation": "divide", "a": 10, "b": 2 }
```

**Output**

```json
5
```

Dividing by zero returns an error result instead of throwing:

```json
{ "isError": true, "content": [{ "type": "text", "text": "Division by zero is not allowed" }] }
```

### `server_info`

Returns metadata about the running server: name, version, Node.js version, uptime in seconds,
and the list of available tools. Takes no input.

**Output**

```json
{
  "name": "mcp-demo-server",
  "version": "1.0.0",
  "nodeVersion": "v22.14.0",
  "uptimeSeconds": 42,
  "tools": ["task_create", "task_list", "task_get", "task_update", "task_delete", "calculate", "server_info"]
}
```

## Error handling

Every tool validates its input against a zod schema before running any logic (the MCP SDK
rejects malformed input automatically based on the registered schema). Business-level failures
(task not found, division by zero) are returned as `Result` error values rather than thrown
exceptions, and are surfaced to the client as `isError: true` tool results — never as an
unhandled exception that crashes the server process.

## License

MIT