cerata-mcp-server: Instructions file for Claude Code

Agent Protocol & Architectural Mandate

Version: 2.4.7 Target Project: mcp-ts-template Last Updated: 2024-10-15

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

Note on File Synchronization: AGENTS.md is symlinked to CLAUDE.md & .clinerules/AGENTS.md for consistency. Only edit the root AGENTS.md file. You do not have permission edit, touch, or change in any way the CLAUDE.md or .clinerules/AGENTS.md files.

Note for Developer: Never assume anything. Always review related files, search for documentation, etc. when making changes. Always prefer reading the full file content to understand the full context. NEVER attempt to edit a file before reading the current content.

I. Core Principles (Non‑Negotiable)

1. The Logic Throws, The Handler Catches

   • Implement pure, stateless logic in ToolDefinition/ResourceDefinition logic functions. No try...catch in logic.
   • Throw new McpError(...) with appropriate JsonRpcErrorCode on failure.
   • Handlers (createMcpToolHandler, resourceHandlerFactory) create RequestContext, measure execution, format responses, and catch errors.

2. Full‑Stack Observability

   • OpenTelemetry preconfigured. Logs/errors auto-correlated to traces. measureToolExecution records duration, success, payload sizes, error codes.
   • No manual instrumentation. Use provided utilities and structured logging. No direct console calls - use our logger.

3. Structured, Traceable Operations

   • Logic receives appContext (logging/tracing) and sdkContext (Elicitation, Sampling, Roots operations).
   • Pass same appContext through call stack. Use global logger with appContext in every log.

4. Decoupled Storage

   • Never access persistence backends directly. Always use DI-injected StorageService.
   • StorageService provides built-in validation, opaque cursor pagination, and parallel batch operations.
   • All inputs (tenant IDs, keys, prefixes) are validated before reaching providers.