Get Full Endpoint Details

Instructions

Implementation Reference

• src/tools/handlers/get-endpoint-details.ts:3-88 (handler)

  The handler function that executes the 'procore_get_endpoint_details' tool logic. It receives an operation_id, looks up details via getEndpointDetails() from the catalog service, and formats a human-readable response with parameters, request body, success/error responses.

  export async function handleGetEndpointDetails(args: {
    operation_id: string;
  }): Promise<string> {
    const detail = getEndpointDetails(args.operation_id);
  
    if (!detail) {
      return `Endpoint not found: ${args.operation_id}. Use procore_search_endpoints or procore_discover_endpoints to find valid operationIds.`;
    }
  
    const lines: string[] = [
      `## ${detail.method} ${detail.path}`,
      `**${detail.summary}**`,
      "",
    ];
  
    if (detail.description) {
      lines.push(detail.description, "");
    }
  
    // Parameters
    if (detail.parameters.length > 0) {
      lines.push("### Parameters");
      for (const p of detail.parameters) {
        const req = p.required ? " **(required)**" : "";
        const schemaStr = p.schema.type
          ? ` (${p.schema.type}${p.schema.format ? `, ${p.schema.format}` : ""})`
          : "";
        lines.push(
          `- \`${p.name}\` [${p.in}]${schemaStr}${req}: ${p.description}`
        );
        if (p.schema.enum) {
          lines.push(
            `  Values: ${(p.schema.enum as unknown[]).map((v) => `\`${v}\``).join(", ")}`
          );
        }
      }
      lines.push("");
    }
  
    // Request body
    if (detail.requestBody) {
      lines.push(`### Request Body (${detail.requestBody.contentType})`);
      if (detail.requestBody.required) {
        lines.push("**Required**");
      }
      lines.push("```json");
      lines.push(JSON.stringify(detail.requestBody.schema, null, 2));
      lines.push("```");
      lines.push("");
    }
  
    // Response schemas (just 200/201)
    const successCodes = Object.entries(detail.responses).filter(
      ([code]) => code === "200" || code === "201"
    );
    if (successCodes.length > 0) {
      lines.push("### Success Response");
      for (const [code, resp] of successCodes) {
        lines.push(`**${code}**: ${resp.description}`);
        if (resp.schema) {
          lines.push("```json");
          lines.push(
            JSON.stringify(resp.schema, null, 2).slice(0, 2000)
          );
          lines.push("```");
        }
      }
      lines.push("");
    }
  
    // Error codes
    const errorCodes = Object.entries(detail.responses)
      .filter(([code]) => code !== "200" && code !== "201")
      .map(([code, resp]) => `${code}: ${resp.description}`);
    if (errorCodes.length > 0) {
      lines.push("### Error Codes");
      lines.push(errorCodes.join(", "));
      lines.push("");
    }
  
    lines.push(
      "Use procore_api_call to execute this endpoint."
    );
  
    return lines.join("\n");
  }

• src/catalog/types.ts:28-51 (schema)

  The EndpointDetail type that defines the shape of data returned by getEndpointDetails(), including parameters, requestBody, and responses.

  export interface EndpointDetail {
    operationId: string;
    method: string;
    path: string;
    summary: string;
    description: string;
    tag: string;
    parameters: Array<{
      name: string;
      in: string;
      required: boolean;
      description: string;
      schema: Record<string, unknown>;
    }>;
    requestBody?: {
      contentType: string;
      required: boolean;
      schema: Record<string, unknown>;
    };
    responses: Record<
      string,
      { description: string; schema?: Record<string, unknown> }
    >;
  }

• src/tools/registry.ts:83-106 (registration)

  The tool registration for 'procore_get_endpoint_details' with input schema (operation_id string), annotations, and the handler wiring.

  // 3. Get Endpoint Details
  server.registerTool(
    "procore_get_endpoint_details",
    {
      title: "Get Full Endpoint Details",
      description:
        "Fetch the full parameter schema, request body shape, and response format for " +
        "a single Procore endpoint. Pass an `operation_id` from `procore_discover_endpoints`. " +
        "Use this right before calling `procore_api_call` so you know exactly which " +
        "path/query/body parameters to provide. Returns a JSON object.",
      inputSchema: {
        operation_id: z
          .string()
          .describe(
            "The operationId returned by procore_discover_endpoints, e.g. 'RestV10ProjectsProjectIdRfisGet'"
          ),
      },
      annotations: { title: "Get Endpoint Details", ...READ_ONLY },
    },
    async (args) => {
      const text = await handleGetEndpointDetails(args);
      return { content: [{ type: "text" as const, text }] };
    }
  );

• src/catalog/service.ts:81-91 (helper)

  The service-layer function getEndpointDetails() which delegates to loadEndpointDetail() in the repository.

  export function getEndpointDetails(
    operationId: string
  ): EndpointDetail | null {
    return loadEndpointDetail(operationId);
  }
  
  export function getEndpointByOperationId(
    operationId: string
  ): CatalogEntry | undefined {
    return findByOperationId(operationId);
  }

• src/catalog/repository.ts:27-39 (helper)

  The repository function loadEndpointDetail() that reads the endpoint detail JSON file from disk (data/endpoint-details/{operationId}.json).

  export function loadEndpointDetail(
    operationId: string
  ): EndpointDetail | null {
    try {
      const raw = readFileSync(
        join(DATA_DIR, "endpoint-details", `${operationId}.json`),
        "utf8"
      );
      return JSON.parse(raw) as EndpointDetail;
    } catch {
      return null;
    }
  }