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.

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.

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).

manage_basket (write)

Views or modifies the deployment basket — a staging list of components.

• action = get (staged components, populates Items) | add (stage a component; requires category and name) | remove (unstage; requires category and name) | empty (clear) | import (add every component from a basket XML document passed in content — e.g. a basket.xml fetched via manage_task_attachment). add/remove resolve the component against the workspace cache, then the component folder on disk, then (for remove) the basket's own contents.

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.xml — existence is checked against the task's attachment list (Exists is null only when no tracker is connected).
• read (read): the raw deployment XML in Content, routing between workspace-file and task-attachment storage.
• describe (read): the parsed structure — VcsType, WorkingBranch, 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 raw XML.
• build (write): builds a new deployment file from a components list (source='components') — each component pinned to its latest non-deleted version and ordered by its template's deployment weight, with triggered scripts injected automatically. save=true (default) writes it to the configured storage (needs write access); save=false returns the built XML in Content for review without writing.

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).

generate_reversal_scripts (read)

Generates reversal (rollback) scripts for the deployment file attached to a task, against a named target database. For object components the reversal SQL is queried from the target database's current state; static-data reversal artefacts are copied from the workspace file. Read-only — it produces scripts, it does not apply them.

• connectionName (required); taskId (optional — defaults to the active task).

preview_deployment_changes (read)

Previews what deploying a task's deployment file to a target environment would change, without deploying anything — the headless equivalent of the Deployment view's Database Snapshot. It answers questions like "if I deploy TASK-123 to DEV, what would it change?".

For each version-pinned item it downloads the script at its pinned version (from version control, not the current workspace copy — this is what a deploy actually applies) and compares it against the target environment's current state, classifying each item as:

• CHANGED — the object exists in the environment but deploying would alter it. Returns the full to-be-deployed script plus a diff against the current database (read as current → deploy).
• NEW — the object is not in the environment; deploying would create it. Returns the full new script.
• MATCH — identical to the environment; deploying changes nothing. Counted only, to keep the response focused.
• N/A — static-data or custom scripts that deploy verbatim and have no database object to DDL-diff. Returns the verbatim script (e.g. a reference-data MERGE) so its effect can still be described.

The result carries a one-line Summary (e.g. 3 changed, 1 new, 42 unchanged, 2 n/a — DEV (server/db)), the four counts, and a Changes list with per-item Category, FileName, Status, DeployedScript, and Diff. Read-only: it opens the environment to script 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 pinned version.
• taskId (optional — defaults to the active task).
• detail (optional) — summary (status and counts only), diff (default; full deployed script plus a context-trimmed diff for changed items), or full (the complete diff for changed items).

Scope

Object/DDL changes (procedures, views, functions, tables, and so on) are diffed precisely against the live environment. Static data scripts are surfaced verbatim — so the agent can read the MERGE/INSERT and describe its intent — but are not diffed row-by-row against the environment's current table data.

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 and an exported 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).