io.github.mafaq229/pbirb-mcp

Set <DocumentMapLabel> on any named ReportItem (Textbox / Image / Rectangle / Chart / Tablix / etc.). Surfaces in the rendered report's navigable document-map / table-of-contents pane. Pass '' to clear. Idempotent. Returns {element, kind, changed: bool}.

Set <Visibility> on any named ReportItem (Tablix, Textbox, Image, Rectangle, Subreport, Chart). For group-level visibility use set_group_visibility; for detail-row use set_detail_row_visibility. toggle_textbox optionally points at a textbox name that toggles expand/collapse.

Move an existing named ReportItem inside <PageFooter> to (top, left). Errors if there is no <PageFooter> (call set_page_footer first) or no item by that name.

Resize a named item inside <PageFooter>. Same shape as set_header_item_size.

Set <BreakLocation> on a tablix group's page-break rule. location ∈ {None, Start, End, StartAndEnd, Between}. Passing 'None' removes the <PageBreak> element (the canonical 'no break' shape). Idempotent. Returns {tablix, group, kind: 'Group', location, changed}.

Replace a group's <SortExpressions> with a fresh list. Each entry is an RDL expression, e.g. =Fields!Region.Value.

Set <Visibility> on a group's TablixMember. Accepts a Hidden expression and an optional ToggleItem (a textbox name that toggles the group expand/collapse).

Move an existing named ReportItem inside <PageHeader> to (top, left). Errors if there is no <PageHeader> (call set_page_header first) or no item by that name.

Resize a named item inside <PageHeader>. Mirrors set_body_item_size — at least one of width / height; missing fields untouched; idempotent ({changed: false} when nothing differs). Closes the v0.2 parity gap where only the body variant existed.

Same shape as set_textbox_action but operates on a named <Image>. action_type ∈ Hyperlink / Drillthrough / BookmarkLink. Returns {image, kind, action_type, changed}.

Set <Image>/<Sizing> on a named Image. sizing ∈ AutoSize / Fit / FitProportional / Clip. AutoSize renders at native size (box grows to fit); Fit stretches to fill (ignores aspect ratio); FitProportional preserves aspect ratio; Clip renders at native size, clipped to the box. Idempotent: same value → {changed: false}, no save.

Repoint an existing <Image> at a different embedded image entry without delete-and-readd. Sets Source=Embedded and rewrites <Value> to embedded_name. Refuses with a clear error if embedded_name isn't in <EmbeddedImages> — leaving a dangling reference would render as a broken image. Add the image first via add_embedded_image. Idempotent: same (Source, Value) pair → {changed: false}, no save. Returns {name, kind, changed: bool}.

Set <KeepTogether> on a named Tablix / Rectangle / Chart / Textbox / Map / Gauge. Tells the renderer 'don't split this across pages if you can help it'. Best-effort — items larger than a page are still split. keep=False removes the element. Refuses for Image / Line / Subreport and other kinds where the RDL XSD doesn't allow it.

Set <TablixMember>/<KeepWithGroup> on the member that wraps the named group. value ∈ {None, Before, After}. Typical use: a column-header row's member with 'After' to glue it to the data rows that follow. value='None' removes the element.

Same as set_page_header, for <PageFooter>.

Create or update <PageHeader>: height plus PrintOnFirstPage / PrintOnLastPage flags. All fields optional — only what's passed gets written.

Set page orientation by swapping PageHeight and PageWidth when the current orientation doesn't match the requested one. Idempotent. Accepts 'Portrait' or 'Landscape'.

Update <Page> dimensions, margins, and column count on the first ReportSection. All fields are optional — only what's passed gets written. columns=1 strips the <Columns/> element.

Set or clear <ValidValues> on a report parameter. source='static' with a non-empty static_values writes a list of <ParameterValue> entries (each entry can be a string or {value, label} dict). source='static' with static_values=[] or omitted CLEARS the <ValidValues> element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a <DataSetReference> to a lookup dataset. Replaces any existing <ValidValues> block.

Set or clear <DefaultValue> on a report parameter. source='static' with a non-empty static_values writes a <Values> list of expressions. source='static' with static_values=[] or omitted CLEARS the <DefaultValue> element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a <DataSetReference> with ValueField only (no LabelField — defaults are values, not display strings). Replaces any existing block.

Author <ReportParametersLayout>/<GridLayoutDefinition> explicitly. Writes <NumberOfRows> + <NumberOfColumns>; rewrites <CellDefinitions> so each name in parameter_order lands at (row=index // columns, col=index % columns). Strict permutation check (every existing parameter exactly once). rows*columns must be ≥ parameter count. Auto-creates the layout block when absent. Idempotent: same grid + order → no save. Complements reorder_parameters (declaration order) and sync_parameter_layout (gap-filling). Returns {rows, columns, order, kind, changed}.

Write the <Prompt> text on a ReportParameter. Empty string clears the <Prompt> element entirely; pass a single space ' ' for blank-but-present.

Set <DataType> on a ReportParameter. type ∈ {Boolean, DateTime, Integer, Float, String}. Rejects with ValueError if any existing literal default value would be incompatible with the new type — fix defaults first via set_parameter_default_values, then retry.

Set <TablixMember>/<RepeatOnNewPage> on the member that wraps the named group. Most common use: repeat a group header row at the top of every page the group spans. Setting repeat=False removes the element (False is default). Returns {tablix, group, kind: 'TablixMember', repeat, changed}.

Set the Height of the Nth body row (0-indexed) in a tablix. Accepts any RDL size string ('0.25in', '1cm', '12pt').

Write <Color> into a named series's <Style> block, overriding the chart palette for just that series. color accepts a named color ('Red'), a hex string ('#FF0000'), or an =expression. Pass '' to clear (series falls back to the palette). Returns {chart, series, kind, changed: bool}.

Write the <TablixCorner> block — the top-left cell of a matrix-shaped tablix that holds the row-axis caption (e.g. 'Type'). Pass `text` for a literal value OR `expression` for a VB.NET '=...' formula. Mutually exclusive. Textbox name is deterministic: '<tablix_name>_Corner'. Refuses if the tablix has no named column group (the corner is only meaningful in a matrix). Replaces any existing TablixCorner block. Returns {tablix, name, kind: 'TablixCorner', changed}.

Resize a tablix by writing <Height> and / or <Width> directly. Each arg independently optional. Use after adding header / footer rows that change the body's natural height — v0.2's positioning tools only cover top/left, not size. Both values are RDL size strings. Returns {tablix, kind, changed: list[str]} — empty list when inputs match existing.

Set <Textbox>/<Action> to a Hyperlink (URL), Drillthrough (another report + optional parameters), or BookmarkLink (jump within document). target_expression accepts literal text or =expression. drillthrough_parameters is a list of {name, value} dicts wired into <Drillthrough>/<Parameters>. Idempotent: same action_type + target + parameters → {changed: false}, no save.

Replace a textbox's content with multiple <TextRun> children for mixed styling within one display — e.g. '**Asset(s):** value' with a bold prefix + regular value in a single textbox. Each run is a dict with required 'text' and optional font_family / font_size / font_weight / font_style / color / format / text_decoration. Replaces the entire <Paragraphs> subtree (single-paragraph in v0.3; multi-paragraph deferred). Round-trip contract: get_textbox.runs[] returns the same shape this tool writes. Idempotent — identical input is a no-op short-circuit. Returns {textbox, kind, runs, changed}. Pass raw text in each run's `text` — encoding is handled; don't pre-encode XML entities (use `&` not `&amp;`, including for the VB.NET string-concat operator).

Set styling on a named Textbox. Properties route to the right nested Style node automatically: background_color, border_*, vertical_align, padding_*, writing_mode go on Textbox/Style; text_align on Paragraph/Style; font_*, color, format on TextRun/Style; can_grow / can_shrink go DIRECTLY on Textbox (not inside Style). All fields optional — only what's passed gets written. Cell-level styling: every tablix cell is a Textbox with a unique name, so use this tool with the cell's textbox name (e.g. 'HeaderAmount').

Apply the same style kwargs to every named textbox in one call. Same kwarg surface as set_textbox_style. Missing names land in skipped rather than raising. Returns {textboxes, skipped, changed} where changed is the union of sub-paths affected across all textboxes. Pair with find_textboxes_by_style to discover names by current style.

Set <Textbox>/<ToolTip>. Literal text or =expression. Pass '' to clear. Idempotent. Returns {textbox, kind, changed: bool}.

Replace the text content of a single-run textbox. value can be raw text or an =expression. Use this for the everyday 'change the textbox content' case (swap a literal label, update a stale parameter reference, replace a broken aggregate). Refuses with a redirect to set_textbox_runs when the textbox has multiple text runs (multi-run content needs the rich-text editor). Idempotent: identical value → {changed: false} no-op. Returns {textbox, kind, changed}. Pass raw text — encoding is handled; don't pre-encode XML entities (use `&` not `&amp;`, including for the VB.NET string-concat operator in expressions).

Open the report and start an editing transaction. Returns {transaction_id, path, expires_at}. Pass transaction_id to subsequent edit tools to mutate the live in-memory tree WITHOUT touching disk between calls — eliminates the per-edit parse+serialize round-trip. The transaction times out after PBIRB_MCP_TRANSACTION_TIMEOUT_S seconds (default 600); call commit_editing_transaction to flush or cancel_editing_transaction to discard. Refuses if an active transaction already owns this path.

Apply the same style kwargs to every cell in a tablix row in ONE call. Replaces the 12-individual-set_textbox_style-calls-per-row pattern. row accepts: integer (0-based body row index), 'header' (first leaf with KeepWithGroup=After — the column header row), 'details' (the Details leaf row), '<group>_header' (header row of a named row group), '<group>_footer' (footer row when present, e.g. after add_subtotal_row). Same style kwargs as set_textbox_style (font_*, color, background_color, border_*, padding_*, writing_mode, can_grow, can_shrink, etc.). Delegates writes to set_textbox_style_bulk. Returns {tablix, row, row_index, kind, cells, changed, skipped}.

Emit =Sum(IIf(<condition>, <field_expression>, 0)) — the SSRS conditional-sum idiom. Both args are expression bodies (no leading '=').

Bring <ReportParametersLayout>/<GridLayoutDefinition>/<CellDefinitions> into sync with <ReportParameters>. Drops cells whose ParameterName no longer exists; appends cells for parameters that have no entry, placed at the next free (row, col) slot. add_parameter / remove_parameter / rename_parameter call this internally; the standalone tool is for repairing legacy reports authored before v0.3.0 where the layout drifted. No-op when the report has no <ReportParametersLayout>. Returns {added, removed}.

Replace the DAX command text of a named dataset. The full DAX expression is accepted verbatim; empty bodies are rejected. Optional alias_strategy='preserve_field_names' positionally rewrites <DataField> cells to the new DAX columns while keeping existing <Field Name> identifiers — so Fields!X.Value references in expressions keep resolving.

Toggle the four boolean flags on a report parameter: multi_value, hidden, allow_null (writes <Nullable>), allow_blank. Each is independently optional. With no flags passed it's a no-op. Cascading parameters are NOT a flag — use set_parameter_available_values(source='query') + add_query_parameter on the lookup dataset to wire a dependency on another parameter.

Change the value expression of an existing query parameter. Same PBIDATASET @-prefix normalisation as add_query_parameter applies on lookup; legacy Name='@X' parameters that already exist on disk are addressable via either @X or X.

Run schema/structural validation against an .rdl. Returns {valid, errors, xsd_used}. Structural checks always run (root element + required top-level sections). The Microsoft RDL 2016/01 XSD is bundled by default since v0.3.1 — when it's loaded, xsd_used is True and the schema-conformance bug class Power BI Report Builder rejects on load gets caught here. If the bundled XSD is missing (source-build without package-data) a {severity:warning, rule:'xsd-not-bundled'} issue surfaces instead of silent skip. Each issue is {severity, rule, location, message, suggestion?}; valid is True iff no severity='error' issue.

One-shot static check: union of validate_report and lint_report. Returns {valid, issues, xsd_used} where valid is True iff no issue has severity='error'. Warnings (including 'xsd-not-bundled' when the schema file is missing) don't invalidate the report. Use this as the single 'is the report OK?' tool, or set PBIRB_MCP_AUTO_VERIFY=1 to have it run after every mutating call.