IGN API Carto MCP Server

Instructions

Implementation Reference

• src/index.ts:688-709 (handler)

  The handler function executes the tool logic: constructs the API endpoint `/limites-administratives/{type}`, calls apiRequest with query params, and formats the GeoJSON response as JSON or Markdown.

  async (params) => {
    const { type, response_format, ...queryParams } = params;
    const endpoint = `/limites-administratives/${type}`;
  
    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,
      `Limites administratives - ${type}`
    );
    return {
      content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }],
    };
  }

• src/index.ts:671-680 (schema)

  Zod input schema validating parameters: required 'type' (commune, departement, region), optional geom, lon, lat, pagination (_limit, _start), and response_format.

  inputSchema: z.object({
    type: z
      .enum(["commune", "departement", "region"] as const)
      .describe("Administrative boundary type"),
    geom: GeometrySchema.optional(),
    lon: z.number().optional().describe("Longitude coordinate (use with lat)"),
    lat: z.number().optional().describe("Latitude coordinate (use with lon)"),
    ...PaginationSchema,
    response_format: ResponseFormatSchema,
  }).strict(),

• src/index.ts:646-710 (registration)

  Registers the 'ign_get_administrative_limits' tool on the MCP server, including title, description, input schema, annotations, and inline handler function.

  server.registerTool(
    "ign_get_administrative_limits",
    {
      title: "Get administrative boundaries",
      description: `Query French administrative boundaries (communes, departments, regions).
  
  This tool accesses administrative limit data from the IGN Admin Express dataset.
  
  Args:
    - type (string): Boundary type - 'commune', 'departement', or 'region'
    - geom (string, optional): GeoJSON geometry to intersect
    - lon (number, optional): Longitude coordinate (use with lat)
    - lat (number, optional): Latitude coordinate (use with lon)
    - _limit (number): Max results (1-1000)
    - _start (number): Pagination offset
  
  Note: Either provide geom OR (lon + lat), but not both.
  
  Returns:
    GeoJSON FeatureCollection with administrative boundaries.
  
  Examples:
    - "What commune is at this point?" -> type="commune", lon=2.35, lat=48.85
    - "What department is at this point?" -> type="departement", geom={"type":"Point",...}
    - "Get regions intersecting this polygon" -> type="region", geom=...`,
      inputSchema: z.object({
        type: z
          .enum(["commune", "departement", "region"] as const)
          .describe("Administrative boundary type"),
        geom: GeometrySchema.optional(),
        lon: z.number().optional().describe("Longitude coordinate (use with lat)"),
        lat: z.number().optional().describe("Latitude coordinate (use with lon)"),
        ...PaginationSchema,
        response_format: ResponseFormatSchema,
      }).strict(),
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },
    async (params) => {
      const { type, response_format, ...queryParams } = params;
      const endpoint = `/limites-administratives/${type}`;
  
      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,
        `Limites administratives - ${type}`
      );
      return {
        content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }],
      };
    }
  );