volkern_create_contrato

Instructions

Implementation Reference

• src/index.ts:926-927 (handler)

  The handler case for 'volkern_create_contrato' that creates a new contract by making a POST request to the /contratos endpoint with the provided arguments.

  case "volkern_create_contrato":
    return volkernRequest("/contratos", "POST", args);

• src/index.ts:692-720 (schema)

  The input schema definition for 'volkern_create_contrato' tool, defining required 'titulo' field and optional fields like 'tipo', 'leadId', 'dealId', 'cotizacionId', 'fechaInicio', 'fechaFin', 'metodoPago', 'clausulas', and 'items'.

  {
    name: "volkern_create_contrato",
    description: "Create a new contract",
    inputSchema: {
      type: "object",
      properties: {
        titulo: { type: "string", description: "Contract title (required)" },
        tipo: { type: "string", enum: ["servicios", "productos", "suscripcion", "proyecto", "otro"] },
        leadId: { type: "string", description: "Associated lead ID" },
        dealId: { type: "string", description: "Associated deal ID" },
        cotizacionId: { type: "string", description: "Source quotation ID" },
        fechaInicio: { type: "string", description: "Contract start date (YYYY-MM-DD)" },
        fechaFin: { type: "string", description: "Contract end date (YYYY-MM-DD)" },
        metodoPago: { type: "string", enum: ["unico", "mensual", "trimestral", "anual"] },
        clausulas: { type: "string", description: "Contract terms and conditions" },
        items: {
          type: "array",
          items: {
            type: "object",
            properties: {
              concepto: { type: "string" },
              cantidad: { type: "number" },
              precioUnitario: { type: "number" }
            }
          }
        }
      },
      required: ["titulo"]
    }

• src/index.ts:955-958 (registration)

  Registration of tools via ListToolsRequestSchema handler that returns the tools array to the MCP server.

  // List available tools
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });

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

  The main handleToolCall function that contains all tool implementations including the switch statement routing to the appropriate API calls.

  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);
  
      // SERVICES
      case "volkern_list_servicios": {
        const params = new URLSearchParams();
        if (args.activo !== undefined) params.append("activo", String(args.activo));
        return volkernRequest(`/servicios?${params.toString()}`);
      }
      case "volkern_get_servicio":
        return volkernRequest(`/servicios/${args.servicioId}`);
  
      // TASKS
      case "volkern_create_task": {
        const { leadId, ...taskData } = args;
        return volkernRequest(`/leads/${leadId}/tasks`, "POST", taskData);
      }
      case "volkern_list_tasks":
        return volkernRequest(`/leads/${args.leadId}/tasks`);
      case "volkern_complete_task":
        return volkernRequest(`/tasks/${args.taskId}`, "PATCH", { completada: true });
  
      // MESSAGING
      case "volkern_send_whatsapp":
        return volkernRequest("/mensajes/enviar", "POST", args);
      case "volkern_list_conversaciones": {
        const params = new URLSearchParams();
        if (args.leadId) params.append("leadId", String(args.leadId));
        if (args.page) params.append("page", String(args.page));
        if (args.limit) params.append("limit", String(args.limit));
        return volkernRequest(`/mensajes/conversaciones?${params.toString()}`);
      }
  
      // INTERACTIONS
      case "volkern_list_interactions":
        return volkernRequest(`/leads/${args.leadId}/interactions`);
      case "volkern_create_interaction": {
        const { leadId, ...interactionData } = args;
        return volkernRequest(`/leads/${leadId}/interactions`, "POST", interactionData);
      }
  
      // NOTES
      case "volkern_list_notes":
        return volkernRequest(`/leads/${args.leadId}/notes`);
      case "volkern_create_note": {
        const { leadId: noteLeadId, ...noteData } = args;
        return volkernRequest(`/leads/${noteLeadId}/notes`, "POST", noteData);
      }
  
      // CONTACTS / COMPANIES
      case "volkern_list_contacts": {
        const params = new URLSearchParams();
        if (args.tipo) params.append("tipo", String(args.tipo));
        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(`/contacts?${params.toString()}`);
      }
      case "volkern_get_contact":
        return volkernRequest(`/contacts/${args.contactId}`);
      case "volkern_create_contact":
        return volkernRequest("/contacts", "POST", args);
      case "volkern_update_contact": {
        const { contactId, ...contactData } = args;
        return volkernRequest(`/contacts/${contactId}`, "PATCH", contactData);
      }
  
      // DEALS / PIPELINE
      case "volkern_list_deals": {
        const params = new URLSearchParams();
        if (args.etapa) params.append("etapa", String(args.etapa));
        if (args.estado) params.append("estado", String(args.estado));
        if (args.prioridad) params.append("prioridad", String(args.prioridad));
        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(`/deals?${params.toString()}`);
      }
      case "volkern_get_deal":
        return volkernRequest(`/deals/${args.dealId}`);
      case "volkern_create_deal":
        return volkernRequest("/deals", "POST", args);
      case "volkern_update_deal": {
        const { dealId, ...dealData } = args;
        return volkernRequest(`/deals/${dealId}`, "PATCH", dealData);
      }
      case "volkern_list_pipeline_stages":
        return volkernRequest("/pipeline/stages");
      case "volkern_get_sales_forecast": {
        const params = new URLSearchParams();
        if (args.periodo) params.append("periodo", String(args.periodo));
        return volkernRequest(`/deals/forecast?${params.toString()}`);
      }
  
      // COTIZACIONES (QUOTES)
      case "volkern_list_cotizaciones": {
        const params = new URLSearchParams();
        if (args.estado) params.append("estado", String(args.estado));
        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(`/cotizaciones?${params.toString()}`);
      }
      case "volkern_get_cotizacion":
        return volkernRequest(`/cotizaciones/${args.cotizacionId}`);
      case "volkern_create_cotizacion":
        return volkernRequest("/cotizaciones", "POST", args);
      case "volkern_update_cotizacion": {
        const { cotizacionId, ...cotizacionData } = args;
        return volkernRequest(`/cotizaciones/${cotizacionId}`, "PATCH", cotizacionData);
      }
      case "volkern_send_cotizacion":
        return volkernRequest(`/cotizaciones/${args.cotizacionId}/send`, "POST", { mensaje: args.mensaje });
  
      // CONTRATOS (CONTRACTS)
      case "volkern_list_contratos": {
        const params = new URLSearchParams();
        if (args.estado) params.append("estado", String(args.estado));
        if (args.tipo) params.append("tipo", String(args.tipo));
        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(`/contratos?${params.toString()}`);
      }
      case "volkern_get_contrato":
        return volkernRequest(`/contratos/${args.contratoId}`);
      case "volkern_create_contrato":
        return volkernRequest("/contratos", "POST", args);
      case "volkern_create_contrato_from_cotizacion": {
        const { cotizacionId, ...contratoData } = args;
        return volkernRequest(`/contratos/from-cotizacion/${cotizacionId}`, "POST", contratoData);
      }
      case "volkern_send_contrato":
        return volkernRequest(`/contratos/${args.contratoId}/send`, "POST", { mensaje: args.mensaje });
  
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  }

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

  The volkernRequest helper function that handles HTTP requests to the Volkern API with authentication headers, error handling, and JSON response parsing.

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