mcp-demo-server

A small Model Context Protocol (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

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

For development without a build step:

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:

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:

{
  "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

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

Tools

task_create

Creates a new task.

Input

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

Output

{
  "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

{ "status": "pending" }

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

task_get

Fetches a single task by id.

Input

{ "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

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

Output: the updated task object.

task_delete

Deletes a task by id.

Input

{ "id": 1 }

Output

{ "id": 1 }

calculate

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

Input

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

Output

5

Dividing by zero returns an error result instead of throwing:

{ "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

{
  "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