Volkern MCP Server

Instructions

Implementation Reference

• src/index.ts:794-795 (handler)

  The handler for volkern_create_cita tool - a switch case that calls volkernRequest to POST appointment data to the /citas endpoint

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

• src/index.ts:184-204 (schema)

  Tool schema definition for volkern_create_cita - defines the tool name, description, and inputSchema with properties for leadId, fechaHora, tipo, titulo, descripcion, duracion, and servicioId

  {
    name: "volkern_create_cita",
    description: "Create a new appointment. Check availability first with volkern_check_disponibilidad.",
    inputSchema: {
      type: "object",
      properties: {
        leadId: { type: "string", description: "ID of the lead for this appointment" },
        fechaHora: { type: "string", description: "Appointment date/time in ISO 8601 UTC (e.g., 2026-02-10T10:00:00Z)" },
        tipo: {
          type: "string",
          enum: ["reunion", "servicio", "llamada", "otro"],
          description: "Appointment type (default: reunion)"
        },
        titulo: { type: "string", description: "Appointment title" },
        descripcion: { type: "string", description: "Appointment description or notes" },
        duracion: { type: "number", description: "Duration in minutes (default: 60)" },
        servicioId: { type: "string", description: "Service ID (required if tipo is 'servicio')" }
      },
      required: ["leadId", "fechaHora"]
    }
  },

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

  The volkernRequest helper function used by the handler - makes HTTP requests to the Volkern API with authentication headers and handles responses/errors

  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:754-795 (handler)

  The complete handleToolCall function that contains the switch statement routing tool calls to their respective handlers, including volkern_create_cita

  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);

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

  The CallToolRequestSchema handler registration that receives tool call requests and delegates to handleToolCall function

  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}`,
          },
        ],
        isError: true,
      };
    }
  });