8df0a58dfa
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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.
|