list_instances
Retrieve a paginated list of Civo cloud instances, optionally filtered by region.
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)The tool handler for 'list_instances' - calls listInstances API, formats the output with hostname, ID, status, and public IP.
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/tools/instances.ts:36-58 (schema)The tool schema definition for 'list_instances' - includes name, description, and inputSchema with optional region, page, and per_page parameters.
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:72-72 (registration)Registration of LIST_INSTANCES_TOOL in the server's capabilities.
[LIST_INSTANCES_TOOL.name]: LIST_INSTANCES_TOOL, - src/api/instances.ts:43-69 (helper)The API helper function that makes the actual HTTP GET request to Civo's /v2/instances endpoint with optional query parameters (region, page, per_page).
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/api/civo.ts:52-57 (helper)The CivoInstanceList interface defining the response shape (items array, page, per_page, pages) returned by listInstances.
export interface CivoInstanceList { items: CivoInstance[]; page: number; per_page: number; pages: number; }