mcp-server-starter

A small, working Model Context Protocol server in TypeScript. Two tools, a resource, a prompt, and an integration test that proves the whole thing runs.

Built to be read. Every file is short, and the comments explain the decisions that are not obvious from the code, particularly around tool design, which is where most MCP servers actually go wrong.

Written alongside a full walkthrough: How to build an MCP server.

Why this exists

Most MCP examples online still use server.tool(), server.resource() and server.prompt(). Those are deprecated in the current SDK. This repo uses registerTool, registerResource and registerPrompt, which is what you should be writing today.

Verified against @modelcontextprotocol/sdk@1.30.0 on Node 20+.

Related MCP server: Rememb

Quick start

git clone https://github.com/ImTaegan/mcp-server-starter
cd mcp-server-starter
npm install
npm run build
npm test

npm test spins the real server up against the real client over an in-memory transport and exercises every tool, the resource, and the prompt. If it passes, the server works.

Connect it to a client

Build first (npm run build), then point your client at dist/index.js.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-starter/dist/index.js"],
      "env": { "NOTES_FILE": "/absolute/path/to/notes.json" }
    }
  }
}

Claude Code — from anywhere:

claude mcp add notes -- node /absolute/path/to/mcp-server-starter/dist/index.js

Restart the client. You should see a notes server with two tools, and summarise-notes as a slash command.

What is inside

Notes persist to a JSON file (NOTES_FILE, default ./notes.json) so the example has no database and nothing to configure. src/store.ts is the only file that touches storage; swap it for a real database without changing the server.

The part that actually matters

A tool's description is not documentation. It is the prompt the model reads when deciding whether to call it. Compare:

// Bad: technically accurate, useless to a model
description: "Searches notes."

// Good: says what it does, when to use it, and what comes back
description:
  "Search the user's saved notes by keyword, optionally filtered to a single tag. " +
  "Use this before answering any question about what the user has written down, " +
  "and before adding a note, to avoid creating a duplicate. " +
  "Returns matching notes ordered by relevance, most relevant first."

Nearly every "the agent called the wrong tool" problem is a description problem, not a model problem. The same applies to parameters: every field in inputSchema carries a .describe() for the same reason.

Two other things worth copying:

• Annotations. readOnlyHint and idempotentHint tell the host how risky a call is, which is what lets it auto-approve reads and confirm writes.

• Never write to stdout. The stdio transport is stdout. One stray console.log corrupts the protocol stream. Log to stderr.

Layout

src/
  index.ts        stdio wiring, deliberately tiny
  server.ts       tools, resource, prompt
  store.ts        JSON persistence, swap for a real database
  server.test.ts  integration test over an in-memory transport

Licence

MIT. Take it, strip out the notes, keep the shape.