MCP Server TypeScript Project Structure

TypeScript MCP server with full type safety. Zod validation, proper error handling, and npm packaging.

#mcp #typescript #ai #tools #claude #nodejs #model-context-protocol

PNG PDF

Project Directory

mcp-server/

src/

Server source code

index.ts

Server entry point

tools/

Tool definitions

index.ts

Export all tools

search.ts

database.ts

resources/

Resource providers

index.ts

files.ts

prompts/

Prompt templates

index.ts

analysis.ts

lib/

Shared utilities

http.ts

validators.ts

tests/

tools.test.ts

resources.test.ts

package.json

tsconfig.json

.env.example

.gitignore

README.md

Why This Structure?

The TypeScript SDK provides full type safety for MCP development. Zod schemas validate inputs at runtime while TypeScript catches errors at compile time. This structure mirrors the Python version but follows Node.js conventions.

Key Directories

src/index.ts-Server instance, registers all handlers
src/tools/-Tool implementations with Zod schemas
src/resources/-Resource handlers for AI context
src/lib/-Shared utilities and HTTP clients

Getting Started

npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init
npm run build && node dist/index.js

TypeScript MCP Server

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server" });

server.tool(
  "search",
  { query: z.string().describe("Search query") },
  async ({ query }) => ({
    content: [{ type: "text", text: `Results: ${query}` }]
  })
);

When To Use This

Teams already using TypeScript/Node.js
Need compile-time type checking
Building npm-publishable MCP packages
Integrating with existing Node.js services

Trade-offs

Build step-Requires compilation before running
More verbose-Zod schemas add boilerplate vs Python decorators
Node.js required-Heavier runtime than Python for simple servers