naftiko: 1.0.0-alpha2
info:
  label: Sage Accounting and Finance
  description: Unified workflow for accounting and financial management using Sage Accounting API v3.1. Covers contacts, invoicing,
    payment recording, bank reconciliation, and financial reporting. Used by accountants, bookkeepers, and finance teams to
    manage business finances.
  tags:
  - Accounting
  - ERP
  - Finance
  - Invoicing
  - Payments
  - Cloud Software
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SAGE_ACCESS_TOKEN: SAGE_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: sage-accounting
    baseUri: https://api.accounting.sage.com/v3.1
    description: Sage Accounting API v3.1
    authentication:
      type: bearer
      token: '{{SAGE_ACCESS_TOKEN}}'
    resources:
    - name: contacts
      path: /contacts
      description: Customer and supplier contact management
      operations:
      - name: list-contacts
        method: GET
        description: List customer and supplier contacts
        inputParameters:
        - name: contact_type_ids
          in: query
          type: string
          required: false
          description: 'Filter by contact type: CUSTOMER or SUPPLIER'
        - name: search
          in: query
          type: string
          required: false
          description: Search by name or reference
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-contact
        method: POST
        description: Create a new customer or supplier contact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            contact:
              name: '{{tools.name}}'
              contact_type_ids: '{{tools.contact_type_ids}}'
              email: '{{tools.email}}'
    - name: contact-detail
      path: /contacts/{key}
      description: Individual contact operations
      operations:
      - name: get-contact
        method: GET
        description: Get contact details by ID
        inputParameters:
        - name: key
          in: path
          type: string
          required: true
          description: Contact unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-contact
        method: PUT
        description: Update a contact's details
        inputParameters:
        - name: key
          in: path
          type: string
          required: true
          description: Contact unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            contact:
              name: '{{tools.name}}'
              email: '{{tools.email}}'
    - name: sales-invoices
      path: /sales_invoices
      description: Sales invoice management
      operations:
      - name: list-sales-invoices
        method: GET
        description: List sales invoices with optional filtering
        inputParameters:
        - name: contact_id
          in: query
          type: string
          required: false
          description: Filter by customer contact ID
        - name: status_id
          in: query
          type: string
          required: false
          description: 'Filter by status: DRAFT, SENT, PAID, VOID'
        - name: from_date
          in: query
          type: string
          required: false
          description: Filter from date (YYYY-MM-DD)
        - name: to_date
          in: query
          type: string
          required: false
          description: Filter to date (YYYY-MM-DD)
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-sales-invoice
        method: POST
        description: Create a new sales invoice
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            sales_invoice:
              contact_id: '{{tools.contact_id}}'
              date: '{{tools.date}}'
              due_date: '{{tools.due_date}}'
              reference: '{{tools.reference}}'
              line_items: '{{tools.line_items}}'
    - name: sales-invoice-detail
      path: /sales_invoices/{key}
      description: Individual sales invoice operations
      operations:
      - name: get-sales-invoice
        method: GET
        description: Get sales invoice details
        inputParameters:
        - name: key
          in: path
          type: string
          required: true
          description: Invoice unique identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sales-invoice-payments
      path: /sales_invoices/{key}/payments
      description: Sales invoice payment recording
      operations:
      - name: record-sales-payment
        method: POST
        description: Record a payment received for a sales invoice
        inputParameters:
        - name: key
          in: path
          type: string
          required: true
          description: Invoice ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            payment:
              payment_type_id: '{{tools.payment_type_id}}'
              bank_account_id: '{{tools.bank_account_id}}'
              date: '{{tools.date}}'
              amount: '{{tools.amount}}'
    - name: purchase-invoices
      path: /purchase_invoices
      description: Purchase invoice management
      operations:
      - name: list-purchase-invoices
        method: GET
        description: List purchase invoices (supplier bills)
        inputParameters:
        - name: contact_id
          in: query
          type: string
          required: false
          description: Filter by supplier contact ID
        - name: status_id
          in: query
          type: string
          required: false
          description: Filter by status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-purchase-invoice
        method: POST
        description: Create a new purchase invoice (supplier bill)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            purchase_invoice:
              contact_id: '{{tools.contact_id}}'
              date: '{{tools.date}}'
              due_date: '{{tools.due_date}}'
              line_items: '{{tools.line_items}}'
    - name: bank-accounts
      path: /bank_accounts
      description: Bank account management
      operations:
      - name: list-bank-accounts
        method: GET
        description: List bank accounts connected to the business
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: products
      path: /products
      description: Product and service catalog
      operations:
      - name: list-products
        method: GET
        description: List products and services
        inputParameters:
        - name: search
          in: query
          type: string
          required: false
          description: Search by product name
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-product
        method: POST
        description: Create a new product or service
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            product:
              description: '{{tools.description}}'
              item_code: '{{tools.item_code}}'
    - name: tax-rates
      path: /tax_rates
      description: Tax rate configuration
      operations:
      - name: list-tax-rates
        method: GET
        description: List configured tax rates
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ledger-accounts
      path: /ledger_accounts
      description: Chart of accounts
      operations:
      - name: list-ledger-accounts
        method: GET
        description: List ledger accounts (chart of accounts)
        inputParameters:
        - name: visible_in
          in: query
          type: string
          required: false
          description: Filter by visibility context
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: accounting-finance-api
    description: Unified REST API for Sage accounting and finance management.
    resources:
    - path: /v1/contacts
      name: contacts
      description: Customer and supplier contact management
      operations:
      - method: GET
        name: list-contacts
        description: List customers and suppliers
        call: sage-accounting.list-contacts
        with:
          contact_type_ids: rest.contact_type_ids
          search: rest.search
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-contact
        description: Create a new customer or supplier
        call: sage-accounting.create-contact
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contacts/{id}
      name: contact-detail
      description: Individual contact operations
      operations:
      - method: GET
        name: get-contact
        description: Get contact details
        call: sage-accounting.get-contact
        with:
          key: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: update-contact
        description: Update contact details
        call: sage-accounting.update-contact
        with:
          key: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sales-invoices
      name: sales-invoices
      description: Sales invoice management
      operations:
      - method: GET
        name: list-sales-invoices
        description: List sales invoices with filtering by customer, status, and date
        call: sage-accounting.list-sales-invoices
        with:
          contact_id: rest.contact_id
          status_id: rest.status_id
          from_date: rest.from_date
          to_date: rest.to_date
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-sales-invoice
        description: Create a new sales invoice
        call: sage-accounting.create-sales-invoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sales-invoices/{id}
      name: sales-invoice-detail
      description: Individual sales invoice
      operations:
      - method: GET
        name: get-sales-invoice
        description: Get sales invoice details
        call: sage-accounting.get-sales-invoice
        with:
          key: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sales-invoices/{id}/payments
      name: sales-invoice-payments
      description: Sales invoice payments
      operations:
      - method: POST
        name: record-sales-payment
        description: Record a payment received for a sales invoice
        call: sage-accounting.record-sales-payment
        with:
          key: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/purchase-invoices
      name: purchase-invoices
      description: Purchase invoice (supplier bill) management
      operations:
      - method: GET
        name: list-purchase-invoices
        description: List purchase invoices
        call: sage-accounting.list-purchase-invoices
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-purchase-invoice
        description: Create a new purchase invoice
        call: sage-accounting.create-purchase-invoice
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/bank-accounts
      name: bank-accounts
      description: Bank account management
      operations:
      - method: GET
        name: list-bank-accounts
        description: List bank accounts
        call: sage-accounting.list-bank-accounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/products
      name: products
      description: Product and service catalog
      operations:
      - method: GET
        name: list-products
        description: List products and services
        call: sage-accounting.list-products
        with:
          search: rest.search
          page: rest.page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-product
        description: Create a new product or service
        call: sage-accounting.create-product
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ledger-accounts
      name: ledger-accounts
      description: Chart of accounts
      operations:
      - method: GET
        name: list-ledger-accounts
        description: List ledger accounts
        call: sage-accounting.list-ledger-accounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tax-rates
      name: tax-rates
      description: Tax rates
      operations:
      - method: GET
        name: list-tax-rates
        description: List configured tax rates
        call: sage-accounting.list-tax-rates
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: accounting-finance-mcp
    transport: http
    description: MCP server for AI-assisted accounting and financial management with Sage Accounting.
    tools:
    - name: list-contacts
      description: List customers and suppliers in Sage Accounting
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-contacts
      with:
        contact_type_ids: tools.contact_type_ids
        search: tools.search
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: create-contact
      description: Create a new customer or supplier contact in Sage Accounting
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: sage-accounting.create-contact
      with:
        name: tools.name
        contact_type_ids: tools.contact_type_ids
        email: tools.email
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contact
      description: Get details for a specific contact including balance and outstanding amounts
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.get-contact
      with:
        key: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-sales-invoices
      description: List sales invoices filtered by customer, status, or date range
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-sales-invoices
      with:
        contact_id: tools.contact_id
        status_id: tools.status_id
        from_date: tools.from_date
        to_date: tools.to_date
        page: tools.page
      outputParameters:
      - type: object
        mapping: $.
    - name: create-sales-invoice
      description: Create a new sales invoice with line items, due date, and customer reference
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: sage-accounting.create-sales-invoice
      with:
        contact_id: tools.contact_id
        date: tools.date
        due_date: tools.due_date
        reference: tools.reference
        line_items: tools.line_items
      outputParameters:
      - type: object
        mapping: $.
    - name: get-sales-invoice
      description: Get full details of a sales invoice including line items and payment status
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.get-sales-invoice
      with:
        key: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: record-sales-payment
      description: Record a payment received against a sales invoice
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: sage-accounting.record-sales-payment
      with:
        key: tools.invoice_id
        payment_type_id: tools.payment_type_id
        bank_account_id: tools.bank_account_id
        date: tools.date
        amount: tools.amount
      outputParameters:
      - type: object
        mapping: $.
    - name: list-purchase-invoices
      description: List purchase invoices (supplier bills) with filtering options
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-purchase-invoices
      with:
        contact_id: tools.contact_id
        status_id: tools.status_id
      outputParameters:
      - type: object
        mapping: $.
    - name: create-purchase-invoice
      description: Create a new purchase invoice (supplier bill) in Sage Accounting
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: sage-accounting.create-purchase-invoice
      with:
        contact_id: tools.contact_id
        date: tools.date
        due_date: tools.due_date
        line_items: tools.line_items
      outputParameters:
      - type: object
        mapping: $.
    - name: list-bank-accounts
      description: List bank accounts connected to the Sage Accounting business
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-bank-accounts
      outputParameters:
      - type: object
        mapping: $.
    - name: list-products
      description: List products and services in the Sage catalog
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-products
      with:
        search: tools.search
      outputParameters:
      - type: object
        mapping: $.
    - name: create-product
      description: Create a new product or service in Sage Accounting
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: sage-accounting.create-product
      with:
        description: tools.description
        item_code: tools.item_code
      outputParameters:
      - type: object
        mapping: $.
    - name: list-ledger-accounts
      description: List chart of accounts (ledger accounts) for financial reporting
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-ledger-accounts
      outputParameters:
      - type: object
        mapping: $.
    - name: list-tax-rates
      description: List configured tax rates for invoice line items
      hints:
        readOnly: true
        openWorld: false
      call: sage-accounting.list-tax-rates
      outputParameters:
      - type: object
        mapping: $.