apogeoapi-mcp

Instructions

Implementation Reference

• src/tools/cities.ts:6-24 (registration)

  The 'get_cities' tool is registered on the McpServer here, which includes both the tool definition (schema) and the execution logic (handler).

  server.tool(
    'get_cities',
    'Get all cities for a state/province by state ID. Requires Starter plan or above.',
    {
      state_id: z.number().int().positive().describe('Numeric state ID (from get_states response)'),
      page: z.number().int().positive().optional(),
      limit: z.number().int().min(1).max(100).optional(),
      fields: z.enum(['basic', 'standard', 'full']).optional(),
    },
    async ({ state_id, page, limit, fields }) => {
      const params = new URLSearchParams();
      if (page) params.set('page', String(page));
      if (limit) params.set('limit', String(limit));
      if (fields) params.set('fields', fields);
      const qs = params.toString() ? `?${params}` : '';
      const data = await apiGet(`/v1/api/geo/states/${state_id}/cities${qs}`);
      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/tools/cities.ts:15-23 (handler)

  The execution handler for the 'get_cities' tool, which performs the API call to fetch city data.

  async ({ state_id, page, limit, fields }) => {
    const params = new URLSearchParams();
    if (page) params.set('page', String(page));
    if (limit) params.set('limit', String(limit));
    if (fields) params.set('fields', fields);
    const qs = params.toString() ? `?${params}` : '';
    const data = await apiGet(`/v1/api/geo/states/${state_id}/cities${qs}`);
    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
  }

• src/tools/cities.ts:9-14 (schema)

  The input schema definition for the 'get_cities' tool using Zod.

  {
    state_id: z.number().int().positive().describe('Numeric state ID (from get_states response)'),
    page: z.number().int().positive().optional(),
    limit: z.number().int().min(1).max(100).optional(),
    fields: z.enum(['basic', 'standard', 'full']).optional(),
  },