get_invoice

Instructions

Implementation Reference

• src/tools/invoices.ts:65-99 (handler)

  The tool handler for 'get_invoice'. It accepts an invoice_id, calls client.getInvoice(), and returns formatted invoice details including number, patient, practitioner, status, issue date, total, and item count.

    server.tool('get_invoice', {
      description: 'Get details of a specific invoice (READ-ONLY)',
      inputSchema: {
        type: 'object',
        properties: {
          invoice_id: { type: 'number', description: 'Invoice ID' }
        },
        required: ['invoice_id']
      },
    }, async ({ invoice_id }: { invoice_id: number }) => {
      try {
        const invoice = await client.getInvoice(invoice_id);
        
        return {
          content: [{
            type: 'text',
            text: `Invoice #${invoice.invoice_number || invoice.id}:
  - Patient: ${invoice.patient?.name}
  - Practitioner: ${invoice.practitioner?.name}
  - Status: ${invoice.status}
  - Issue Date: ${invoice.issued_at}
  - Total: $${invoice.total || 0}
  - Items: ${invoice.invoice_items?.length || 0} items`
          }],
          data: invoice
        };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `Error fetching invoice: ${error instanceof Error ? error.message : String(error)}`
          }]
        };
      }
    });

• src/tools/invoices.ts:66-73 (schema)

  Input schema for the get_invoice tool: requires invoice_id (number).

  description: 'Get details of a specific invoice (READ-ONLY)',
  inputSchema: {
    type: 'object',
    properties: {
      invoice_id: { type: 'number', description: 'Invoice ID' }
    },
    required: ['invoice_id']
  },

• src/index.ts:10-63 (registration)

  The tool is registered in index.ts by importing registerInvoiceTools from './tools/invoices.js' and calling it at line 62.

  import { registerInvoiceTools } from './tools/invoices.js';
  import { registerDemoInvoiceTools } from './tools/demo-invoice-generation.js';
  import { registerResources } from './resources/index.js';
  
  const API_KEY = process.env.CLINIKO_API_KEY;
  
  if (!API_KEY) {
    // Exit silently if no API key - MCP protocol doesn't allow stderr output
    process.exit(1);
  }
  
  // Initialize MCP server
  const server = new Server(
    {
      name: 'mcp-cliniko',
      version: '1.0.0',
    },
    {
      capabilities: {
        tools: {},
        resources: {},
        prompts: {},
      },
    }
  );
  
  // Initialize Cliniko client
  const clinikoClient = new ClinikoClient(API_KEY);
  
  // Track registered tools and resources
  const tools = new Map();
  const resources = new Map();
  
  // Helper to register tools
  const toolRegistry = {
    tool(name: string, schema: any, handler: any) {
      tools.set(name, { schema, handler });
    }
  };
  
  // Helper to register resources
  const resourceRegistry = {
    resource(uriTemplate: string, options: any, handler: any) {
      resources.set(uriTemplate, { ...options, handler, uriTemplate });
    }
  };
  
  // Register all tools
  registerPatientTools(toolRegistry, clinikoClient);
  registerAppointmentTools(toolRegistry, clinikoClient);
  registerSyntheticDataTools(toolRegistry, clinikoClient);
  registerEnhancedSyntheticDataTools(toolRegistry, clinikoClient);
  registerInvoiceTools(toolRegistry, clinikoClient);
  registerDemoInvoiceTools(toolRegistry, clinikoClient);

• src/cliniko-client.ts:224-226 (helper)

  The ClinikoClient.getInvoice(id) method that performs the HTTP GET request to /invoices/{id} and returns the Invoice object.

  async getInvoice(id: number): Promise<Invoice> {
    return this.request<Invoice>(`/invoices/${id}`);
  }

• src/types.ts:138-182 (helper)

  TypeScript interface for Invoice, defining all fields returned from the API including patient, practitioner, business, invoice_items, etc.

  export interface Invoice {
    id: number;
    invoice_number?: string;
    issued_at: string;
    due_at?: string;
    status: 'draft' | 'awaiting_payment' | 'part_paid' | 'paid' | 'void' | 'write_off';
    total: number;
    tax_total: number;
    subtotal: number;
    amount_paid: number;
    amount_outstanding: number;
    notes?: string;
    payment_terms?: number;
    patient: {
      id: number;
      name: string;
      links: {
        self: string;
      };
    };
    practitioner: {
      id: number;
      name: string;
      links: {
        self: string;
      };
    };
    business: {
      id: number;
      name: string;
      links: {
        self: string;
      };
    };
    invoice_items?: InvoiceItem[];
    created_at: string;
    updated_at: string;
    links?: {
      self: string;
      patient: string;
      practitioner: string;
      invoice_items?: string;
      payments?: string;
    };
  }