Home › MCP servers › MCP server (TypeScript) AGENTS.md

MCP server (TypeScript) AGENTS.md

AGENTS.md for building Model Context Protocol servers in TypeScript with clear tools, zod schemas and safe defaults.

AGENTS.mdMCP servers

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md — MCP server (TypeScript)

## Setup
- `npm i` · build `npm run build` · test with the inspector: `npx @modelcontextprotocol/inspector node dist/index.js`

## Design rules
- Use the official `@modelcontextprotocol/sdk`. Register tools with `server.registerTool` and zod input schemas.
- Tool names are verbs in snake_case (`search_issues`, `create_note`). Descriptions say what the tool does, when to use it, and what it returns — the model reads them.
- Keep tools small and composable; return concise, structured text. Paginate or truncate large results and say so in the output.
- Mark side effects clearly: read-only tools vs. tools that write/delete. Destructive tools require explicit parameters (no implicit "delete all").
- Return errors as tool results with `isError: true` and an actionable message instead of throwing.
- stdio transport: never write logs to stdout (it corrupts the protocol) — log to stderr.
- Secrets come from environment variables; never echo them in tool output.

## Done
- `npm run build` passes, every tool exercised in the inspector, README lists tools and required env vars.