server-quality-harness: Instructions file for Codex

AGENTS.md

Welcome to the Smithery TypeScript MCP Server Scaffold!

This is the template project that gets cloned when you run npx create-smithery. It provides everything you need to build, test, and deploy a Model Context Protocol (MCP) server with Smithery.

Table of Contents

• Project Structure
• Quick Start Commands
• smithery.yaml Configuration
• Concepts
• Development Workflow
• Deployment & CI/CD
• Troubleshooting
• Resources
• Community & Support

Project Structure

your-server/
├── package.json           # Project dependencies and scripts
├── smithery.yaml          # Runtime specification (runtime: typescript)
├── src/
│   └── index.ts          # Main server implementation
└── README.md

Quick Start Commands

# Run development server (streamable HTTP on port 8081)
# Opens interactive Smithery playground in your browser for testing
npm run dev          # or: bun run dev, pnpm run dev, yarn dev

# Run on a custom port
npm run dev -- --port 3000

# Kill existing process if port 8081 is in use
lsof -ti:8081 | xargs kill

# Build for production
npm run build        # or: bun run build, pnpm run build, yarn build

smithery.yaml Configuration

The smithery.yaml file configures how your server runs. For this TypeScript setup, it only needs:

Required Field

runtime: typescript

This tells Smithery to use the TypeScript runtime for your server.

Optional Fields

target (optional)

Specifies where your server runs and determines the transport protocol. Can be local or remote:

runtime: typescript
target: remote    # Options: remote (default) or local

• local: Server runs on the user's machine using stdio transport. When published, bundled into .mcpb file for distribution
• remote: Server runs on Smithery's infrastructure using HTTP transport (default)