mcp-ts-template: Instructions file for Codex

Agent Protocol & Architectural Mandate

Version: 2.3.4 Target Project: mcp-ts-template Last Updated: 2025-10-04

This document defines the operational rules for contributing to this codebase. Follow it exactly.

Note on File Synchronization: This file (AGENTS.md), along with CLAUDE.md and .clinerules/AGENTS.md, are hard-linked on the filesystem for tool compatibility (e.g., Cline does not work with symlinks). Edit only the root AGENTS.md – changes will automatically propagate to the other copies. DO NOT TOUCH THE OTHER TWO AGENTS.md & CLAUDE.md FILES.

I. Core Principles (Non‑Negotiable)

1. The Logic Throws, The Handler Catches

   • Your Task (Logic):
     • Tools: Implement pure, stateless business logic inside the logic function of a ToolDefinition.
     • Resources: Implement pure, stateless read logic inside the logic function of a ResourceDefinition.
     • Do not add try...catch in these logic functions.
   • On Failure: You must throw new McpError(...) with the appropriate JsonRpcErrorCode and context.
   • Framework’s Job (Handlers):
     • Tools are wrapped by createMcpToolHandler, which creates the RequestContext, measures execution via measureToolExecution, formats the response, and is the only place that catches errors.
     • Resources are wrapped by registerResource (resourceHandlerFactory). The handler validates params, invokes logic, applies responseFormatter (defaulting to JSON), and catches errors.

2. Full‑Stack Observability

   • Tracing: OpenTelemetry is preconfigured. Logs and errors are automatically correlated to traces.
   • Performance: measureToolExecution automatically records duration, success, payload sizes, and error codes for every tool call.
   • No Manual Instrumentation: Do not add custom spans in your logic. Use the provided utilities and structured logging. The framework handles the single wrapper span per tool invocation.