Visio Diagram Automation

naftiko: "1.0.0-alpha1"

info:
  label: "Visio Diagram Automation"
  description: >-
    Workflow capability for automating Visio diagram inspection, data extraction,
    and visual presentation via the Visio JavaScript API embedded in SharePoint Online.
    Used by developers and business analysts to programmatically read diagram content,
    extract business data from shapes, navigate pages, and update visual highlighting
    for interactive dashboard experiences.
  tags:
    - Business Process
    - Collaboration
    - Diagrams
    - Microsoft 365
    - Office Add-Ins
    - SharePoint
    - Visualization
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VISIO_EMBEDDED_SESSION: VISIO_EMBEDDED_SESSION

capability:
  consumes:
    - import: visio-javascript
      location: ./shared/visio-javascript.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: visio-automation-api
      description: "Unified REST API for Visio diagram automation and data extraction."
      resources:
        - path: /v1/document
          name: document
          description: "Current Visio document"
          operations:
            - method: GET
              name: get-document
              description: "Get the active Visio document and its settings"
              call: "visio-javascript.get-document"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages
          name: pages
          description: "Visio diagram pages"
          operations:
            - method: GET
              name: list-pages
              description: "List all pages in the Visio diagram"
              call: "visio-javascript.list-pages"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/active
          name: active-page
          description: "Currently active Visio page"
          operations:
            - method: GET
              name: get-active-page
              description: "Get the currently active Visio page"
              call: "visio-javascript.get-active-page"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}
          name: page
          description: "Individual Visio page"
          operations:
            - method: GET
              name: get-page
              description: "Get a specific Visio page by name"
              call: "visio-javascript.get-page"
              with:
                pageName: "rest.pageName"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}/shapes
          name: shapes
          description: "Shapes on a Visio page"
          operations:
            - method: GET
              name: list-shapes
              description: "List all shapes on the specified page"
              call: "visio-javascript.list-shapes"
              with:
                pageName: "rest.pageName"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}/shapes/{shapeId}
          name: shape
          description: "Individual shape on a Visio page"
          operations:
            - method: GET
              name: get-shape
              description: "Get a specific shape by ID"
              call: "visio-javascript.get-shape"
              with:
                pageName: "rest.pageName"
                shapeId: "rest.shapeId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}/shapes/{shapeId}/data
          name: shape-data
          description: "Structured business data embedded in a shape"
          operations:
            - method: GET
              name: list-shape-data-items
              description: "Extract all structured data items from a shape"
              call: "visio-javascript.list-shape-data-items"
              with:
                pageName: "rest.pageName"
                shapeId: "rest.shapeId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}/shapes/{shapeId}/hyperlinks
          name: shape-hyperlinks
          description: "Hyperlinks attached to a shape"
          operations:
            - method: GET
              name: list-shape-hyperlinks
              description: "List all hyperlinks on a shape"
              call: "visio-javascript.list-shape-hyperlinks"
              with:
                pageName: "rest.pageName"
                shapeId: "rest.shapeId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/pages/{pageName}/shapes/{shapeId}/comments
          name: shape-comments
          description: "Comments on a shape"
          operations:
            - method: GET
              name: list-shape-comments
              description: "List all comments on a shape"
              call: "visio-javascript.list-shape-comments"
              with:
                pageName: "rest.pageName"
                shapeId: "rest.shapeId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: visio-automation-mcp
      transport: http
      description: "MCP server for AI-assisted Visio diagram analysis and automation."
      tools:
        - name: get-document
          description: "Get the active Visio document properties and settings"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.get-document"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-pages
          description: "List all pages in the embedded Visio diagram"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.list-pages"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-active-page
          description: "Get the currently active page in the Visio diagram"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.get-active-page"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-page
          description: "Get a specific Visio page by name"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.get-page"
          with:
            pageName: "tools.pageName"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-shapes
          description: "List all shapes on a named Visio page"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.list-shapes"
          with:
            pageName: "tools.pageName"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-shape
          description: "Get details of a specific shape including text and bounding box"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.get-shape"
          with:
            pageName: "tools.pageName"
            shapeId: "tools.shapeId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-shape-data-items
          description: "Extract business data items stored in a shape"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.list-shape-data-items"
          with:
            pageName: "tools.pageName"
            shapeId: "tools.shapeId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-shape-hyperlinks
          description: "List hyperlinks embedded in a Visio shape"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.list-shape-hyperlinks"
          with:
            pageName: "tools.pageName"
            shapeId: "tools.shapeId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-shape-comments
          description: "Read comments attached to a Visio shape"
          hints:
            readOnly: true
            idempotent: true
          call: "visio-javascript.list-shape-comments"
          with:
            pageName: "tools.pageName"
            shapeId: "tools.shapeId"
          outputParameters:
            - type: object
              mapping: "$."