MCP Integration

IconVectors supports local automation through the Model Context Protocol (MCP). An MCP-capable coding client can inspect and control the running IconVectors desktop application: it can work with the active Editor document and selection, navigate Icon Explorer, create and edit SVG geometry, render previews, export files, and run the accepted Explorer batch operations.

The IconVectors 2.10 server exposes 166 MCP tools, including the Explorer batch PNG/ICO export, Replace Colors, Make Icon Versions, Adjust Icon Colors, Optimize SVG Files, Convert to currentColor, Center and Fit, Rotate / Flip, Outline Strokes, Apply Auto Gradient and Add Badge Overlays additions (the released 2.0 server exposed 155). This page explains the shared connection and safety model. Use one of the client-specific setup guides for exact configuration. The 2.10 additions require an application and sidecar built with those capabilities; inspect the connected catalog before using them.

How the local connection works

The Windows integration uses two cooperating processes:

• IconVectors.exe is the desktop application. It owns the current workspace, document, selection, Undo history, Explorer state, rendering, and file operations.

• IconVectorsMcp.exe is a local stdio sidecar launched by the MCP client. Do not run it as a separate background service.

• The sidecar forwards calls to the already-running application over IPv4 loopback. The default endpoint is 127.0.0.1:61337.

Start IconVectors normally before connecting. If the application setting Options/McpPort was changed, pass the same requested port to the sidecar. The application’s ICONVECTORS_MCP_PORT environment variable takes precedence when present. Sidecar --port arguments override its own environment setting; changing the client’s environment does not reconfigure an already-running app.

The 2.10 application/sidecar pair first tries the configured port. If that bind fails, the app requests an OS-assigned loopback port and publishes its runtime endpoint. The updated companion discovers a matching fallback without rewriting your preferences. Custom requested ports only match their own runtime records. When several instances run, the configured-port owner is preferred; a unique matching fallback can be used, but ambiguous fallbacks are rejected. This is endpoint discovery, not a document picker. Verify app_getInfo and the intended document or Explorer state before changing anything. The updated companion then pins that app’s per-start identity. After the app closes or restarts, restart/reconnect the MCP companion and inspect again, even if the port is unchanged. It will not silently redirect a command to another instance. An explicit --port matching the intended actual endpoint can resolve ambiguous fallback instances.

Older companions need the actual port configured manually and a reconnect, or an upgrade of both executables. A runtime-assigned port can change after the application restarts. Older applications remain usable on their configured port. They lack the new per-start identity and its restart-detection guarantee.

Successful MCP initialize, tools/list or protocol ping only confirms that the sidecar responds. Use the app_ping tool to test the actual desktop application connection; a visible tool catalog is not an application health check.

IconVectors does not publish a remote HTTP MCP endpoint. A cloud coding agent, hosted connector, container, or WSL process cannot reach the user’s desktop application merely by connecting to its own localhost.

Note

Client pages use C:\Program Files\Axialis\IconVectors as the normal installed-product example. Replace that path when IconVectors is installed elsewhere. Paths passed to tools must be native Windows paths visible to the desktop application, not paths that exist only in a client sandbox.

What the 166 tools cover

The catalog covers application and workspace discovery, document and selection state, SVG DOM inspection, creation, element and path editing, styles, gradients, palettes, icon operations, previews, export, history, preferences, and Icon Explorer file and batch operations.

The installed sidecar supplies its catalog through MCP tools/list. Public tool names use underscores, for example app_ping and document_getSvg. The eight supported clients in this documentation do not require IconVectors tool names to be rewritten. Use the installed command reference or machine schema when exact arguments are needed; this user guide does not duplicate all 166 definitions.

Discover, inspect, mutate, verify

Use the same sequence in every client:

1. Call app_ping, app_getInfo, app_getCapabilities, and app_get_workspace.

2. Inspect the intended workspace. In Editor, use document_getInfo and selection_get plus bounded DOM or style queries. In Explorer, use explorer_get_state and explorer_list_entries.

3. Prepare the smallest valid operation. Confirm paths and destructive intent before replacement, Save As, export, delete, move, or multi-file changes.

4. Perform one bounded mutation.

5. Inspect the affected document, selection, element, Explorer generation, or output path again before continuing.

6. Save or export only when requested.

Editor and Explorer are distinct states. Switch deliberately with app_set_workspace and inspect again. Explorer navigation that returns status: "accepted" has started asynchronously; poll explorer_get_state until the requested folder is the accepted current folder before issuing another navigation or file operation.

Element ordinals are live document identities rather than permanent IDs. Creation, deletion, reparenting, reordering, compound-path work, or whole document replacement can make a previously observed ordinal stale. Reinspect after structural edits instead of reusing old targets.

Duplicate element IDs and safe targeting

In IconVectors 2.10, dom_findById and commands that resolve a single element by its id reject an ID shared by several elements instead of silently selecting the first match. The tool reports isError:true and category ambiguous_element_id. This is a target-safety error, not a bridge connection failure: reconnecting will not make the SVG ID unique. A rejected ambiguous target does not partially change the document, selection, drawing defaults or Undo history.

Ask the assistant to query the current document before choosing what to edit. For example, call dom_query with:

{"query":{"id":"b","limit":1000}}

Inspect the returned ordinals using dom_getElement with an ordinal. Then explicitly target the intended current ordinal, or all intended ordinals if the chosen operation supports multiple targets. Do not automatically choose the first match. Both the error’s candidate list and query results are bounded: the diagnostic includes at most 32 candidates; this query returns at most 1,000. Do not describe an incomplete list as all matching elements.

Unique-ID lookup, missing-ID errors and explicit ordinal targeting retain their existing behavior. Ordinals belong to the current document state; query again after structural edits. This safety check does not repair or rename SVG IDs, rewrite saved files, or change authored gradient/resource URL references. The tool catalog remains 166; no new tool or input parameter is required.

Error details and multi-element targets

The companion adds the error data as compact JSON after the error text, as well as retaining structuredContent and isError:true. An assistant that displays only text can therefore see candidate ordinals and other supplied details. Errors without data keep their original text. Success responses and the application’s bounded candidate list are unchanged.

For editing tools accepting the shared multi-target selector, use {"target":{"elements":[{"ordinal":4},{"ordinal":9}]}}. Singular target.id/target.ordinal or {"target":{"useSelection":true}} are alternatives where accepted. target.ordinals is unsupported; errors now explain the correct form. The separate selection_set tool still accepts top-level {"ordinals":[4,9]}. Re-query after structural edits and inspect the intended elements before changing them. A rejected mixed target list is not partly applied.

Save As requires an existing destination folder. IconVectors reports the missing folder and a native OS error, or distinguishes an observed access failure or a path component that is not a directory. Create the folder explicitly or choose an existing one, then retry. No automatic parent-folder creation or modal MCP prompt is added; a failed save preserves the document and existing target.

Attribute queries compare stored text

dom_query uses literal string matching for query.attribute.equals, not numeric equality. The text "0.5" does not match "0.500000" even though both express the same number. Inspect the current element with dom_getElement and use the actual returned attribute spelling. An inline style is not automatically a separate presentation attribute of the same name.

The existing import sanitizer can store opacity with six fractional digits. Numeric setters and string setters can also produce different spellings, so inspect again after import or an edit. The 2.10 gradient-output improvement does not change this query contract, imported-opacity formatting or the existing Make Disabled Version behavior. No numeric-comparison query mode is added.

Undo, transactions, and filesystem changes

Many active-document mutations participate in IconVectors Undo/Redo. For several related document edits:

1. Call history_beginTransaction and keep its returned txId.

2. Perform only compatible active-document mutations.

3. Pass that exact ID to history_commitTransaction. If a step fails, use history_rollbackTransaction instead.

Do not leave a transaction open or include unrelated work in it. Transactions and document Undo do not cover every operation:

• document_new, document_open, and document_setSvg replace state and clear document Undo history.

• Save, Save As, export, preferences, palette files, view state, and selection changes are not document Undo operations.

• Explorer create, rename, delete, paste, duplicate, grouping, and batch apply change the filesystem and cannot be undone through document history.

Explorer Paste and Duplicate support dry run. Each Explorer batch tool uses a separate plan then apply protocol: review the summary, diagnostics, and returned plan_id, then apply only that unchanged current plan. An attempted matching service apply consumes its plan even on rejection; inspect current state and create a new plan rather than retrying a consumed ID. An earlier argument/busy rejection can occur before that attempt. See Keeping independent batch plans usable for independent explicit-path plans.

Reading batch diagnostics and committed-write counts

IconVectors 2.10 provides detailed results without changing tool names, arguments or opaque plan IDs. Copy/export planning collects independent per-file errors in deterministic order. One blocked selected output still rejects the whole copy plan. Original-file batches keep their existing policy: only reviewed Changed items are applied; Unchanged, Unsupported and Failed items remain untouched. Global rejection or cancellation still blocks the operation.

Read each diagnostic’s code, phase, cause, severity and path. An older explorer.export.render_failed wrapper can accompany a precise non-rendering cause, so inspect the details. Invalid explicit source paths also identify active_folder: base sources must still belong to the indexed active Explorer folder, not arbitrary folders.

The companion omits a redundant generic render wrapper when a precise terminal callback error already explains the failure. Distinct errors, warnings, service exceptions, actual preview/render failures and recovery information remain. Diagnostic array length is not a fixed contract; inspect codes and fields, not positions. This does not change statuses, plan applicability or write accounting.

In shared plan/apply results:

• reviewed_summary describes planned work, never completed writes. Original plans include planned_writes; copy plans include planned_outputs. reviewed_inputs and not_reviewed_inputs describe source review, not the number of overlay inputs or output files.

• review_complete means all requested source inputs entered content review, not that they all passed. A global failure or cancellation can stop review early. Unreviewed inputs must not be assumed safe.

• can_apply says whether this response contains an applicable plan. It is false for rejected/cancelled plans and apply responses. A true value never bypasses revalidation. False alone does not prove an earlier token was consumed: argument/busy rejection can precede a matching service apply attempt.

• no_op identifies an applicable original-file plan with no Changed items, or its completed zero-write apply. Still read unsupported/failed results. Creating a copy of an unchanged SVG is a write, not a no-op.

• Apply adds applied_summary.committed_files and committed_paths for verified surviving writes, plus applied_summary.unrecovered_files and unrecovered_paths for touched targets that could not be restored. A missing or externally changed target is not automatically a committed file.

Legacy summary, paths, artifacts and count fields keep their existing meanings; do not infer completed writes from planned counts. Rejection before writes and complete rollback leave zero committed files. After incomplete rollback, inspect both surviving writes and unrecovered targets, which can overlap, and retain reported recovery material. Accounting fields do not themselves extend plan lifetime or make a client timeout cancel an operation; the separate explicit-path policy is described below.

A missing or externally replaced output detected during post-commit cleanup is excluded from committed_paths and reported in unrecovered_paths. The command fails (failed for originals, failed_with_recovery for copies/export). Cleanup may already have removed its journal/backups, so even failed_with_recovery can have an empty recovery_folder. Do not infer an available backup or automatic restoration from status alone; inspect the diagnostics and explicit recovery paths.

See Reading batch results and warnings for the user-facing review workflow and Centering, fitting, rotating and flipping SVG files for clipping warnings. The installed command reference documents the full additive field contract.

Keeping independent batch plans usable

In IconVectors 2.10, a batch plan made with explicit paths can remain usable after unrelated batch work or a refresh of the same accepted Explorer folder. The application’s frozen dependency context must still match. Changing the filter or selection presentation alone need not invalidate these explicit targets. GUI previews and plans using use_explorer_selection:true keep their existing strict Explorer generation/revision checks; do not assume that they survive a refresh.

For independent pending operations, retain the returned plan ID from each different batch tool and review its exact input/output paths. Completing one does not automatically invalidate the others solely because the folder was refreshed. This is still one latest plan per tool, not a queue: planning again with the same tool replaces its older plan.

At apply, IconVectors checks the same accepted folder session, canonical folder and on-disk directory identity, and freshly validates the explicit base paths against the current Explorer index. It compares their observed file identity, size and modification time as well as the existing content checks. Replacing a source with a different file is a conflict even if its bytes are identical. If this context cannot be verified, the plan is rejected rather than trusted. The internal identity is not a new argument and plan_id remains opaque.

Base files must still belong to the active indexed Explorer folder; this is not arbitrary-folder access. Wait for indexing to settle. Navigating away and back starts a new accepted folder session and requires a fresh plan. Failed navigation that leaves the accepted folder unchanged does not itself invalidate a plan. Overlay changes, actual source/output conflicts, aliases, relevant settings, Editor conflicts and explicit overwrite consent remain guarded.

An attempted matching service apply still consumes the plan, including after rejection. Plans do not survive application restart. No new MCP tools or arguments are required, and a client timeout is still not cancellation.

A rejected plan reports the known changed, missing or unreadable input and path when safe read-only checks prove it. Copy plans can distinguish content, identity and metadata changes. Original-file checks do not guess file identity from an opaque context digest; a same-byte replacement or timestamp-only change can still receive a context rejection. Never treat that message refinement as permission to apply an old plan. When the specific cause cannot safely be established, the context error remains. Indexing, navigation, consent, consumption and Editor protections are unchanged.

Exporting Windows ICO files

On servers whose export schema includes ico, ask the assistant to export one ICO with the desired pixel sizes, for example:

{"format":"ico", "path":"C:/Icons/example.ico", "sizes":[16,24,32,48,256]}

For just a 24×24 icon, use sizes:[24]. Each image is square, 32-bit with transparency. Sizes must be unique integers from 1 to 256 pixels; entries are stored in ascending order. Images below 256 use DIB, and 256 uses PNG. Legacy color depths are not selectable. The native output path must be absolute and end in .ico; missing parent folders are created. Existing output is replaced only after successful export. This does not change the SVG, selection or Undo history. sizes is not accepted for other formats.

No dialog or action_invoke call is needed. If the connected schema does not list ICO, update the application and MCP sidecar together; changing the client’s subscription does not add this server capability. Always check the destination and obtain approval before overwriting a file.

Explorer batch commands at a glance

All 14 Explorer batch commands are available through MCP. Their public names remain stable even when the menu wording differs. Follow the feature links for the visual workflow, options and limits; MCP uses explicit JSON arguments instead of opening those dialogs.

Batch feature and MCP tool

Explorer feature	MCP tool
Add Badge Overlays	explorer_batch_overlay_icons
Adjust Icon Colors	explorer_batch_adjust_colors
Apply Auto Gradient	explorer_batch_auto_gradient
Apply Palette	explorer_batch_apply_palette
Center and Fit	explorer_batch_center_fit
Change Line Stroke	explorer_batch_apply_strokes
Convert to currentColor	explorer_batch_convert_to_current_color
Make Icon Versions	explorer_batch_make_icon_versions
Make PNG, ICO Bitmap Icons	explorer_batch_export_icons
Optimize SVG Files	explorer_batch_optimize_svg_files
Outline Strokes	explorer_batch_outline_strokes
Replace Colors	explorer_batch_replace_colors
Resize Icons	explorer_batch_resize_icons
Rotate / Flip	explorer_batch_rotate_flip

For example, ask your assistant: “In the current Explorer folder, plan PNG exports at 24 and 48 pixels and one ICO containing 16, 24, 32, 48 and 256 pixel images for each selected SVG. Put them in C:\Icons\Output. Show me the complete destination list and any errors before writing anything.”

Options saved by the graphical batch dialogs are a convenience for interactive use, not a substitute for MCP arguments. Inspect the connected schema and pass the desired options explicitly. A plan freezes those settings; never resend changed options with an existing plan ID.

Applying a palette and resizing icons

explorer_batch_apply_palette uses the current Editor palette. Select the intended palette first, then plan with:

{"mode":"plan","use_explorer_selection":true,"palette_id":"current","mapping_mode":"current_editor_default"}

These are the supported palette and mapping identifiers, not arbitrary palette filenames. Review every preview before applying, particularly icons with gradients or symbolic paints. A changed palette context requires a new plan.

explorer_batch_resize_icons changes the icon dimensions using the Editor’s resize behavior, unlike Center and Fit, which keeps the canvas unchanged:

{"mode":"plan","use_explorer_selection":true,"width":32,"height":32,"preserve_aspect_ratio":true,"alignment":"center","fit":"current_editor_default"}

Width and height must be positive finite numbers. alignment accepts only center and fit only current_editor_default. Both commands require all the shown planning options and exactly one source selector. Explicit indexed paths may replace use_explorer_selection:true. They modify source files without Editor Undo. After approval, call the same tool with only {"mode":"apply","plan_id":"returned-plan-id"}, then inspect the result.

Batch-exporting Explorer icons

Use explorer_batch_export_icons for several saved SVGs. Open their folder in Explorer, wait for indexing to settle, select the sources, then plan:

{
  "mode": "plan",
  "use_explorer_selection": true,
  "output_folder": "C:/Icons/export",
  "formats": ["png", "ico"],
  "png_sizes": [24, 48],
  "ico_sizes": [16, 24, 32, 48, 256],
  "current_color": "#000000",
  "overwrite": false
}

Explicit paths can replace use_explorer_selection, but must identify SVGs indexed in the active Explorer folder. Review the returned source and output counts, full destination list, replacement count and diagnostics. Apply only a successful plan, using its actual identifier:

{"mode":"apply", "plan_id":"returned-export-plan-id"}

Apply accepts the plan identifier without replacement options. Require status:"completed" and inspect diagnostics and recovery paths otherwise. A consumed or stale plan must be recreated. A client timeout does not cancel the application operation; inspect its state and outputs before planning again.

This route exports transparent PNGs and one multi-size 32-bit ICO per source without changing the SVGs or Editor document. Save or exclude dirty sources before planning. It uses explicit currentColor fallback, accepts the standard SVG 1.1 declaration without fetching a DTD, and rejects unsupported resources. See Batch export to PNG and ICO for input limits and rollback behavior.

Changing batch stroke colors

The Change Line Stroke command retains the MCP name explorer_batch_apply_strokes. Its color argument has three distinct meanings:

• "currentColor" writes the SVG paint keyword.

• "#2468AC" supplies an explicit opaque RGB color.

• "current" retains the legacy behavior: snapshot the current Editor brush and reject apply if that brush changes afterward.

Explicit RGB and currentColor plans do not become stale just because the Editor brush changes. The operation changes existing strokes, including inherited ones, and leaves fill-only or stroke="none" artwork without an added outline. Review its plan before apply; this modifies source files and is not covered by Editor Undo.

For example, use the following complete stroke plan:

{"mode":"plan","use_explorer_selection":true,"stroke_width":2,"line_cap":"round","line_join":"round","color":"currentColor"}

stroke_width must be finite and nonnegative. Cap values are butt, round or square; join values are miter, round or bevel. After review, apply with only mode and the returned plan_id.

Adding badge overlays to SVG copies

explorer_batch_overlay_icons creates one separate editable SVG for every selected base/overlay pair. For example:

{
  "mode":"plan",
  "use_explorer_selection":true,
  "overlays":[
    {"path":"C:/Badges/add.svg","suffix":"-add"},
    {"path":"C:/Badges/remove.svg","suffix":"-remove"}
  ],
  "output_folder":"C:/Icons/Badged",
  "anchor":"bottom_right",
  "size_percent":40,
  "margin":0,
  "cutout":true,
  "clearance":1,
  "overwrite":false
}

Forty bases and six overlays produce 240 copies, not six badges stacked on each base. Bases must be indexed in the active Explorer folder; overlay paths may be elsewhere. output_folder and overlay paths must be absolute. Placement supports all nine anchors: top_left, top, top_right, left, center, right, bottom_left, bottom, bottom_right. Size is greater than zero and at most 100 percent of the base canvas’s shorter side. Margin and cutout clearance are nonnegative SVG units; clearance has no effect when cutout is off. Bounds include supported strokes; this is geometric, not optical placement. See Add badge overlays for visual examples.

The default suffix is a hyphen plus the overlay filename without its extension. An explicit empty suffix is allowed only when destinations remain distinct and cannot overwrite any source. Repeated/aliased overlays and more than 10,000 pairs are rejected. Existing outputs require explicit overwrite:true. Neither base nor overlay originals, nor an open Editor file, can be overwritten.

Safe unreferenced duplicate IDs on ordinary artwork can be repaired in private copies only: later base occurrences of b become b-2, b-3 and so on, avoiding existing names. Badge IDs use separate namespacing. Resource IDs and ambiguous references remain blockers. Review overlay_duplicate_id_repaired diagnostics for exact mappings; the originals remain unchanged.

Review the source/overlay counts, per-pair destination paths, previews, replacement count and all diagnostics. After approval use the same tool with only {"mode":"apply","plan_id":"returned-overlay-plan-id"}. Any changed base, overlay or destination requires replanning. Inspect committed outputs and recovery information; the operation has no Editor Undo.

Batch SVG versions and color adjustments

explorer_batch_make_icon_versions creates separate SVG copies using the existing Hot, Disabled and Dark Theme transformations. For example:

{
  "mode": "plan",
  "use_explorer_selection": true,
  "output_folder": "C:/Icons/Versions",
  "versions": ["hot", "disabled", "dark"],
  "suffixes": {"hot": "-hot", "disabled": "-disabled", "dark": "-dark"},
  "overwrite": false
}

Review the planned destinations, previews and replacements. Each version starts from the original, not the result of another version. Source SVGs remain unchanged. Omitted suffix keys use -hot, -disabled and -dark. An explicitly empty suffix keeps the source filename in another folder; multiple enabled versions must still have distinct destinations. Explicit custom suffixes such as _hot are preserved rather than changed to hyphens. Generated files cannot overwrite a selected source or the current Editor document.

explorer_batch_adjust_colors modifies saved SVGs using one chosen adjustment:

{
  "mode": "plan",
  "use_explorer_selection": true,
  "adjustment": "brightness_contrast",
  "value1": 10,
  "value2": 5
}

Other adjustments are hue_saturation, levels, desaturate and invert. The first two numbers mean brightness/contrast, hue/saturation, or shadow/highlight, respectively. Omit both numeric fields for Desaturate and Invert. This applies the same chosen settings to the selection; it does not infer optimal values per icon. See Adjust colors across SVG icons for ranges and source-write warnings.

For either tool, use exactly one selection source: use_explorer_selection:true or explicit paths indexed in the active Explorer folder. After review and approval, call the same tool with only:

{"mode": "apply", "plan_id": "returned-plan-id"}

Changing inputs, destinations or options requires a new plan. The tools do not open modal options or confirmation dialogs. Inspect status and diagnostics, including recovery information; do not assume that every selected file succeeded.

Replacing an exact color in saved SVGs

Use explorer_batch_replace_colors after selecting saved SVGs in Explorer:

{
  "mode": "plan",
  "use_explorer_selection": true,
  "source_color": "#FF0000",
  "replacement_color": "#2468AC",
  "target": "both"
}

Use target:"fill" or target:"stroke" to limit the operation to one paint channel. source_color accepts an explicit #RRGGBB value or the symbolic "currentColor" keyword. replacement_color must be an explicit #RRGGBB value; there is no current Editor-brush fallback and no replacement with the currentColor keyword. Exactly one selection source is required: either use_explorer_selection:true or explicit paths identifying SVGs indexed in the active Explorer folder.

Review the returned counts, per-file diagnostics, changed paths and scope. After approval, apply only the reviewed plan:

{"mode":"apply", "plan_id":"returned-replace-colors-plan-id"}

Do not resend colors, targets or paths in apply mode. Changed inputs require a new plan. No picker or modal confirmation is opened through MCP; the client must obtain approval before writing the files. Check the structured status and diagnostics, including any recovery paths, rather than assuming all selected files changed. The operation has no Editor Undo entry.

Matching is exact parsed RGB, with existing transparency preserved. Choosing source_color:"currentColor" instead replaces symbolic fill/stroke paint occurrences with the supplied RGB color, not colors inferred from the theme or SVG color property. RGB-source plans leave currentColor paints unchanged. none and gradient/pattern paints are always left unchanged. No-match and same-RGB-color results retain the source bytes. Unsupported SVG/CSS constructs, including !important paint declarations, produce per-file diagnostics rather than partial recoloring. See Replacing an exact color for the detailed scope and safeguards.

Replace Colors and Convert to currentColor update the winning local attribute/inline declaration for an actually changed paint and remove safely superseded local values of that same property. A supported inherited/stylesheet/default paint still uses a local override; shared rules, ancestors, resources and authored color are unchanged. Required channel-opacity edits follow the same rule without losing effective alpha. Unrelated source bytes and no-op inputs stay identical. This is not global CSS cleanup and does not expand support for !important or complex CSS. The same tool arguments and plan/apply contract remain; see How color batches edit SVG source.

Optimizing selected SVG files

Discover explorer_batch_optimize_svg_files before use. Plan with either unique indexed paths or use_explorer_selection:true (exactly one):

{"mode":"plan","use_explorer_selection":true,"compact_formatting":true,"shorten_hex_colors":true,"compact_path_numbers":true,"round_path_coordinates":false}

The first three options default to true; rounding defaults to false. To round path coordinates, explicitly enable round_path_coordinates and optionally set integer decimal_precision from 0 to 5 (default 3). Supplying precision without rounding, unknown fields, or disabling every transformation is rejected. Rounding can change appearance. The tool preserves metadata, comments, IDs, references and significant text and writes only smaller results.

Review per-file states and byte_metrics containing original_bytes, planned_bytes and saved_bytes. Unreadable/unsupported items have no byte metrics. A percentage is saved bytes divided by original bytes times 100; use zero when original bytes are zero. Apply only the matching plan:

{"mode":"apply","plan_id":"returned-optimize-plan-id"}

Apply metrics count only successfully committed changed files, with zero totals for a no-op; rejection, failure and rollback omit them. Do not report planned savings as committed savings. See Optimizing SVG files.

Converting selected paints to currentColor

Discover explorer_batch_convert_to_current_color. For all supported solid paints, use color_scope:"all_solid" (the default) and omit source_color. To convert one exact RGB color:

{"mode":"plan","use_explorer_selection":true,"color_scope":"selected_color","source_color":"#2468AC","target":"both"}

target is both (default), fill or stroke. Selected-color mode requires source_color:"#RRGGBB"; symbolic source tokens are rejected. Exactly one source selector is required. Unknown or irrelevant options are rejected. The tool echoes scope, target and selected source when applicable. The GUI preview color is not an API option and never affects output.

Paint alpha is preserved through effective channel opacity, without changing element/group opacity. Existing currentColor, none, resources and untargeted paints remain unchanged. Authored color remains intact, with a warning when a fixed value limits external theme inheritance. Translucent authored color that would change converted paint alpha reports Unsupported. See Converting paints to currentColor for the supported SVG/CSS boundary. The local paint/opacity source edits described in How color batches edit SVG source do not change those transparency rules or clean pre-existing redundant declarations on already-converted paints.

{"mode":"apply","plan_id":"returned-currentcolor-plan-id"}

Both tools modify SVG files in place without Editor Undo. Back up or commit sources before applying. A target open in the current Editor blocks the entire modifying batch. Review selected/hidden counts, every file state and diagnostics; cancel writes nothing. Apply accepts only mode and the matching plan_id. Stale, consumed or cross-operation plans require new planning. Inspect status, affected paths and surviving recovery_paths; a transport timeout is not cancellation and must not trigger a blind retry.

Centering, fitting, rotating and flipping SVG files

Discover explorer_batch_center_fit and explorer_batch_rotate_flip before use. Both operate on saved SVGs with exactly one selection source: explicit indexed paths or use_explorer_selection:true. Plan mode is the default; the commands do not open modal option or confirmation dialogs.

Centering/fitting uses fitMode:"center" (default) or fitMode:"fit". Only fit mode accepts margin, a finite nonnegative inset in SVG user units; the default is zero and every icon must retain positive interior dimensions.

{"mode":"plan","use_explorer_selection":true,"fitMode":"fit","margin":2,"outputMode":"originals"}

Center-only does not scale. Fit applies one proportional scale to all artwork, including strokes, using supported conservative stroke-inclusive bounds. It is not optical centering. Root dimensions/viewBox remain unchanged. See Centering and fitting artwork for supported geometry and canvas semantics.

Rotation/flipping requires one action: rotate_left, rotate_right, rotate_180, flip_horizontal, flip_vertical or rotate_custom. Custom rotation requires finite numeric angleDegrees (positive clockwise, negative counterclockwise); fractions and full turns are accepted. This argument is forbidden for other actions and center/fit. Zero/full turns preserve source bytes. The pivot is the existing canvas center. Quarter-turns do not swap dimensions or fit the result; artwork may be clipped, including on square canvases with custom angles.

The geometry_canvas_clipping warnings reach both original and copy plans and successful apply results. They use phase:"transform" and cause:"painted_bounds_outside_canvas". The clipping object reports before and after overruns on left, top, right and bottom in units:"svg_user_units", with numeric tolerance. introduced identifies newly overrunning sides; worsened identifies increased existing overrun. conservative qualifies stroke envelopes that may exceed exact painted pixels. These are review warnings, not automatic fitting or proof that files were written; compare the previews.

{"mode":"plan","use_explorer_selection":true,"action":"rotate_right","outputMode":"copies","outputFolder":"C:/Icons/Rotated","suffix":"-rotated-right","overwrite":false}

For example, to plan a 22.5-degree counterclockwise rotation:

{"mode":"plan","use_explorer_selection":true,"action":"rotate_custom","angleDegrees":-22.5}

Both default to outputMode:"originals". Copy mode requires a nonempty outputFolder and the suffix string. That string may be empty ("") to keep the source filename in another folder; do not omit the field. Nonempty suffixes must be safe filename fragments; custom underscores are preserved. overwrite defaults to false. Do not supply copy-only options in originals mode, fit-only arguments to rotate/flip, or margin for center-only. Unknown and inapplicable arguments are rejected. Copy destinations cannot alias a source or the current Editor document, even with overwrite:true.

Review every planned status, diagnostic, before/after preview and destination, including unsupported files and replacements. After approval call the same tool with only:

{"mode":"apply","plan_id":"returned-geometry-plan-id"}

Changed options, inputs or destinations require a new plan. Explicit-path and selection-based plans follow Keeping independent batch plans usable. Neither mode has Editor Undo. Originals are changed only through the reviewed protected write; copies leave sources untouched but can replace explicitly approved destinations. Inspect final status, affected paths and retained recovery paths. Cancellation, failure or partial recovery is not successful completion. See Geometry output, review and limits for unsupported SVG constructs and shared safety rules. A transport timeout is not cancellation: inspect state before retrying.

Batch outlining and automatic gradients

Discover explorer_batch_outline_strokes and explorer_batch_auto_gradient before using them. Both default to planning, not writing. Supply exactly one source selector: indexed paths or use_explorer_selection:true. Review per-file states, unsupported inputs, preserved-paint diagnostics and destinations before applying.

Outline Strokes takes no width/cap/color overrides. It uses the SVG’s authored stroke appearance and preserves original fills, local transforms and canvas. Gradient/pattern strokes and unrepresentable geometry are unsupported, not silently approximated. If cached renderer RGBA ever disagrees with an affected symbolic currentColor paint, outline_current_color_renderer_context leaves the whole file untouched. This is a defensive appearance-preservation check, not an invalid-SVG verdict or a fixed-RGB conversion. See Outlining strokes.

{"use_explorer_selection":true,"outputMode":"copies","outputFolder":"C:\\Icons\\Outlined","suffix":"-outlined","overwrite":false}

Auto Gradient independently uses each targeted paint’s color. target is fill (default), stroke or both; type is linear (default) or radial. Integer angle accepts 0–359 (default 90) and affects both types; integer force accepts 1–50 (default 15). By default, existing gradients and symbolic currentColor are preserved. See Applying automatic gradients.

{"use_explorer_selection":true,"target":"both","type":"linear","angle":90,"force":15,"outputMode":"copies","outputFolder":"C:\\Icons\\Gradients","suffix":"-gradient","overwrite":false}

Only when requested, replace_existing_gradients:true replaces supported local gradient shape and stop-opacity variation using the existing midpoint/ average base-color rule. convert_current_color:true additionally requires current_color:"#RRGGBB"; omit that field when conversion is false. This explicit base replaces symbolic theme-responsive paint, even when the SVG has an authored color. It overrides that color’s RGB while preserving authored alpha and separate paint/element/group opacity. It is not a global base for ordinary solid paints.

IconVectors 2.10 reuses identical newly generated definitions within one SVG transformation, including units, mapping, coordinates, stops and alpha. Authored definitions are not merged or deleted. IDs remain deterministic and collision-free locally, not unique across files. Changed-paint counts do not become definition counts.

Only generated normalized coordinates use trimmed 15-fractional-digit formatting with a checked parse-back error of at most 1e-15 normalized gradient units; cardinal directions use exact coefficients. A mapping matrix can scale that bound. Stop alpha/offsets, mapping precision, unrelated geometry and global document precision are unchanged. This does not promise arbitrary-angle byte-identical output on untested platforms. Default/no-op preservation remains; explicit repeated replace_existing_gradients:true is not guaranteed to be a no-op or idempotent. Always review the new plan.

Both tools default to outputMode:"originals", with no Editor Undo. Copies require outputMode:"copies", a nonempty outputFolder and the suffix string. An empty suffix:"" keeps the source filename in another folder; nonempty values must be safe filename fragments. overwrite defaults to false. outputFolder, suffix and overwrite are forbidden for originals. Source aliases are protected even with overwrite:true; open Editor destinations and stale files are guarded. Unknown or inapplicable fields are rejected rather than ignored. Copy planning fails closed if any selected input is unsupported or failed; unchanged supported results are copied byte-for-byte. Copy plans expose source_results and a summary of planned states. Copy apply echoes this as reviewed_summary; only actual status and artifact results prove what was committed.

After reviewing the plan, call the same tool with only its matching ID:

{"mode":"apply","plan_id":"returned-paint-plan-id"}

Options and targets are frozen in the plan. Inspect actual status, affected paths, artifacts and recovery diagnostics; planned changes are not committed changes. Reinspect and replan after rejection or changed state. A client timeout does not cancel the transaction and must not trigger a blind retry.

Two current argument details

When these tools are useful in a workflow, use the accepted 2.0 behavior:

• selection_selectAll.includeHidden omitted or set to true includes hidden selectable elements. Set it to false for visible-selection semantics.

• document_placeFiles.position is an optional {x, y} top-left target in current SVG document coordinates. Omitting it keeps normal placement.

Consult the installed schema before calling either tool; these details are not substitutes for the full argument definition.

Working with a large catalog

Client limits and discovery features differ. IconVectors 2.10 does not serve named or dynamic tool profiles. Any allowlist, exclusion, deferred-schema setting, Tool Search feature, or tool picker described in a client guide is a client-side control.

Useful task-focused selections include:

• application and state discovery plus Explorer tools,

• application, document, selection, creation, style, element, history, and preview tools for basic editing,

• inspection, selection, DOM, path, history, and preview tools for path work,

• inspection plus code, render, and export tools for output,

• application/workspace discovery plus Explorer tools for batch work.

Always keep application, capability, workspace, and target-state discovery in the active set. Prefer bounded DOM or Explorer queries and minified SVG when a full SVG, preview PNG, or base64 payload would create unnecessary output.

Skills and persistent instructions

The distributed iconvectors-mcp skill contains the shared inspect, mutation, recovery, and verification workflow. Copy the complete skill folder, including its references directory, to the location documented for the client. Do not copy only SKILL.md when its references are needed.

Use short persistent files such as AGENTS.md, CLAUDE.md, GEMINI.md, steering, or Copilot instructions only for always-on policy or a pointer to the skill. Do not paste the complete tool catalog into every repository instruction file.

Approval and safety

Begin with client approval prompts enabled. Review the exact tool and arguments for document replacement, save/export, Explorer filesystem operations, and batch apply. Client trust, allowlists, and auto-approval are policy controls; they are not an Undo guarantee and do not change IconVectors behavior.

If the intended document, selection, Explorer folder, destination, or IconVectors instance is uncertain, inspect or ask for the missing intent. Do not force document replacement, fabricate a selection, or globally approve disk-changing tools merely to suppress prompts.

Troubleshooting

Server not discovered

Check the client-specific configuration scope and syntax, the absolute path to IconVectorsMcp.exe, and the client’s server list or MCP panel. Let the client launch the sidecar.

Sidecar starts but calls fail

Start IconVectors, match the requested port, and call app_ping. Check application responsiveness and the bridge diagnostics described below. Most calls have a 10-second bridge I/O timeout; existing long-running batch routes use 300 seconds, independently of the client’s startup/request limits. A timeout is not cancellation; inspect state before attempting another change.

Wrong application, workspace, or selection

Use app_getInfo and state inspection. With several instances, assign distinct ports and verify identity before mutation. Do not resolve an ambiguous fallback by guessing which document should receive the call.

Path fails

Use a native absolute Windows path. Quote executable paths in shell commands and escape backslashes in JSON. A client sandbox or cloud path is not a desktop path.

Explorer request appears stuck or stale

Wait for navigation to settle, reacquire Explorer state, and regenerate a batch plan if needed. Read structured status, category, and diagnostics rather than inferring success from prose.

Catalog or output is too large

Use the client-specific tool-selection feature and bounded results. Consult the client’s MCP log or output panel for companion-side diagnostics.

Bridge status and logs

The app_ping and app_getInfo results include a bridge object with the instance identity, requested/actual ports and startup state: not-started, listening-configured, listening-fallback or failed. A working fallback may retain the requested-port bindError to explain the port change. A failed listener cannot answer a health call; use the runtime log. Complete startup failure is also shown in the application’s status bar; no notification popup is required. If Windows socket cleanup loses the original error, a labelled fresh bind-only diagnostic may explain the requested port’s current failure. It never listens or selects a port. Its result is not the original socket error; if that recheck succeeds, the original reason remains unavailable. Actual application bind/listen success determines readiness.

The companion also returns mcpServerRunning, bridgeReachable, applicationResponding and a category. A healthy app call has all three flags true and category connected. A running companion with an absent app reports a tool error, not success. Resolve ambiguous_bridge or app_instance_unavailable explicitly. If a request failed after transmission, outcomeUnknown:true means the action may have happened; inspect state before deciding whether to retry. The top-level requested port is the companion’s choice, while bridge.requestedPort is the app’s originally configured port. A failed connection can retain a known or attempted actual port; only the health flags and result establish whether the app is reachable.

Each application instance writes bridge-<pid>-<instanceId>.json and a corresponding .log under these default directories:

• Windows: %LOCALAPPDATA%\Axialis\IconVectors\MCP\bridge

• macOS: ~/Library/Application Support/Axialis/IconVectors/MCP/bridge

• Linux: $XDG_STATE_HOME/axialis/iconvectors/mcp/bridge, or ~/.local/state/axialis/iconvectors/mcp/bridge when unset.

The JSON record is only a discovery hint; identity is checked against the live application. Do not edit records or share another user’s directory. Normal shutdown removes only that instance’s JSON record. Its bounded log remains and contains bridge diagnostics, not icon contents. Companion stderr is reported separately through the MCP client’s log/output panel. These records/logs require the updated application, not just a client configuration change.

Windows port conflicts and reservations

If the default port fails, inspect Windows’ excluded IPv4 TCP ranges and any listening process. These commands do not modify network settings:

netsh interface ipv4 show excludedportrange protocol=tcp
Get-NetTCPConnection -LocalPort 61337 -State Listen -ErrorAction SilentlyContinue |
    Select-Object LocalAddress, LocalPort, OwningProcess

A port inside an excluded range may be unavailable even when no process is listening. Ranges differ between computers and may be associated with Windows networking, Hyper-V or WSL. Do not delete reserved ranges or disable services. The 2.10 runtime fallback does not require changing those settings.

With older versions, select a port that is neither excluded nor occupied; 47337 is an example, not a guaranteed free port. Save your work and close IconVectors. Set ICONVECTORS_MCP_PORT=47337 in the environment used to launch the application, and separately set the MCP client’s companion arguments to --port 47337. A variable in the client’s configuration alone does not change the app’s port. Restart/reconnect, then verify app_ping and app_getInfo before using document tools.

For a persistent Windows application setting, back up the existing value first and, while the app is closed, set only HKEY_CURRENT_USER\Software\Axialis\IconVectors\Options\McpPort to a REG_DWORD with decimal value 47337. Do not replace the Options key. An inherited ICONVECTORS_MCP_PORT takes precedence and must be absent or match. Restore the previous value, or remove only this value if originally absent, to undo the change. The packaged MCP README includes a temporary, process-scoped PowerShell launch example that does not write preferences.

Client setup guides

• Using IconVectors with Codex / OpenAI

• Using IconVectors with Claude / Anthropic

• Using IconVectors with Cursor

• Using IconVectors with VS Code / GitHub Copilot

• Using IconVectors with Gemini CLI

• Using IconVectors with Kiro

• Using IconVectors with Cline

• Using IconVectors with GitHub Copilot CLI

See Developer Features for non-MCP developer output features.