TypeScript MCP server template

A small, forkable Model Context Protocol server using the official @modelcontextprotocol/sdk 1.x, Zod, strict TypeScript, ESM and Node.js 20+. No API keys or external services required. MIT licensed.

It exposes two tools and one resource:

word_stats defaults to five top words (range 1–20). Words are runs of Unicode letters/numbers, normalized to NFC and lowercased; punctuation separates words. Ties sort by word using JavaScript string order, without locale-dependent collation. Character count measures Unicode code points in the original text, including spaces and punctuation; it is not a grapheme count. Input is limited to 100,000 UTF-16 code units.

Quick start

git clone https://github.com/buildfound/mcp-server-template.git
cd mcp-server-template
npm install
npm run typecheck
npm run build
npm test
npm run inspect

The Inspector opens a UI for listing tools, calling them and reading resources. Try word_stats with {"text":"Hello hello world!","top":1}. It returns:

{
  "wordCount": 3,
  "characterCount": 18,
  "topWords": [{ "word": "hello", "count": 2 }]
}

After the first install, use npm ci for installs from package-lock.json.

Related MCP server: MCP Calculator Server

Project layout

src/
  server.ts             createServer(): tools, schemas and resource
  stdio.ts              Executable stdio entrypoint
  http.ts               HTTP factory and entrypoint
  tools/
    add.ts              Pure addition function
    word-stats.ts       Pure text analysis function
test/
  tools.test.ts         Unit tests
  server.test.ts        SDK Client + InMemoryTransport integration
  http.test.ts          Real HTTP endpoint + SDK clients

tsc compiles only src/ into dist/. Typechecking includes tests too. The package bin points at dist/stdio.js, which preserves the Node shebang. Server identity comes from package.json; keep that file next to dist/ when copying the build.

Add your own tool

Put business logic in a pure function under src/tools/, then import and register it inside createServer() in src/server.ts. For example:

// src/tools/greet.ts
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

// src/server.ts (z and server already exist here)
// Add this import at the top:
import { greet } from "./tools/greet.js";

// Add this registration inside createServer():
server.registerTool(
  "greet",
  {
    description: "Greet someone by name.",
    inputSchema: { name: z.string().min(1).max(100) },
  },
  ({ name }) => ({ content: [{ type: "text", text: greet(name) }] }),
);

The SDK validates arguments against the Zod schema. Follow word_stats for an outputSchema and structuredContent; keep a text representation for clients that display text results. Update the tool list in info://server, add tests, and rebuild before restarting your client. See the SDK v1 server guide for other capabilities.

Transports and scripts

Stdio

npm start       # Runs node dist/stdio.js; build first
npm run dev    # Watches src/stdio.ts with tsx

Use stdio when a local MCP client launches the server as a child process. Running it in a terminal waits for MCP messages; it is not an interactive CLI. Stdout carries protocol messages only. Send diagnostics to stderr with console.error.

Streamable HTTP

npm run build
npm run start:http
curl http://127.0.0.1:3000/health
# {"status":"ok"}

The endpoint is http://127.0.0.1:3000/mcp. Configure HOST and PORT in the process environment; defaults are 127.0.0.1 and 3000. For example, in a POSIX shell:

HOST=127.0.0.1 PORT=3001 npm run start:http
npx tsx watch src/http.ts

HTTP uses stateless mode: every POST gets a fresh McpServer and StreamableHTTPServerTransport, with JSON responses and no session ID. There is no persistent server-to-client stream, session storage or resumability. GET /mcp and DELETE /mcp return 405 Method Not Allowed, as there is no stream or session to manage. GET /health returns JSON. Use HTTP for a separately running process or as a starting point for a secured network service.

Connect a client

Build first. Replace /absolute/path/mcp-server-template below with your checkout's absolute path. If a GUI client cannot find node, use the absolute path to your Node executable too. On Windows, use escaped paths such as C:\\path\\mcp-server-template\\dist\\stdio.js in JSON.

Claude Desktop

Open Settings → Developer → Edit Config and merge this into claude_desktop_config.json, preserving any existing servers. Quit and reopen the app after saving. See the local server setup guide.

{
  "mcpServers": {
    "template": {
      "command": "node",
      "args": ["/absolute/path/mcp-server-template/dist/stdio.js"]
    }
  }
}

Claude Code

Choose one transport. The HTTP command requires the HTTP server to be running separately. These follow the Claude Code MCP commands.

claude mcp add --transport stdio template -- node /absolute/path/mcp-server-template/dist/stdio.js
claude mcp add --transport http template-http http://127.0.0.1:3000/mcp
claude mcp list

Use /mcp inside Claude Code to check the connection.

Cursor

Add this to .cursor/mcp.json in your project, or merge it into ~/.cursor/mcp.json for a global setup. See Cursor's MCP configuration.

{
  "mcpServers": {
    "template": {
      "command": "node",
      "args": ["/absolute/path/mcp-server-template/dist/stdio.js"]
    }
  }
}

VS Code

For the VS Code configuration format, create .vscode/mcp.json with the following. Use MCP: List Servers to start it. See the VS Code MCP configuration reference.

{
  "servers": {
    "template": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/mcp-server-template/dist/stdio.js"]
    }
  }
}

For a separately running HTTP server, replace the entry with {"type":"http","url":"http://127.0.0.1:3000/mcp"}.

MCP Inspector

npm run inspect builds and starts the official Inspector with the stdio entrypoint. To inspect HTTP, run npm run start:http in one terminal and npx @modelcontextprotocol/inspector in another, choose Streamable HTTP, and enter http://127.0.0.1:3000/mcp.

Testing

Unit tests exercise pure logic, including Unicode, empty input and ranking ties. The in-memory test uses an SDK Client to initialize, list tools/resources, call both tools, read info://server and check schema rejection. The HTTP test binds an ephemeral port and connects two independent SDK clients; it also checks health, unsupported methods, malformed JSON and Host/Origin rejection. No external services are needed.

Security and forking

• HTTP binds to loopback by default and has no authentication. Add authentication, authorization, TLS, request limits and deployment-specific validation before exposing it beyond your machine.

• Host validation helps prevent DNS rebinding: accepted authorities are 127.0.0.1, localhost, [::1] and the configured HOST, each with the bound port. Wildcard bind addresses (0.0.0.0, ::) are excluded from this allowlist. If you bind a wildcard address, only loopback authorities work until you explicitly extend validation for your deployment.

• Requests with an Origin must match http:// plus the validated Host exactly. Cross-origin requests are rejected; CORS is not enabled. Configure an explicit trusted host/origin policy when adding a reverse proxy, TLS or browser access. Host/Origin checks are not authentication.

• Example tools are offline and read-only. Treat new tools as code running with the server process's permissions. Validate inputs, bound work, protect secrets and avoid logging sensitive tool data. .env is ignored but is not automatically loaded.

Fork the repository, rename the package and bin in package.json, update descriptions and resource metadata, and replace the example tools. Run npm install to refresh lockfile metadata after renaming, then typecheck, build and test. Keep the MIT copyright and license notice.

Built by BuildFound, a founder-led AI product studio.

License

MIT © 2026 Fekri Darkaoui.