Discover Procore API Categories

Instructions

Implementation Reference

• src/tools/registry.ts:25-41 (registration)

  Tool 'procore_discover_categories' is registered via server.registerTool with metadata (title, description, inputSchema) and a callback that delegates to handleDiscoverCategories.

  server.registerTool(
    "procore_discover_categories",
    {
      title: "Discover Procore API Categories",
      description:
        "List every Procore API category with its modules and endpoint counts. " +
        "Use this as the first step when exploring what Procore can do — it returns " +
        "a hierarchical map (Category > Module > endpoint count) that scopes any " +
        "follow-up discovery or search call. Returns a JSON object; takes no inputs.",
      inputSchema: {},
      annotations: { title: "Discover API Categories", ...READ_ONLY },
    },
    async () => {
      const text = await handleDiscoverCategories();
      return { content: [{ type: "text" as const, text }] };
    }
  );

• src/tools/handlers/discover-categories.ts:3-27 (handler)

  Main handler: fetches category index from the catalog service and formats it into a human-readable hierarchical string (Category > Module > endpoint count).

  export async function handleDiscoverCategories(): Promise<string> {
    const index = getCategories();
  
    const lines: string[] = [
      `Procore API — ${index.totalEndpoints} total endpoints across ${Object.keys(index.categories).length} categories\n`,
    ];
  
    for (const [name, data] of Object.entries(index.categories).sort(
      (a, b) => b[1].totalEndpoints - a[1].totalEndpoints
    )) {
      lines.push(`## ${name} (${data.totalEndpoints} endpoints)`);
      const modules = Object.entries(data.modules)
        .sort((a, b) => b[1].endpointCount - a[1].endpointCount)
        .map(([mod, info]) => `  - ${mod}: ${info.endpointCount} endpoints`)
        .join("\n");
      lines.push(modules);
      lines.push("");
    }
  
    lines.push(
      "Use procore_discover_endpoints with a category and optional module to see specific endpoints."
    );
  
    return lines.join("\n");
  }

• src/catalog/service.ts:9-11 (helper)

  Helper function that delegates to repository to load the category index from a JSON file.

  export function getCategories(): CategoryIndex {
    return loadCategories();
  }

• src/catalog/repository.ts:20-25 (helper)

  Loads cached categories.json data from disk with in-memory caching.

  export function loadCategories(): CategoryIndex {
    if (categoriesCache) return categoriesCache;
    const raw = readFileSync(join(DATA_DIR, "categories.json"), "utf8");
    categoriesCache = JSON.parse(raw) as CategoryIndex;
    return categoriesCache;
  }

• src/catalog/types.ts:16-26 (schema)

  Type definition for the CategoryIndex returned by the handler — defines the shape of categories, modules, and endpoint counts.

  export interface CategoryIndex {
    categories: Record<
      string,
      {
        modules: Record<string, { endpointCount: number; tags: string[] }>;
        totalEndpoints: number;
      }
    >;
    totalEndpoints: number;
    generatedAt: string;
  }