contentful-mcp-server: Instructions file for Codex

Agent Guide

Read this file first. It tells you where to find context in this repo.

Quick Reference

Sharp Edges & Invariants

• Always call get_initial_context first — the server's agent instructions require this as the first tool call in every session. It initializes connection context and returns space metadata.
• Entry mutation limit: 5 per conversation — the system prompt enforces a max of 5 entry create/edit/mutate operations at a time.
• ESM-only — both packages output ESM. All internal imports must use .js extensions (even in .ts source files).
• Migration tools are disabled by default — export_space, import_space, and space_to_space_param_collection are registered but disabled. Only space_to_space_migration_handler can enable them.
• contentful-export and contentful-import are lazy-loaded — they are dynamically imported at runtime to avoid bundling their large dependency trees when not needed.
• Zod schemas define tool input contracts — every tool uses Zod for input validation. Most tools pass .shape to the MCP SDK; strict schemas must pass the full Zod object so unknown arguments are rejected.
• X-Contentful-User-Agent-Tool header — all CMA calls include this header with the MCP version. Do not remove or change the header name; it's used for observability.
• Never hardcode space/environment IDs in tool implementations — always read from ContentfulConfig or tool input params.
• contentful-management uses namespace imports — since CMA v12, use import * as ctfl from 'contentful-management' (not default import).