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;
  }