mcp-server: Instructions file for Codex

AGENTS.md - MCP Server Development Guide

This document provides guidelines and commands for agents working on this codebase.

Project Overview

This is a TypeScript-based MCP (Model Context Protocol) server with a pluggable tool architecture. The server uses Express for HTTP endpoints and Zod for schema validation.

Build Commands

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Development with hot reload
npm run dev

# Run linting
npm run lint

# Fix linting errors automatically
npm run lint:fix

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

# Run a single test file
npx vitest run src/tools/echo/index.test.ts

# Run tests matching a pattern
npx vitest run -t "echo"

Environment Variables

Variable	Default	Description
PORT	3000	Server port
HOST	0.0.0.0	Server host
AUTHORIZATION_KEY	-	Bearer token for API authentication (optional)

Code Style Guidelines

TypeScript Configuration

• Target: ES2022
• Module: NodeNext
• Strict mode enabled
• Explicit return types: Off (optional, but recommended for public APIs)
• Use unknown instead of any when type is uncertain

Naming Conventions

• Variables/Functions: camelCase (toolRegistry, getAllTools)
• Classes: PascalCase (ToolRegistry, MCPTool)
• Constants: SCREAMING_SNAKE_CASE for config values
• Files: kebab-case for general files, index.ts for directory entry points
• Interfaces: Prefix with MCP for domain types (MCPTool, MCPMethodDefinition)

Imports

• Use .js extension in imports even for TypeScript files (required for NodeNext module resolution)
• Group imports in this order: external dependencies, internal modules
• Use named exports for utilities and classes
• Use default exports for tool modules

import { z } from 'zod';
import { MCPTool } from '../../types/mcp.js';