create_instance

Instructions

Implementation Reference

• src/tools/instances.ts:3-34 (schema)

  Tool schema definition for create_instance, including name, description, and inputSchema with properties: hostname, size, template_id, count, region. Required fields: hostname, size, template_id.

  export const CREATE_INSTANCE_TOOL: Tool = {
    name: 'create_instance',
    description: 'Create a new cloud instance on Civo',
    inputSchema: {
      type: 'object',
      properties: {
        hostname: {
          type: 'string',
          description: 'Fully qualified domain name',
        },
        size: {
          type: 'string',
          description: 'Instance size (e.g. g2.small)',
        },
        template_id: {
          type: 'string',
          description: 'Disk image ID',
        },
        count: {
          type: 'number',
          description: 'Number of instances to create',
          default: 1,
        },
        region: {
          type: 'string',
          description: 'Region identifier',
          default: 'LON1',
        },
      },
      required: ['hostname', 'size', 'template_id'],
    },
  };

• src/index.ts:129-156 (handler)

  Request handler for the 'create_instance' tool in the CallToolRequestSchema switch statement. Validates arguments, calls the createInstance API function, and returns a formatted response with the created instance's hostname and ID.

  case 'create_instance': {
    if (
      typeof args !== 'object' ||
      args === null ||
      typeof args.hostname !== 'string' ||
      typeof args.size !== 'string' ||
      typeof args.template_id !== 'string'
    ) {
      throw new Error('Invalid arguments for create_instance');
    }
  
    const instance = await createInstance({
      hostname: args.hostname as string,
      size: args.size as string,
      template_id: args.template_id as string,
      count: args.count as number | undefined,
      region: args.region as string | undefined,
    });
    return {
      content: [
        {
          type: 'text',
          text: `Created instance ${instance.hostname} (ID: ${instance.id})`,
        },
      ],
      isError: false,
    };
  }

• src/api/instances.ts:9-41 (handler)

  The actual API implementation of createInstance. Makes a POST request to Civo API /instances endpoint with form-encoded parameters (hostname, size, template_id, count, region), checks rate limit, and returns the created CivoInstance.

  export async function createInstance(params: {
    hostname: string;
    size: string;
    template_id: string;
    count?: number;
    region?: string;
  }): Promise<CivoInstance> {
    checkRateLimit();
  
    const url = `${CIVO_API_URL}/instances`;
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${CIVO_API_KEY}`,
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        hostname: params.hostname,
        size: params.size,
        template_id: params.template_id,
        count: params.count?.toString() || '1',
        region: params.region || 'LON1',
      }),
    });
  
    if (!response.ok) {
      throw new Error(
        `Civo API error: ${response.status} ${response.statusText}`
      );
    }
  
    return response.json();
  }

• src/index.ts:71-93 (registration)

  Registration of CREATE_INSTANCE_TOOL in the server's capabilities under the tools object.

          [CREATE_INSTANCE_TOOL.name]: CREATE_INSTANCE_TOOL,
          [LIST_INSTANCES_TOOL.name]: LIST_INSTANCES_TOOL,
          [REBOOT_INSTANCE_TOOL.name]: REBOOT_INSTANCE_TOOL,
          [SHUTDOWN_INSTANCE_TOOL.name]: SHUTDOWN_INSTANCE_TOOL,
          [START_INSTANCE_TOOL.name]: START_INSTANCE_TOOL,
          [RESIZE_INSTANCE_TOOL.name]: RESIZE_INSTANCE_TOOL,
          [DELETE_INSTANCE_TOOL.name]: DELETE_INSTANCE_TOOL,
          [LIST_DISK_IMAGES_TOOL.name]: LIST_DISK_IMAGES_TOOL,
          [GET_DISK_IMAGE_TOOL.name]: GET_DISK_IMAGE_TOOL,
          [LIST_SIZES_TOOL.name]: LIST_SIZES_TOOL,
          [LIST_REGIONS_TOOL.name]: LIST_REGIONS_TOOL,
          [LIST_NETWORKS_TOOL.name]: LIST_NETWORKS_TOOL,
          [CREATE_NETWORK_TOOL.name]: CREATE_NETWORK_TOOL,
          [RENAME_NETWORK_TOOL.name]: RENAME_NETWORK_TOOL,
          [DELETE_NETWORK_TOOL.name]: DELETE_NETWORK_TOOL,
          [LIST_KUBERNETES_CLUSTERS_TOOL.name]: LIST_KUBERNETES_CLUSTERS_TOOL,
          [CREATE_KUBERNETES_CLUSTER_TOOL.name]: CREATE_KUBERNETES_CLUSTER_TOOL,
          [DELETE_KUBERNETES_CLUSTER_TOOL.name]: DELETE_KUBERNETES_CLUSTER_TOOL,
          [LIST_KUBERNETES_VERSIONS_TOOL.name]: LIST_KUBERNETES_VERSIONS_TOOL,
        },
      },
    }
  );

• src/api/civo.ts:25-39 (helper)

  Rate limiting helper (checkRateLimit) used by createInstance to enforce API call limits.

  export function checkRateLimit() {
    const now = Date.now();
    if (now - requestCount.lastReset > 1000) {
      requestCount.second = 0;
      requestCount.lastReset = now;
    }
    if (
      requestCount.second >= RATE_LIMIT.perSecond ||
      requestCount.month >= RATE_LIMIT.perMonth
    ) {
      throw new Error('Rate limit exceeded');
    }
    requestCount.second++;
    requestCount.month++;
  }