synthetic-web-search-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents working with this repository.

Build & Development Commands

# Build the project (TypeScript compilation)
npm run build

# Run in development mode with ts-node
npm run dev

# Watch for changes and auto-rebuild
npm run watch

# Run the compiled server
npm start

# Test with MCP Inspector (manual testing)
npx @modelcontextprotocol/inspector synthetic-web-search-mcp

Note: No automated test suite exists. Use MCP Inspector for manual testing. No linting or formatting tools are configured.

Code Style Guidelines

Imports

• Use ES Module syntax with .js extensions in import paths (required for ESM projects)
  • ✅ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
  • ❌ import { Server } from '@modelcontextprotocol/sdk/server/index';
• Group imports by source (external packages first, then internal modules)
• Use named exports over default exports for better tree-shaking

TypeScript Configuration

• Strict mode is enabled in tsconfig.json
• Target: ES2022, Module: ES2022
• Always use type assertions sparingly; prefer proper type annotations
• Use await async for all asynchronous operations
• No any types allowed (strict mode enforcement)

Naming Conventions

• Constants: UPPER_SNAKE_CASE (e.g., API_KEY)
• Variables/functions: camelCase (e.g., searchWeb, response)
• Classes: PascalCase (e.g., Server, Transport)
• Interface/type definitions: PascalCase (e.g., SearchRequest, ToolResponse)
• File names: kebab-case or camelCase for TypeScript files

Formatting & Style

• No comments in code unless explicitly requested
• Use 2-space indentation (project default)
• Use single quotes for strings
• Add trailing commas in multi-line objects/arrays
• Use async/await instead of Promise chains
• Use const by default, let only when reassignment is needed
• Use template literals for string interpolation

Error Handling

• Use console.error() for error messages to stderr (MCP protocol requirement)
• Exit with code 1 on critical failures: process.exit(1)
• Throw descriptive Error objects with context:

  throw new Error('Query parameter is required');
  throw new Error(`API error: ${response.status} ${response.statusText} - ${errorText}`);
  

• Validate environment variables at entry point and exit early
• Always check response.ok for HTTP requests before parsing JSON