volkern_create_contrato

Create new contracts in Volkern CRM by specifying title, type, dates, payment method, and terms to formalize agreements with clients.

Instructions

Create a new contract

Input Schema

TableJSON Schema

Name	Required	Description
`titulo`	Yes	Contract title (required)
`tipo`	No
`leadId`	No	Associated lead ID
`dealId`	No	Associated deal ID
`cotizacionId`	No	Source quotation ID
`fechaInicio`	No	Contract start date (YYYY-MM-DD)
`fechaFin`	No	Contract end date (YYYY-MM-DD)
`metodoPago`	No
`clausulas`	No	Contract terms and conditions
`items`	No

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

Volkern MCP Server