IGN API Carto MCP Server

Instructions

Implementation Reference

• src/index.ts:170-189 (handler)

  The core handler function that destructures input params, determines the cadastre API endpoint based on source ('pci' or 'bdparcellaire'), fetches data via apiRequest, and returns either raw JSON or formatted markdown GeoJSON response.

  async (params) => {
    const { source, response_format, ...queryParams } = params;
    const endpoint = source === "pci" ? "/cadastre/parcelle" : "/cadastre/parcelle";
    
    const data = await apiRequest<unknown>(endpoint, { params: queryParams as Record<string, string | number | boolean | undefined> });
  
    if (response_format === ResponseFormat.JSON) {
      return {
        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      };
    }
  
    const markdown = formatGeoJSONToMarkdown(
      data as import("./types.js").GeoJSONFeatureCollection,
      "Parcelles cadastrales"
    );
    return {
      content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }],
    };
  }

• src/index.ts:149-162 (schema)

  Zod schema for input validation, defining optional parameters for geometry intersection, administrative codes, parcel identifiers, data source, pagination, and response format.

  inputSchema: z.object({
    geom: GeometrySchema.optional(),
    code_insee: z.string().optional().describe("INSEE commune code (5 digits)"),
    code_dep: z.string().optional().describe("Department code"),
    code_com: z.string().optional().describe("Commune code within department"),
    section: z.string().optional().describe("Cadastral section (2 chars)"),
    numero: z.string().optional().describe("Parcel number"),
    source: z
      .enum(["pci", "bdparcellaire"] as const)
      .default("pci")
      .describe("Data source: 'pci' (recommended) or 'bdparcellaire'"),
    ...PaginationSchema,
    response_format: ResponseFormatSchema,
  }).strict(),

• src/index.ts:119-190 (registration)

  The server.registerTool call that registers the tool with its metadata (title, description, annotations), input schema, and inline handler function.

  server.registerTool(
    "ign_get_cadastre_parcelles",
    {
      title: "Get cadastral parcels",
      description: `Search for cadastral parcels (land plots) in France.
  
  This tool queries the IGN API Carto cadastre module to find parcels by geometry intersection or administrative codes. Useful for property identification, urban planning, and administrative procedures.
  
  Args:
    - geom (string, optional): GeoJSON geometry to intersect
    - code_insee (string, optional): INSEE commune code (5 digits)
    - code_dep (string, optional): Department code (2-3 digits)
    - code_com (string, optional): Commune code within department (3 digits)
    - section (string, optional): Cadastral section (2 characters)
    - numero (string, optional): Parcel number
    - source (string): Data source - 'pci' (PCI Express, recommended) or 'bdparcellaire'
    - _limit (number): Max results (1-1000)
    - _start (number): Pagination offset
  
  Returns:
    GeoJSON FeatureCollection with parcel geometries and properties including:
    - numero: Parcel number
    - feuille: Sheet number
    - section: Cadastral section
    - code_dep, code_com, com_abs, code_arr
    - geometry: MultiPolygon
  
  Examples:
    - "Find parcels in commune 75101" -> code_insee="75101"
    - "Get parcel AB-0001 in section AB" -> section="AB", numero="0001"`,
      inputSchema: z.object({
        geom: GeometrySchema.optional(),
        code_insee: z.string().optional().describe("INSEE commune code (5 digits)"),
        code_dep: z.string().optional().describe("Department code"),
        code_com: z.string().optional().describe("Commune code within department"),
        section: z.string().optional().describe("Cadastral section (2 chars)"),
        numero: z.string().optional().describe("Parcel number"),
        source: z
          .enum(["pci", "bdparcellaire"] as const)
          .default("pci")
          .describe("Data source: 'pci' (recommended) or 'bdparcellaire'"),
        ...PaginationSchema,
        response_format: ResponseFormatSchema,
      }).strict(),
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },
    async (params) => {
      const { source, response_format, ...queryParams } = params;
      const endpoint = source === "pci" ? "/cadastre/parcelle" : "/cadastre/parcelle";
      
      const data = await apiRequest<unknown>(endpoint, { params: queryParams as Record<string, string | number | boolean | undefined> });
  
      if (response_format === ResponseFormat.JSON) {
        return {
          content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
        };
      }
  
      const markdown = formatGeoJSONToMarkdown(
        data as import("./types.js").GeoJSONFeatureCollection,
        "Parcelles cadastrales"
      );
      return {
        content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }],
      };
    }
  );