mcp-ts-template CLAUDE.md

Agent Protocol & Architectural Mandate

Version: 2.3.1 Target Project: mcp-ts-template

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.

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.

3. Structured, Traceable Operations

   • Your logic functions will receive two context objects: appContext (for internal logging/tracing) and sdkContext (for SDK-level operations like Elicitation, Sampling, and Roots).
   • The sdkContext provides methods (like elicitInput and createMessage) for client interaction.
   • Pass the same appContext through your internal call stack for continuity.
   • Use the global logger for all logging; include the appContext in every log call.