MCP Tool Catalog

Every tool the DataStar MCP server exposes, grouped by purpose. Tools marked (read) are read-only; tools marked (write) require Allow write access to be enabled for the relevant category on the workspace's MCP settings.

Several tools are dispatchers that pick a sub-operation via a first argument (action, mode, target, kind, direction, or source). That argument is documented inline.

The agent is assumed to run locally, with direct access to the workspace files. So there are no tools that merely mirror file contents: the agent reads and writes component SQL and template XML on disk itself, and uses these tools for what it cannot do directly — the database, the DataStar engine (scripting, dependencies, extraction, reversal, deployment building), and the task tracker.

Workspace

get_workspace_info (read)

Returns the open workspace: name, on-disk location, relative component path, whether it's under git, the component categories it exposes, and the configured metadata/dictionary-table names (so the agent knows which catalog tables it can query through execute_sql). Call it first to confirm which workspace the agent is operating against.

It also says what the work would belong to and how to extract it:

• Branch: the branch checked out (Git), or the workspace path (TFVC).
• TaskId: the task that branch belongs to, the active task; null when it belongs to none. work_on_task changes it.
• ChangesetCategories: the categories whose template deploys changesets. Extracting one of these would take every row in the table, not the task's, so an agent pulls the task's rows with pull_task_rows instead.
• VersionControl: git or tfvc (null when the workspace is not under version control, or its session is not connected). The tools that switch branch, commit and push are Git only.
• CommitTaskPolicy: the workspace's Task on Commits setting, Optional, Required or Off.
• CommitsLinked: whether a pushed commit's task is linked to its work item here: Link Commits to Work Items is on, Task on Commits is not Off, and the tracker can link commits on this remote (Azure Boards with an Azure Repos remote in the same organisation, on Azure DevOps Services).

Database

list_saved_connections (read)

Lists the saved database connections configured for the workspace's vendor, each with its Name and Vendor (which indicates the SQL dialect). Pass a Name to any DB-touching tool's connection parameter — the underlying session is constructed and cached on first use, so there is no explicit open or close step.

execute_sql (write)

Runs SQL against the connected database. mode picks the execution path:

• mode='read' (default): read-only. The SQL is validated up-front and any write (INSERT/UPDATE/DELETE/DDL/multi-statement) is rejected before it reaches the database; the SELECT rows come back in Rows. Schema and catalog inspection is done here — SELECT from INFORMATION_SCHEMA, sys.* (SQL Server) or the data dictionary / ALL_* views (Oracle) to list objects, describe a table's columns, or resolve the current schema and user.
• mode='dryRun': the write path wrapped in a transaction that is rolled back — results and errors come back without persisting. Requires write access. On Oracle, DDL auto-commits, so dryRun does not protect DDL.
• mode='commit': the write path that commits on success; may contain multiple statements. Requires write access.

Parameters: sql (required); mode = read | dryRun | commit (default read); maxRows (default 1000, read only); maxResultChars (default 100000, read only — caps cumulative cell text so large CLOB/varbinary values don't blow the client's context window); commandTimeoutSeconds (default 30; 0 = no limit — important on Oracle, where the provider default is unbounded); connection.

Components

find_components (read)

Lists and/or searches SQL components in the workspace. Omit query to list everything (optionally filtered by category); provide query to match component names (and file names); set searchContent=true to also match the SQL body. Each result carries its category, name, path, IsInBasket, HasDraft, and template name — read the SQL itself from the returned FullPath.

• query, category, searchContent (default false), maxResults (default 200), connection. When connection is supplied the live database is queried as well and each entry is tagged Unchanged, New, or Deleted against the workspace cache (requires category); omit it to return the cache alone, which is fast but may be stale.

compare_component (read)

Compares a component across two sources and returns a unified diff. Each side is scripted through the canonical engine before diffing.

• category, name (required); target = database (workspace vs live database; requires connection) or draft (workspace vs the component's pending draft; no connection needed); connection; connectionB (with target='database', supplying both connection and connectionB diffs the same component database-vs-database — the workspace file is not involved).

get_dependencies (read)

Lists components related to a target by direct dependency, using the template scripter's reference resolution (not catalog views — so it can't be reproduced with SQL). Requires an active database connection.

• category, name (required); direction = forward (components the target refers to) or reverse (components that refer to the target — "what would break if I changed this?"); scanAllCategories (reverse only, default false — scan the whole workspace vs just the target's own category); maxScan (reverse only, default 500; results report Scanned and Truncated); connection.

Authoring (write)

extract_components (write)

Extracts component scripts from the database through the template scripter.

• category (required); target = workspace (default — write into the component tree), draft (write as drafts for review, only when the database version differs from the workspace), or location (write a single component to outputDirectory, which must resolve inside the workspace; requires exactly one entry in names); names (omit to extract every component in the category; not allowed for target='location'); scriptType = create (default) or drop (target='workspace' only); outputDirectory (required for target='location'); connection.

Each result's OutputPath is the file written: the data document for a JSON template, otherwise the script. Pass these paths to commit_task_changes.

A category whose template deploys changesets is refused for every target and script type: writing the whole component, or a drop of it, would replace every row in the table, other tasks' included, and leave the task's changeset measured from a file that is gone. Use pull_task_rows.

delete_component (write)

Deletes a component file from the workspace and cleans up any associated draft. Destructive.

• category, name (required).

manage_drafts (write)

Acts on component drafts (proposed changes that haven't been applied yet).

• action = list (components with a pending draft; optional category filter; populates Drafts) | read (one draft's SQL; requires category and exactly one entry in names; populates Content) | apply (promote drafts to the workspace — the draft becomes the new workspace version and is removed; requires category, omit names for the whole category; populates Results) | discard (delete drafts without touching the workspace; same arguments as apply). apply is refused for a category that deploys changesets, for the same reason as extract_components; pull those rows with pull_task_rows.

Working on a task (write)

These four take a task from "I'm working on DAT-21" to pushed changes, doing what the app does around each step. Each refuses, changing nothing, when the choice is the user's, and says what to ask. When something fails that no one planned for (git, the database, the disk), the message says first what it left behind, such as nothing was committed, but these files were left staged, then the cause in the words of whatever failed. They sit in the Component Authoring category; all but pull_task_rows are Git only. On TFVC the task is the one set in the status bar, and the user checks in from the app, before manage_deployment build, which pins the checked-in versions.

work_on_task (write)

Puts the workspace on a task's branch, so the work that follows belongs to that task. It fetches first, then finds the task's branch (the branch associated with the task, or the one whose name carries its ID, whether it is local or so far only on the remote) and checks it out. When the task has no branch, it creates one from from, named by the Branch Template in Git preferences (for example feature/{taskid}), associates it with the task and checks it out. When the task's branch is already checked out it does nothing else. Either way the branch is brought up to its remote when that is a fast-forward, as checking out a remote branch in the app does; it is never merged. When the branch and its remote have both moved on, or there are uncommitted changes, Warnings asks the user to pull in the Incoming view. If the remote cannot be reached, it goes ahead on what the clone already knows and says so.

It refuses when there are uncommitted changes, including untracked files, because they belong to the branch checked out now, unless the user says to stash them (stash); when the task has several branches (pass branch); when branch names a branch that belongs to another task (it is not moved to this one; the user decides); when the task's branch is no longer in Git, or from names a branch that is not there; when the Branch Template has no {taskid} to name a new branch with (pass branch); and when a branch must be created without from. If the branch is checked out but its association with the task cannot be saved, it says so rather than reporting success, and the user associates it from the status bar. Previewing a task's deployment does not need it: preview_deployment_changes reads any task's branch.

• taskId (required); branch (optional: the branch to work on, local or remote such as origin/feature/DAT-21; created from from if it does not exist, and associated with the task either way); from (the branch a new branch starts from, such as origin/main; needed only when one is created); stash (default false: set only when the user says so, to stash uncommitted changes, untracked files included, as the app's Stash does, before switching. Nothing is stashed when the switch would be refused for another reason).
• Returns Action (none, checked_out or created), Branch, TaskId, BaseBranch, Pulled (the commits brought in from the remote), Warnings, and Stashed (the stash the changes went into, when any were stashed; any later failure repeats it so the user knows where their changes are).

commit_task_changes (write)

Commits files to the checked-out branch as the app's commit does. The shared definitions the documents point at, and the changesets and documents that belong together, go into the commit with them.

The commit's task is the branch's task unless taskId names another, as the commit dialog pre-fills its task field. The workspace's Task on Commits setting decides the rest: under Optional a branch with no task commits with none; under Required it refuses; under Off no task is recorded, and a taskId given is ignored with a warning. A recorded task is linked to its work item when the commit is pushed only where get_workspace_info's CommitsLinked is true. When a commit names no task under Optional, Warnings says so, for the agent to tell the user.

It refuses when the workspace requires a task and there is none, when other files are already staged, when a document's shared definition is missing, when a changeset does not match its document, when none of the files has changes or a path lies outside the workspace, and when the workspace moved to another branch (for example in the app) while the commit was being prepared.

• message (required); paths (required: the files to commit, absolute or relative to the workspace root, such as the OutputPath values from extract_components, the ChangesetPath and DocumentPath from pull_task_rows, and the deployment file's FilePath from manage_deployment); taskId (optional: a task other than the branch's).
• Returns Commit, Branch, TaskId (null when none is recorded), Committed, AlsoCommitted (the definitions and changeset partners added), Unchanged (paths with no changes, left out) and Warnings.

pull_task_rows (write)

Pulls the checked-out task's rows of a component that deploys changesets into its changeset, as Pull My Changes does, with the row picker's choice made by naming the rows. Call it twice:

1. Without rows, it compares and writes nothing. Each row on offer comes with its Key (for a template with more than one table, prefixed with the table's id, such as 2:"ALERIANINDEX", so rows in different tables never share one), KeyText (such as FEED_CD = NORTHFIELD_UK), table, Kind (insert, update or delete), the changed columns as before => after for an update or the whole row otherwise, whether it is already in the changeset (InChangeset), and why it cannot be taken (Refusal). At most 200 rows are listed; Total and Truncated say how many there are, and match narrows them.
2. With rows set to the keys to take, it writes the changeset and the document and returns ChangesetPath and DocumentPath for commit_task_changes. When the take leaves nothing to record, the changeset file is removed; ChangesetPath is still returned, with a warning, so its removal is committed too.

Rows already in the changeset always stay in it, so naming only new rows never takes earlier ones out. A row the source has changed again since it was taken is offered with its new value, and naming it takes that value. Taking a row out is done in the app. The changeset is always recorded against the checked-out task, whichever ticket described the rows. The pull is remembered, so the app's next Pull My Changes on the component starts from the same source.

By default the rows are measured against this branch without the task's rows. against names a database whose rows the changeset starts from instead, such as production. The compare then offers only what from changes against that database, each row with from's value, and only the rows named are taken. The document becomes that database's rows plus the rows named, so any other row the branch holds differently, other tasks' included, takes that database's value, as Pull My Changes does when a baseline is chosen. Both the compare and the take list those rows in Warnings, so the agent can name them to the user. Once a task has a changeset, starting from another database starts it again: its rows go back to their values before the task and are taken afresh. The compare reports this in StartsAgain, and rows are only written with startAgain=true, which an agent passes only after asking. To add rows to a changeset later, leave against out.

Nothing is written, and the agent is told to compare again, when the document or the changeset changed after they were read (another pull, in the app or by an agent, got there first), or when the workspace moved to another branch while the rows were read. A personal component is refused: its rows are pulled in the app.

• category, name, from (required: the saved connection to take the rows from); rows, match, against (optional); startAgain (default false).

push_task_changes (write)

Pushes the branch's commits, setting the upstream for a new branch, as every push in the app does, then links each commit that names a task to its work item where Link Commits to Work Items is on and the tracker can. A branch with no commits of its own is not pushed, and Warnings says there was nothing to push. A failure after the push went through is reported as that, and a cancel then does not stop the commits being linked. When the remote branch has commits this one does not, it refuses: the user pulls them in the Incoming view and pushes again. When the remote refuses the push for another reason, such as branch protection or a server-side hook, nothing is pushed and the message says why. A commit that could not be linked to its work item is named in Warnings; linking a commit never makes a push that went through fail.

• No parameters. Returns Branch, the Commits pushed (at most 50 named, the rest counted), and Warnings.

Asking an agent

Say what you are working on and what to do: "I'm working on DAT-21. Extract the views V_ORDERS and V_LINES from DEV, take my NORTHFIELD_UK import rows, build the deployment file, show me what it would do to UAT, then push." The rows can also be described in the task itself or in another ticket, which the agent reads with get_task. The server tells a connecting agent the order: work_on_task, extract_components (or pull_task_rows for a changeset component), commit_task_changes, manage_deployment build (which pins committed versions, so after the commit), commit the deployment file, preview_deployment_changes and generate_reversal_scripts, then push_task_changes. It also tells the agent to commit and push with these tools rather than with git.

Deployment

manage_deployment (read + write)

Reads or builds a task's deployment file, the ordered, version-pinned manifest of components that make up a release. Choose what to do via action:

• where (read): where the file is stored and whether it is there yet (Exists). Mode='Workspace' means a plain file at FilePath; Mode='Attachment' means the task attachment deployment.json or deployment.xml (AttachmentName says which). Existence is checked against the task's attachment list (Exists is null only when no tracker is connected).
• read (read): the raw deployment file (XML or JSON) in Content, routing between workspace-file and task-attachment storage.
• describe (read): the parsed structure: VcsType, WorkingBranch, DeploymentMode (Pinned, each item at its own version, or Branch, every item at the one commit it was stamped with; not the storage Mode above) and the ordered Items (path, category, file name, pinned version, template, triggered flag). Prefer this over read when you want the component list rather than the raw file.
• build (write): builds a new deployment file from a components list (source='components'). Each component is pinned to its latest committed, non-deleted version (in a Branch-mode workspace, every item is stamped with HEAD instead) and ordered by its template's deployment weight, with triggered scripts injected automatically. A component whose template deploys changesets goes in as the task's changeset for it (taskId, else the active task), as Add from Basket does; one the task has no changeset for is refused, telling the agent to pull its rows with pull_task_rows first or ask the user, since a full document deployed by a pipeline would replace every other work item's rows. (Added in the app's Deployment view, a full document is deployed only after asking.) save=true (default) writes it to the configured storage (needs write access), replacing the task's existing deployment file; save=false returns the built file in Content for review without writing. Warnings names any item with changes not yet committed, which the file does not include (commit them, then build again), and, when saving, any item the replaced file had that the new one does not.

A workspace-stored deployment file lives on the task's own branch, which need not be the branch checked out. When you ask about another task's file, read and describe read it from that task's branch in version control, so the user does not have to switch branch. Branch and BranchCommit in the result say where it came from. The task's branch is the one associated with it in DataStar, or the one whose name carries its ID; when there are several, the tool names them and asks for branch. When the task is the checked-out branch's own, the working tree is read, uncommitted edits included.

Parameters: taskId (optional; defaults to the workspace's active task); source (build only; components is the only value today); components (list of {category, name}, for build); save (default true); branch (optional, for read and describe: the git branch to read the file from, such as feature/DAT-21 or origin/feature/DAT-21).

generate_reversal_scripts (read)

Generates reversal (rollback) scripts for a task's deployment file against a named target database, as the Deployment view's Export Reversal Script does. Each item is read from version control at the version it deploys at (in a Branch-mode file, the head of the task's branch), so the task's branch need not be checked out, and changesets for one component are combined as deploying combines them. Object and data components are scripted from the target database's current state, so generate the reversal before deploying; a changeset's reversal is its own inverse. Read-only: it produces scripts, it does not apply them.

• connectionName (required); taskId (optional; defaults to the active task); branch (optional; as for manage_deployment).

preview_deployment_changes (read)

Previews what deploying a task's deployment file to a target environment would change, without deploying anything. It is the headless equivalent of the Deployment view's Database Snapshot, and the tool for questions like "what changes would the deployment for DAT-21 make when deployed to PRD?".

The deployment file is read from the task's own branch (see manage_deployment above). Each item is taken at the version it deploys at, from version control rather than the workspace copy: in a Pinned-mode file, each item's own version; in a Branch-mode file, the head of the task's branch, because deploying a Branch-mode file moves it to HEAD first. The result says which (DeploymentMode, PreviewedAt, StampedAt, HeadMoved). Each item is then compared with the environment as it is now, and classified as:

• CHANGED: deploying would alter it. A script returns the deployed script and a diff against the environment (read as current → deploy). A data component (a SQL MERGE or a JSON data document, which is first turned into the SQL it deploys) returns Operations instead: per table, whether the deployment can insert, update or delete, and a DataDelta with the rows it inserts, the rows it updates and their changed columns, and the rows it removes.
• NEW: the component is not in the environment; deploying would create it.
• REMOVE: a delete document whose component the environment holds; deploying removes it. Returns the delete script and a diff from what the environment holds.
• CONFLICT: a changeset some of whose rows someone else has changed since it was made. Deploying would stop.
• MATCH: deploying changes nothing (a delete document whose component is already gone is a MATCH too). Counted only, unless it carries a warning.
• N/A: the item cannot be compared, and Reason says why: a custom or static script that deploys as written, an item not in version control at its version, a document that cannot be turned into SQL, a changeset captured from the other vendor, or the database's own error.

A changeset returns Changeset: its rows against the environment, each with its change (insert, update, delete), its verdict (would change, already applied, conflict), the columns an update changes (before => after), the row an insert adds or a delete removes, and for a conflict what the environment holds instead (EnvironmentDiffers) and why (Explanation). Several work items' changesets for one component are compared as the one changeset they deploy as.

Read Problems first: anything there stops the whole deployment before it starts, such as a changeset beside its component's own document. Then each item's Reason and Warnings. A warning flags what a deployment would ask about, such as a full document of a changeset-deploying component, which would remove other work items' rows.

The result carries a one-line Summary (for example 3 changed, 1 new, 42 unchanged, 2 n/a - PRD (server/db)), the counts, and the Changes list. Read-only: it opens the environment to read its current state but never writes to it.

• environment (required): the target, given as a saved database connection name (use list_saved_connections to discover names). A version control connection must be active, since the preview fetches each item at its version.
• taskId (optional; defaults to the active task).
• detail (optional): summary (status, reason and counts only), diff (default: scripts, diffs and changeset rows, each capped in size so a large deployment fits an agent's context), or full (everything, uncapped).
• branch (optional; as for manage_deployment).

Asking an agent

Ask it plainly: "What changes would the deployment for DAT-21 make when deployed to PRD?". The server tells a connecting agent to find the connection with list_saved_connections and call preview_deployment_changes. For a large deployment, ask for a summary first, then the detail of the items that matter.

Templates

get_template_xsd (read)

Returns the XSD schema for a template type (DataComponent or ObjectComponent). Hand it to an agent before asking it to author or edit a template — templates themselves are XML files in the workspace that the agent reads and writes on disk directly.

Task tracking (Jira / Azure Boards)

get_task_tracking_capabilities (read)

Reports what the connected tracker supports (create, update, comment, transition, query, metadata, link). Returns IsConnected=false when no tracker is connected — safe to call with no session.

get_task_tracking_metadata (read)

Returns metadata from the connected tracker, selected by kind:

• types (task types) | statuses (statuses a task of taskType can hold; requires taskType) | fields (fields for taskType, including custom fields with name/type/required; requires taskType) | priorities | projects (projects accessible to the user) | link_types (use before link_tasks) | transitions (status transitions a specific task can make from its current state; requires taskId; use before transition_task).
• taskType (required for statuses/fields); project (Jira requires it for types/statuses/fields — these are per-project schemes; accepted and ignored on Azure DevOps, which is bound to one project; use kind='projects' to discover keys); taskId (required for transitions).

search_tasks (read)

Finds tasks by structured filters or a raw provider query.

• text, status, assignee (me matches the authenticated user), type, labels (ANDed), maxResults (default 50); or query — a raw provider-native query (JQL for Jira, WIQL for Azure DevOps) that overrides the structured filters. To fetch one known task by id, use get_task.

get_task (read)

Returns the full details of a task by taskId.

task_edit (write)

Creates or updates a task.

• action = create (requires type and title, plus project for Jira unless parentId is given) | update (requires taskId and at least one field to change).
• Fields: title; description (Markdown — auto-converted to ADF for Jira, HTML for Azure DevOps); assignee (Jira account ID — find it with task_user; display name for Azure DevOps); priority; labels (replaces the existing set on update); parentId (create a sub-task, or reparent on update); customFields (provider-specific fields as a JSON object — Jira field IDs like customfield_10001; Azure DevOps reference names like System.AreaPath; Html/History-typed fields accept Markdown).

task_user (read)

Resolves task tracker users.

• action = current (the authenticated user — account ID, display name, email; use it to resolve me) | lookup (search by display name or email via searchString, returning account IDs to use as assignees in task_edit).

transition_task (write)

Moves a task to a new status. Use get_task_tracking_metadata with kind='transitions' first to see which statuses are reachable.

• taskId, targetStatus (required); comment (optional, Markdown).

manage_task_comments (write)

Reads or posts comments on a task.

• taskId (required); action = list (every comment, oldest first) | add (posts a new comment — Markdown; requires write access); comment (required for add).

link_tasks (write)

Creates a typed link between two tasks. Use get_task_tracking_metadata with kind='link_types' first to discover valid names and their directionality.

• linkType, inwardTaskId, outwardTaskId (required); comment (optional, Markdown).

manage_task_attachment (write)

Reads, writes, lists, or deletes named file attachments on a task — the generic way to move files to and from a task. By convention a task's deployment file is the attachment deployment.xml or deployment.json, and a saved basket is basket.xml.

• action = list (all attachment names, populates Names) | get (the named attachment's text in Content; requires name) | put (writes content under name; requires write access) | delete (removes name; requires write access); taskId (optional — defaults to the active task); comment (optional, stored alongside a put).