HomeAssistantVS/custom_components/ha_mcp_tools/services.yaml

edit_yaml_config:
  name: Edit YAML Config
  description: >-
    Add, replace, or remove a top-level key in configuration.yaml,
    package files, or theme files. Validates YAML, creates backups, and restricts edits
    to a whitelist of allowed keys.
  fields:
    file:
      name: File
      description: >-
        Relative path to the YAML file. Supports configuration.yaml,
        packages/*.yaml, and themes/*.yaml.
      required: true
      example: "configuration.yaml"
      selector:
        text:
    action:
      name: Action
      description: "Action to perform: add, replace, or remove."
      required: true
      example: "add"
      selector:
        select:
          options:
            - "add"
            - "replace"
            - "remove"
    yaml_path:
      name: YAML Path
      description: >-
        Top-level YAML key to modify (e.g., template, sensor,
        binary_sensor) or theme name for themes/*.yaml files. Only whitelisted keys are allowed.
      required: true
      example: "template"
      selector:
        text:
    content:
      name: Content
      description: >-
        YAML content for the value under yaml_path. Required for add
        and replace actions.
      required: false
      example: "- sensor:\n    - name: My Sensor\n      state: '{{ now() }}'"
      selector:
        text:
          multiline: true
    backup:
      name: Backup
      description: Create a backup before editing. Default is true.
      required: false
      default: true
      selector:
        boolean:

list_files:
  name: List Files
  description: List files in a directory within the Home Assistant config directory.
  fields:
    path:
      name: Path
      description: Relative path from config directory (e.g., "www/", "themes/")
      required: true
      example: "www/"
      selector:
        text:
    pattern:
      name: Pattern
      description: Optional glob pattern to filter files (e.g., "*.css", "*.js")
      required: false
      example: "*.css"
      selector:
        text:

read_file:
  name: Read File
  description: Read a file from the Home Assistant config directory.
  fields:
    path:
      name: Path
      description: >-
        Relative path from config directory. Allowed paths include
        configuration.yaml, automations.yaml, scripts.yaml, scenes.yaml,
        secrets.yaml (values masked), home-assistant.log, www/**, themes/**,
        custom_templates/**, packages/*.yaml, custom_components/**/*.py
      required: true
      example: "configuration.yaml"
      selector:
        text:
    tail_lines:
      name: Tail Lines
      description: For log files, return only the last N lines. Default is 1000 for logs.
      required: false
      example: 100
      selector:
        number:
          min: 1
          max: 10000
          mode: box
    yaml_path:
      name: YAML Path
      description: >-
        Dotted key path. When set, the response also carries the round-trip
        text of that YAML subtree under "subtree". Comments and HA tags
        (!secret, !include) are preserved as written.
      required: false
      example: "alert2"
      selector:
        text:
    include_parsed:
      name: Include Parsed
      description: >-
        With yaml_path, also return the subtree as structured data under
        "parsed". HA tags are rendered to their source form (!secret api_key)
        and never resolved, so no secret value is exposed.
      required: false
      default: false
      selector:
        boolean:

write_file:
  name: Write File
  description: Write a file to allowed directories (www/, themes/, custom_templates/).
  fields:
    path:
      name: Path
      description: >-
        Relative path from config directory. Must be in www/, themes/, or
        custom_templates/.
      required: true
      example: "www/custom.css"
      selector:
        text:
    content:
      name: Content
      description: The content to write to the file.
      required: true
      example: ".card { background: #333; }"
      selector:
        text:
          multiline: true
    overwrite:
      name: Overwrite
      description: Whether to overwrite if the file already exists. Default is false.
      required: false
      default: false
      selector:
        boolean:
    create_dirs:
      name: Create Directories
      description: Whether to create parent directories if they don't exist. Default is true.
      required: false
      default: true
      selector:
        boolean:

delete_file:
  name: Delete File
  description: Delete a file from allowed directories (www/, themes/, custom_templates/).
  fields:
    path:
      name: Path
      description: >-
        Relative path from config directory. Must be in www/, themes/, or
        custom_templates/.
      required: true
      example: "www/old-file.css"
      selector:
        text:

get_caller_token:
  name: Get Caller Token (Internal)
  description: >-
    Internal bootstrap service used by the ha-mcp server. Returns the auth
    token that the other ha_mcp_tools.* services require in their
    `_ha_mcp_token` field. The token is generated on first integration setup
    and persisted to .storage. Not intended for direct invocation from
    automations or scripts.
  fields: {}

get_allowed_paths:
  name: Get Allowed Filesystem Paths (Internal)
  description: >-
    Internal service used by the ha-mcp server settings UI. Returns the
    user-configurable extra read/write directories, the built-in allowlists,
    and the non-overridable deny floor. Restricted to the ha-mcp server
    (requires the `_ha_mcp_token`) and admin auth. Not intended for direct
    invocation from automations or scripts.
  fields: {}

set_allowed_paths:
  name: Set Allowed Filesystem Paths (Internal)
  description: >-
    Internal service used by the ha-mcp server settings UI. Replaces the
    user-configurable extra read/write directories (each granted both read and
    write). Entries that use path traversal, are absolute, escape the config
    directory, or hit the non-overridable deny floor (e.g. .storage) are
    dropped. Restricted to the ha-mcp server (requires the `_ha_mcp_token`) and
    admin auth.
  fields:
    paths:
      name: Paths
      description: >-
        Directories relative to the config directory, each granted read and
        write (e.g. "pyscript", "python_scripts"). Replaces the current list.
      required: false
      example: '["pyscript", "python_scripts"]'
      selector:
        object: