IGN API Carto MCP Server

Instructions

Implementation Reference

• src/index.ts:59-113 (registration)

  Registration of the 'ign_get_communes_by_postal_code' tool with title, description, inputSchema, annotations, and handler function.
  server.registerTool( "ign_get_communes_by_postal_code", { title: "Get communes by postal code", description: `Retrieve French communes (municipalities) associated with a postal code. This tool queries the IGN API Carto codes-postaux module to find all communes that share a given postal code. In France, a postal code can cover multiple communes, and this tool returns all of them. Args: - code_postal (string): French postal code (5 digits, e.g. "75001", "69000") - response_format ('markdown' | 'json'): Output format (default: 'markdown') Returns: For JSON format: [ { "codePostal": "75001", "codeCommune": "75101", "nomCommune": "Paris 1er Arrondissement", "libelleAcheminement": "PARIS" } ] Examples: - "What communes are in postal code 75001?" -> code_postal="75001" - "Find cities for zip 69000" -> code_postal="69000"`, inputSchema: z.object({ code_postal: z .string() .regex(/^\d{5}$/, "Postal code must be 5 digits") .describe("French postal code (5 digits)"), response_format: ResponseFormatSchema, }).strict(), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, }, async ({ code_postal, response_format }) => { const communes = await getCommunesByPostalCode(code_postal); if (response_format === ResponseFormat.JSON) { return { content: [{ type: "text", text: JSON.stringify(communes, null, 2) }], }; } const markdown = formatCommunesToMarkdown(communes, code_postal); return { content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }], }; } );
• src/index.ts:100-112 (handler)

  Handler implementation: fetches communes via getCommunesByPostalCode, returns JSON or formatted markdown response.
  const communes = await getCommunesByPostalCode(code_postal); if (response_format === ResponseFormat.JSON) { return { content: [{ type: "text", text: JSON.stringify(communes, null, 2) }], }; } const markdown = formatCommunesToMarkdown(communes, code_postal); return { content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }], }; }
• src/index.ts:85-91 (schema)

  Zod inputSchema: validates code_postal (5-digit string) and response_format.
  inputSchema: z.object({ code_postal: z .string() .regex(/^\d{5}$/, "Postal code must be 5 digits") .describe("French postal code (5 digits)"), response_format: ResponseFormatSchema, }).strict(),
• src/api-client.ts:85-87 (helper)

  getCommunesByPostalCode: core API client function querying IGN endpoint `/codes-postaux/communes/${code_postal}`.
  export async function getCommunesByPostalCode(codePostal: string): Promise<CommuneResponse[]> { return apiRequest<CommuneResponse[]>(`/codes-postaux/communes/${codePostal}`); }
• src/types.ts:31-36 (schema)

  CommuneResponse TypeScript interface defining the structure of commune data returned by the API.
  export interface CommuneResponse { codePostal: string; codeCommune: string; nomCommune: string; libelleAcheminement: string; }