# TS MCP Template (V1)

A Node.js template for building Model Context Protocol (MCP) servers with TypeScript. This template focuses on a local-first development experience, protocol-safe stdio execution, and explicit capability registration.

## Status: V1 Alpha
This template supports:
- Node.js 20+ runtime
- Single-package architecture
- Protocol-safe Local Stdio transport (Primary)
- Streamable HTTP transport (Secondary)
- Explicit, function-based tool, resource, and prompt registration
- Vitest-powered transport and core logic testing

It does not currently support Bun, Deno, edge runtimes, built-in authentication, or telemetry.

## Quickstart: Local Stdio

Stdio is the primary transport for local development and integration with desktop LLM clients like Claude.

1. **Install dependencies**
   ```bash
   npm install
   ```

2. **Run with MCP Inspector**
   The template includes a protocol-safe launch configuration in `package.json` to avoid stdout pollution. Use this command to test your server:
   ```bash
   npx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
   ```

3. **Build the project**
   To prepare for production or use with a compiled entry point:
   ```bash
   npm run build
   ```

## Usage: HTTP

The HTTP transport uses the Node-native `StreamableHTTPServerTransport` for remote or web-based connections.

1. **Start the HTTP server**
   ```bash
   npm run dev:http
   ```
   The server defaults to `127.0.0.1:3000`. You can configure the port via the `HTTP_PORT` environment variable.

2. **Endpoints**
   - `POST /mcp`: Initialize a new session and handle requests.
   - `GET /mcp`: Handle ongoing session requests.

## Development and Testing

- **Typecheck**: `npm run typecheck`
- **Test**: `npm test` (Runs Vitest smoke tests for stdio, HTTP, and core logic)
- **Dev (Core Logic)**: `npm run dev` (Executes `src/index.ts`)

## Repository Structure

- `src/core/`: The shared MCP core factory (`createMcpCore`) that builds the server and registry.
- `src/capabilities/`: Definitions and handlers for tools, resources, and prompts.
- `src/stdio.ts`: The stdio entry point and transport setup.
- `src/http.ts`: The HTTP entry point and session management.
- `src/config/`: Runtime configuration and environment variable parsing.
- `src/lib/`: Internal utilities, stderr-safe logging, and error handling.

## Extension Guidance

This template uses an explicit, function-based registration pattern instead of decorators or reflection.

### 1. Define Contracts
Add new tool or prompt schemas in `src/capabilities/contracts.ts` to share types between handlers and tests.

### 2. Implement Handlers
Create or update files in `src/capabilities/` (e.g., `tools.ts`):
1. Define the handler logic.
2. Update the `register...Capabilities` function to add descriptors to the registry.
3. Update the `register...Handlers` function to wire the logic to the `McpServer` instance.

### 3. Register with Core
If you create new capability modules, ensure they are called within `src/capabilities/index.ts` in the `registerCoreCapabilities` and `registerCoreMcpCapabilities` functions.

## V1 Limitations
- **No Auth**: HTTP transport does not include built-in authentication.
- **Node-only**: Specifically tuned for Node.js 20+.
- **No Monorepo**: Designed as a standalone project template.
- **Local Focus**: Deployment guides for cloud providers are not provided in V1.