volkern_cita_accion

Instructions

Implementation Reference

• src/index.ts:800-801 (handler)

  The handler case for 'volkern_cita_accion' that processes appointment actions by calling volkernRequest('/citas/accion', 'POST', args). This executes the tool logic by making a POST request to the Volkern API's /citas/accion endpoint.

  case "volkern_cita_accion":
    return volkernRequest("/citas/accion", "POST", args);

• src/index.ts:26-55 (helper)

  The volkernRequest helper function that performs the actual HTTP request to the Volkern API. It constructs the request with proper authentication (Bearer token), headers, and body, then handles the response and error cases.

  async function volkernRequest(
    endpoint: string,
    method: string = "GET",
    body?: Record<string, unknown>
  ): Promise<unknown> {
    const url = `${VOLKERN_API_URL}${endpoint}`;
    
    const options: RequestInit = {
      method,
      headers: {
        "Authorization": `Bearer ${VOLKERN_API_KEY}`,
        "Content-Type": "application/json",
      },
    };
  
    if (body && method !== "GET") {
      options.body = JSON.stringify(body);
    }
  
    const response = await fetch(url, options);
    
    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        `Volkern API Error (${response.status}): ${JSON.stringify(errorData)}`
      );
    }
  
    return response.json();
  }

• src/index.ts:220-235 (schema)

  Tool registration and schema definition for 'volkern_cita_accion'. Defines the tool name, description, and inputSchema with properties: citaId (required), accion (required, enum: confirmar/cancelar/reprogramar), nuevaFecha, and motivo.

  {
    name: "volkern_cita_accion",
    description: "Perform an action on an appointment (confirm, cancel, or reschedule)",
    inputSchema: {
      type: "object",
      properties: {
        citaId: { type: "string", description: "The appointment's unique ID" },
        accion: {
          type: "string",
          enum: ["confirmar", "cancelar", "reprogramar"],
          description: "Action to perform"
        },
        nuevaFecha: { type: "string", description: "New date/time for reschedule (ISO 8601)" },
        motivo: { type: "string", description: "Reason for cancellation" }
      },
      required: ["citaId", "accion"]

• src/index.ts:754-801 (handler)

  The handleToolCall function that routes all tool calls to their respective handlers using a switch statement. This is the main dispatcher that processes tool invocations and calls the appropriate logic for each tool.

  async function handleToolCall(
    name: string,
    args: Record<string, unknown>
  ): Promise<unknown> {
    switch (name) {
      // LEADS
      case "volkern_list_leads": {
        const params = new URLSearchParams();
        if (args.estado) params.append("estado", String(args.estado));
        if (args.canal) params.append("canal", String(args.canal));
        if (args.search) params.append("search", String(args.search));
        if (args.page) params.append("page", String(args.page));
        if (args.limit) params.append("limit", String(args.limit));
        return volkernRequest(`/leads?${params.toString()}`);
      }
      case "volkern_get_lead":
        return volkernRequest(`/leads/${args.leadId}`);
      case "volkern_create_lead":
        return volkernRequest("/leads", "POST", args);
      case "volkern_update_lead": {
        const { leadId, ...data } = args;
        return volkernRequest(`/leads/${leadId}`, "PATCH", data);
      }
  
      // APPOINTMENTS
      case "volkern_check_disponibilidad": {
        const params = new URLSearchParams();
        params.append("fecha", String(args.fecha));
        if (args.duracion) params.append("duracion", String(args.duracion));
        return volkernRequest(`/citas/disponibilidad?${params.toString()}`);
      }
      case "volkern_list_citas": {
        const params = new URLSearchParams();
        if (args.estado) params.append("estado", String(args.estado));
        if (args.tipo) params.append("tipo", String(args.tipo));
        if (args.fecha) params.append("fecha", String(args.fecha));
        if (args.fechaInicio) params.append("fechaInicio", String(args.fechaInicio));
        if (args.fechaFin) params.append("fechaFin", String(args.fechaFin));
        return volkernRequest(`/citas?${params.toString()}`);
      }
      case "volkern_create_cita":
        return volkernRequest("/citas", "POST", args);
      case "volkern_update_cita": {
        const { citaId, ...data } = args;
        return volkernRequest(`/citas/${citaId}`, "PATCH", data);
      }
      case "volkern_cita_accion":
        return volkernRequest("/citas/accion", "POST", args);

• src/index.ts:961-980 (registration)

  The MCP server CallToolRequestSchema handler that receives tool call requests, extracts the tool name and arguments, invokes handleToolCall, and returns the formatted response or error message.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    try {
      const result = await handleToolCall(name, args as Record<string, unknown>);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error: ${errorMessage}`,