MCP TypeScript Starter

A feature-complete Model Context Protocol (MCP) server template in TypeScript. This starter demonstrates all major MCP features with clean, production-ready code.

📚 Documentation

• Model Context Protocol
• TypeScript SDK
• Building MCP Servers

✨ Features

| Category | Feature | Description | |----------|---------|-------------| | Tools | hello | Basic tool with annotations | | | get_weather | Tool with structured output schema | | | ask_llm | Tool that invokes LLM sampling | | | long_task | Tool with 5-second progress updates | | | load_bonus_tool | Dynamically loads a new tool | | Resources | info://about | Static informational resource | | | file://example.md | File-based markdown resource | | Templates | greeting://{name} | Personalized greeting | | | data://items/{id} | Data lookup by ID | | Prompts | greet | Greeting in various styles | | | code_review | Code review with focus areas |

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm or pnpm

Installation

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-typescript-starter.git
cd mcp-typescript-starter

# Install dependencies
npm install

# Build
npm run build

Running the Server

stdio transport (for local development):

npm run start:stdio

HTTP transport (for remote/web deployment):

npm run start:http
# Server runs on http://localhost:3000

🔧 VS Code Integration

This project includes VS Code configuration for seamless development:

1. Open the project in VS Code
2. The MCP configuration is in .vscode/mcp.json
3. Build with Ctrl+Shift+B (or Cmd+Shift+B on Mac)
4. Test the server using VS Code's MCP tools

Using DevContainers

1. Install the Dev Containers extension
2. Open command palette: "Dev Containers: Reopen in Container"
3. Everything is pre-configured and ready to use!

📁 Project Structure

.
├── src/
│   ├── tools.ts       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.ts   # Resource and template definitions
│   ├── prompts.ts     # Prompt definitions
│   ├── server.ts      # Server orchestration (combines all modules)
│   ├── stdio.ts       # stdio transport entrypoint
│   └── http.ts        # HTTP transport entrypoint
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── tasks.json     # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── package.json
├── tsconfig.json
├── .prettierrc        # Prettier configuration
└── eslint.config.js

🛠️ Development

# Development mode with live reload
npm run dev

# Build for production
npm run build

# Format code
npm run format

# Lint
npm run lint

# Clean build
npm run clean && npm run build

Live Reload

The npm run dev command uses tsx watch for instant reloads during development. Changes to any .ts file will automatically restart the server.

🔍 MCP Inspector

The MCP Inspector is an essential development tool for testing and debugging MCP servers.

Running Inspector

npx @modelcontextprotocol/inspector -- npx tsx src/stdio.ts

What Inspector Provides

• Tools Tab: List and invoke all registered tools with parameters
• Resources Tab: Browse and read resources and templates
• Prompts Tab: View and test prompt templates
• Logs Tab: See JSON-RPC messages between client and server
• Schema Validation: Verify tool input/output schemas

Debugging Tips

1. Start Inspector before connecting your IDE/client
2. Use the "Logs" tab to see exact request/response payloads
3. Test tool annotations are exposed correctly
4. Verify progress notifications appear for long_task

📖 Feature Examples

Tool with Annotations

server.tool(
  "hello",
  {
    title: "Say Hello",
    description: "A friendly greeting tool",
    annotations: { readOnlyHint: true },
  },
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  })
);

Resource Template

server.resourceTemplate(
  "greeting://{name}",
  { name: "Personalized Greeting", mimeType: "text/plain" },
  async ({ name }) => ({
    contents: [{
      uri: `greeting://${name}`,
      text: `Hello, ${name}!`,
    }],
  })
);

Tool with Progress Updates

server.tool(
  "long_task",
  { title: "Long Task" },
  { taskName: z.string() },
  async ({ taskName }, { sendProgress }) => {
    for (let i = 0; i < 5; i++) {
      await sendProgress({ progress: i / 5, total: 1.0 });
      await sleep(1000);
    }
    return { content: [{ type: "text", text: "Done!" }] };
  }
);

🔐 Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

| Variable | Description | Default | |----------|-------------|---------| | PORT | HTTP server port | 3000 |

🤝 Contributing

Contributions welcome! Please ensure your changes maintain feature parity with other language starters.

📄 License

MIT License - see LICENSE for details.