mcp-typescript-starter: Instructions file for Codex

AGENTS.md

This file provides context for AI coding agents working in this repository.

Quick Reference

Task	Command
Install	npm ci
Build	npm run build
Test	npm test
Lint	npm run lint
Lint fix	npm run lint:fix
Format	npm run format
Format check	npm run format:check
Run (stdio)	npm run start:stdio
Run (HTTP)	npm run start:http
Dev mode	npm run dev

Project Overview

MCP TypeScript Starter is a feature-complete Model Context Protocol (MCP) server template in TypeScript. It demonstrates all major MCP features including tools, resources, resource templates, prompts, sampling, progress updates, and dynamic tool loading.

Purpose: Workshop starter template for learning MCP server development.

Technology Stack

• Runtime: Node.js >=20.0.0
• Language: TypeScript 5.5+ (ESM)
• MCP SDK: @modelcontextprotocol/sdk
• Schema Validation: Zod
• HTTP Server: Express
• Package Manager: npm (use npm ci for reproducible installs)
• Formatter: Prettier
• Linter: ESLint

Project Structure

src/
├── server.ts     # Main server with all MCP features (tools, resources, prompts)
├── stdio.ts      # stdio transport entrypoint
└── http.ts       # HTTP/SSE transport entrypoint

.vscode/
├── mcp.json          # MCP server configuration for VS Code
├── tasks.json        # Build/run tasks
├── launch.json       # Debug configurations
└── extensions.json   # Recommended extensions

.devcontainer/
└── devcontainer.json # DevContainer configuration

Build & Run Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in watch mode (development)
npm run dev

# Run server (stdio transport)
npm run start:stdio

# Run server (HTTP transport)
npm run start:http

Linting & Formatting

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check formatting
npm run format:check

# Full check (lint + format + build)
npm run check