mcp-server-starter: Instructions file for Codex

AGENTS.md

This file provides context for AI coding assistants (Claude Code, Cursor, Copilot, Cline, etc.)

Project Structure

src/
├── index.ts              # Server entry point — registers tools/resources/prompts and starts transport
├── config.ts             # Environment variable parsing
├── helpers.ts            # Response helpers: ok() and err() (ok supports structuredContent)
├── pkg.ts                # JSON-modules import of package.json — sole place {name,version} is read
├── tools/
│   └── greet.ts          # Example tool with safety annotations + outputSchema — copy this pattern
├── prompts/
│   ├── hello.ts          # Zero-arg prompt example
│   └── code-review.ts    # Templated prompt with Zod-validated args
└── resources/
    └── server-info.ts    # Example resource exposing server metadata
tests/
├── config.test.js        # parseConfig environment branches
├── greet.test.js         # Tool tests (run against built output in dist/)
├── helpers.test.js       # ok() / err() unit tests
├── hello.test.js         # Zero-arg prompt tests
├── code-review.test.js   # Templated prompt tests
├── server-info.test.js   # Resource tests
└── integration/          # End-to-end via SDK in-memory transport + spawned process
    ├── sdk-contract.test.js
    └── server-boot.test.js

Adding a New Tool

1. Create src/tools/your-tool.ts:

   import { z } from 'zod';
   import { ok, err } from '../helpers.js';
   
   export const name = 'your_tool';
   
   export const config = {
     title: 'Your Tool',
     description: 'What your tool does',
     inputSchema: {
       param: z.string().describe('Parameter description'),
     },
     // outputSchema makes the handler return `structuredContent` validated
     // against this shape. REQUIRED by the 2026 MCP spec when declared.
     // Omit for free-form text-only tools.
     outputSchema: {
       result: z.string().describe('Processed value'),
     },
     annotations: {
       readOnlyHint: true,       // Does not modify anything
       destructiveHint: false,    // Not destructive
       idempotentHint: true,      // Same input = same result
       openWorldHint: false,      // No external system interaction
     },
   };
   
   export async function handler({ param }: { param: string }) {
     try {
       const result = `Result: ${param}`;
       // Second arg to ok() → structuredContent alongside the text mirror.
       return ok(result, { result });
     } catch (e) {
       return err(`Failed: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
   

2. Register it in src/index.ts:

   import * as yourTool from './tools/your-tool.js';
   server.registerTool(yourTool.name, yourTool.config, yourTool.handler);
   

3. Add tests in tests/your-tool.test.js