mcp -starter-ts

This MCP server is a TypeScript-based starter template that implements the Model Context Protocol (MCP) with dual transport modes: stdio (default) and HTTP (SSE + JSON-RPC). The included auto-loading architecture lets you drop tools, resources, and prompts into their respective directories and have them registered automatically at runtime. You can test and interact with the server and its components using the MCP Inspector during development, or connect clients like Claude Desktop or custom MCP clients to the HTTP endpoint. To run locally, choose either stdio or HTTP mode and start the server through Node.js. In stdio mode, the server communicates via standard input/output, which is convenient for desktop apps or local tooling. In HTTP mode, the server exposes an SSE endpoint at /mcp for streaming events and a JSON-RPC endpoint at /mcp for requests, suitable for web deployments and remote clients.

Prerequisites:

• Node.js 20.11.0 or higher
• npm (or yarn)

Install and build:

# Clone the repository
git clone https://github.com/alexanderop/mcp-server-starter-ts.git
cd mcp-server-starter-ts

# Install dependencies
npm install

# Build the project
npm run build

Run in stdio mode (default):

npm run serve:stdio
# or explicitly
node build/index.js

Run in HTTP mode (requires port to be open and CORS as needed):

# Use the HTTP transport on port 3000
export STARTER_TRANSPORT=http
export PORT=3000
npm run serve:http

Testing with MCP Inspector during development:

npm run inspect

Environment and configuration can also be customized via Docker or using the provided Docker integration in the repository.

Tips and common issues:

• Ensure you have built the project before running in production-like environments: npm run build
• When using HTTP mode, configure CORS_ORIGIN to allow your client origins (default is *).
• If you add new tools, resources, or prompts, leverage the auto-loading feature by placing files in the corresponding directories; the server reloads these on startup.
• For debugging, use the MCP Inspector to verify that tools are registered correctly and that transport endpoints respond as expected.
• The Docker setup supports both stdio and HTTP by environment, but the default HTTP behavior may require port mapping and proper environment variables in your deployment environment.