qgis_mcp_plugin

Imported from nkarasiak/qgis-mcp (qgis_mcp_plugin/AGENTS.md). Install upstream with npx skills add nkarasiak/qgis-mcp --skill qgis_mcp_plugin. Copyright stays with the author.

AGENTS.md — qgis_mcp_plugin/

Plugin-side details. See the repository-root AGENTS.md for the architecture overview, the socket protocol and the shared conventions.

Key Details

• Raster styling: set_raster_style covers singleband_pseudocolor, singleband_gray, multiband_color and hillshade; set_layer_style stays vector-only. Unset min_value/max_value fall back to bandStatistics.
• Message log capture: Plugin connects to QgsApplication.messageLog().messageReceived on start, stores up to 1000 entries in a deque. Disconnects on stop.
• Processing outputs are verified: processing.run() returns an algorithm's declared outputs whether or not the run succeeded. The GDAL providers shell out and report a non-zero exit code only through the feedback object, so a command that wrote nothing still came back as {"OUTPUT": "/path/never/written"} (issue #40). Every processing.run() in the plugin goes through ProcessingHandlers._run_alg, which enforces the deadline, then raises CommandError when a caller supplied output path is not on disk afterwards (_missing_outputs, skipping TEMPORARY_OUTPUT, memory: and provider uris). A file that already existed must also have changed (mtime/size, snapshotted by _output_files_before), since a failed GDAL run leaves an earlier run's file in place. The check is "did the file appear or change", never "was anything reported": GDAL writes non-fatal warnings to stderr on runs that succeed, and _ResponsiveFeedback.reportError collects those into execute_processing's warnings key instead of failing the call. execute_processing(load_results=True) swaps processing.run for processing.runAndLoadResults, which rewrites the destination entries of the parameters dict in place into QgsProcessingOutputLayerDefinition objects - so _run_alg verifies against declared, a snapshot taken before the run, or the check would find no string paths left and silently pass everything (#46). Which layers were loaded is answered by diffing QgsProject.instance().mapLayers() around the run: only feature sink, vector and raster destinations are loaded (never file or folder ones), and the name QGIS gives a loaded layer is not the caller's output value.
• Plugin error model: handlers raise CommandError (or its LayerNotFound / WrongLayerType subclasses) from errors.py for anything the caller can act on - bad parameters, missing layer, unsupported option. _dispatch returns those as {"status": "error", "message": ...} and logs them at WARNING. Any other exception is treated as a plugin defect: the traceback is logged at CRITICAL and the response carries "internal": True. Never raise Exception(...) in a handler - it becomes indistinguishable from a bug. _dispatch also validates the caller's parameters against the handler signature (inspect.signature(...).bind, cached per command) before calling, so a missing or misspelled argument comes back as an ordinary error instead of a CRITICAL traceback in the user's QGIS log.
• Table-driven handlers: options with a fixed set of values are class-level dicts, not if/elif chains (_LAYER_PROPERTIES, _LAYOUT_EXPORTS, _WEB_SERVICES, _INPUT_CLASSES/_INPUT_BUILDERS, _VECTOR_STYLES, _RASTER_STYLES, _SHADER_*, _CONTRAST_ALGORITHMS). _pick(mapping, key, label) does the lookup and raises Unknown <label>: <key>. Use one of [...] generated from the table's keys, so the accepted-values list in the error can never drift from the code. Values that need attribute lookup on the running QGIS (settings classes, setters, builder methods) are stored as names and resolved with getattr - also because a staticmethod object is not callable on Python 3.9.
• QGIS 3.x/4.x compat: qgis_mcp_plugin/compat.py resolves deprecated enum forms at import time via try/except (e.g. QgsMapLayer.VectorLayer → Qgis.LayerType.Vector). The plugin imports constants like LAYER_VECTOR, MSG_WARNING, AGG_COUNT from compat instead of using raw enum values. When adding new enum usages, add the compat constant to compat.py first.