list_instances
Retrieve all cloud instances from Civo with optional region filtering and pagination controls for efficient infrastructure management.
Instructions
List all instances on Civo
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Filter by region | |
| page | No | Pagination page | |
| per_page | No | Results per page |
Implementation Reference
- src/index.ts:158-176 (handler)MCP tool handler implementation for 'list_instances': calls the listInstances API helper, formats the instance list into a text response.case 'list_instances': { const instances = await listInstances(args); const instanceList = instances.items .map( i => `${i.hostname} (${i.id}) - ${i.status} - Public IP: ${i.public_ip || 'None'}` ) .join('\n'); return { content: [ { type: 'text', text: `Instances:\n${instanceList}`, }, ], isError: false, }; }
- src/api/instances.ts:43-69 (helper)Helper function that performs the actual HTTP fetch to Civo API to list instances, handles params and rate limiting.export async function listInstances(params: { region?: string; page?: number; per_page?: number; }): Promise<CivoInstanceList> { checkRateLimit(); const url = new URL(`${CIVO_API_URL}/instances`); if (params.region) url.searchParams.set('region', params.region); if (params.page) url.searchParams.set('page', params.page.toString()); if (params.per_page) url.searchParams.set('per_page', params.per_page.toString()); const response = await fetch(url.toString(), { headers: { Authorization: `Bearer ${CIVO_API_KEY}`, }, }); if (!response.ok) { throw new Error( `Civo API error: ${response.status} ${response.statusText}` ); } return response.json(); }
- src/tools/instances.ts:36-58 (schema)Schema definition for the 'list_instances' tool: name, description, and inputSchema for validation.export const LIST_INSTANCES_TOOL: Tool = { name: 'list_instances', description: 'List all instances on Civo', inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'Filter by region', }, page: { type: 'number', description: 'Pagination page', default: 1, }, per_page: { type: 'number', description: 'Results per page', default: 20, }, }, }, };
- src/index.ts:70-90 (registration)Registration of 'list_instances' tool (and others) in the MCP server capabilities.tools object.tools: { [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, },