Skip to main content

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 on the workspace's MCP settings.

Several tools are dispatchers that pick a sub-operation via an action, target, kind, or direction argument. The dispatch parameter is always the first argument and is documented in line.

Workspace​

get_workspace_info (read)​

Returns the currently open workspace: name, on-disk location, relative component path, whether it's under git, and the component categories it exposes.

Database inspection​

get_database_schema (read)​

Returns a high-level index of the connected database: tables, views, stored procedures, and functions. Each category is capped.

  • maxObjectsPerCategory: int = 200
  • connection: string? — saved-connection name to run against.

get_table_details (read)​

Returns full detail for a single table: columns (type, nullability, default, primary-key flag), constraints, and indexes.

  • tableName: string (required)
  • schema: string? = null. Omit to use the session's default.
  • connection: string? — saved-connection name to run against.

get_database_context (read)​

Returns the context the connected database session resolves unqualified names against: effective default schema, current user, vendor, connection name/summary, and accessible schemas.

  • connection: string? — saved-connection name to run against.

execute_sql (write)​

Runs ad-hoc SQL against the connected database. The allowWrite flag picks the execution path. The read-only validator is vendor-aware — on Oracle it also blocks HTTPURITYPE and the rest of the URI-type family so the read path can't be turned into an outbound-network channel.

  • sql: string (required)
  • allowWrite: bool = false. When false, runs in read-only mode — writes are rejected up-front and rows are returned in Rows (capped by maxRows). When true, runs through the same logged execution path as the UI inside a transaction that COMMITs on success; Execution is populated. Setting true requires workspace write access.
  • maxRows: int = 1000. Ignored when allowWrite=true.
  • maxResultChars: int = 100000. Maximum cumulative stringified value length across returned rows when allowWrite=false. Stops the row stream early to keep large CLOB/varbinary cells from blowing the client's context window. Ignored when allowWrite=true.
  • commandTimeoutSeconds: int = 30. Per-query command timeout in seconds. 0 means no limit. Important on Oracle where the provider default is unbounded.
  • connection: string? — saved-connection name to run against.

For row-returning SELECTs, leave allowWrite at its default. To run a saved component script with the UI's commit/rollback toggle, use execute_script instead.

Connections​

list_saved_connections (read)​

Lists the saved database connections the user has configured.

Metadata tables​

The metadata_table tool only operates on tables listed in the workspace's configured metadata tables.

metadata_table (read)​

Inspects the workspace's configured metadata tables (vendor-specific catalog/dictionary tables, e.g. CS_DICT_TABLES). Only tables explicitly listed in the workspace configuration can be inspected.

  • action: string (required) — one of:
    • list — returns the configured metadata table names. Result populates Tables.
    • describe — returns column definitions (name, type, nullability, max length) for one metadata table. Requires tableName. Result populates Columns.
    • query — returns rows matching optional filters with optional column projection. Requires tableName. Set countOnly=true to skip the rows and just get a count. Result populates Rows + Count, or just Count when countOnly=true.
    • search — full-text-style scan across every configured metadata table for rows that mention searchTerm. Result populates Matches (per-table) + Errors (tables that couldn't be searched).
  • tableName: string? — required for describe and query.
  • filters: MetadataFilter[]? — query only. ANDed together.
  • columns: string[]? — query only. Omit for *.
  • maxRows: int = 1000 — query only.
  • countOnly: bool = false — query only.
  • searchTerm: string? — required for search.
  • maxRowsPerTable: int = 50 — search only.
  • maxResultChars: int = 100000 — query and search only. Maximum cumulative stringified value length across returned rows. Stops the row stream early to keep large text/blob cells from blowing the client's context window.
  • commandTimeoutSeconds: int = 30 — per-query command timeout in seconds for actions that hit the database. 0 means no limit.
  • connection: string? — saved-connection name. Required for describe, query, and search; ignored for list.

Each MetadataFilter has column, operator (=, <>, LIKE, NOT LIKE, IS NULL, IS NOT NULL), and value (ignored for the null operators).

Components​

list_components (read)​

Lists SQL components in the current workspace, with optional filtering and search. Omit query to list everything; provide query to match component names. Set searchContent=true to also match against the SQL body.

  • query: string?
  • category: string? — required when connection is provided.
  • searchContent: bool = false
  • maxResults: int = 200
  • connection: string? — saved-connection name. When provided, the live database is queried as well and each returned component is tagged with a Status of Unchanged, New (present in the database but not yet in the workspace cache), or Deleted (still in the cache but no longer in the database). Omit to return the workspace cache alone, which is fast but may be stale.

get_component_content (read)​

Returns the full SQL script for a component. Throws when the requested copy doesn't exist (e.g. asking for a draft when none is pending).

  • category: string (required)
  • name: string (required)
  • source: string = "workspace" — workspace returns the committed workspace copy; draft returns the pending-draft copy.

get_component_metadata (read)​

Returns a component's metadata: when and where it was last extracted, its database status, template, whether it has a pending draft or is in the deployment basket.

  • category: string (required)
  • name: string (required)

delete_component (write)​

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

  • category: string (required)
  • name: string (required)

Dependencies​

get_dependencies (read)​

Lists components related to the given target by direct dependency.

  • category: string (required)
  • name: string (required)
  • direction: string = "forward" — forward lists components the target refers to; reverse lists components that refer to the target (answers "what would break if I changed this?").
  • scanAllCategories: bool = false — reverse only. When false, scans only the target's own category (fast).
  • maxScan: int = 500 — reverse only. Reverse results report Scanned and Truncated.
  • connection: string? — saved-connection name to run against.

Requires an active database connection.

Drafts​

list_drafts (read)​

Lists components that have a pending draft. Optionally filter by category.

  • category: string?

To read a specific draft's SQL, call get_component_content with source='draft'.

process_draft (write)​

Acts on one or more pending drafts in a category.

  • category: string (required)
  • action: string (required) — apply promotes drafts to the workspace (draft becomes the new workspace version and is removed); discard deletes drafts without modifying the workspace.
  • names: List<string>? — omit to act on every pending draft in the category.

Extraction​

extract_components (write)​

Extracts component scripts from the database. Requires an active database connection.

  • category: string (required)
  • connection: string? — saved-connection name to run against.
  • target: string = "workspace" — one of:
    • workspace — writes scripts straight into the workspace component tree.
    • draft — writes scripts as drafts for review (only when the database version differs from the workspace).
    • location — writes a single component to outputDirectory (must be inside the workspace; requires names with exactly one entry).
  • names: List<string>? — omit to extract every component in the category (not allowed for target='location').
  • scriptType: string = "create" — target='workspace' only. create extracts CREATE scripts; drop extracts DROP scripts.
  • outputDirectory: string? — required for target='location'.

Comparison​

compare_component (read)​

Compares a component across two sources and returns a unified diff.

  • category: string (required)
  • name: string (required)
  • target: string (required) — database diffs against the live database (requires connection); draft diffs against the component's pending draft (no connection needed).
  • connection: string? — saved-connection name. Required when target='database'.
  • connectionB: string? — second saved-connection name. When supplied alongside connection (with target='database'), the comparison is database-vs-database for the same component instead of workspace-vs-database.

Deployment basket​

get_basket (read)​

Returns the components currently staged in the deployment basket.

update_basket (write)​

Modifies the deployment basket.

  • action: string (required) — one of:
    • add — stages a component (requires category and name).
    • remove — takes a component out of the basket (requires category and name).
    • empty — clears the basket (category and name are ignored).
  • category: string?
  • name: string?

import_basket_from_task (write)​

Populates the basket from the basket.xml attachment on a task in the configured task tracker.

  • taskId: string? — optional. When omitted, the workspace's active task is used. Fails if neither is set.

Execution​

execute_script (write)​

Runs a component's SQL script against the connected database.

  • category: string (required)
  • name: string (required)
  • dryRun: bool = true — when true, the script runs inside a transaction that is rolled back. Set false to commit. On Oracle, DDL statements auto-commit regardless of this flag.
  • connection: string? — saved-connection name to run against.

Templates​

list_templates (read)​

Lists templates in the workspace. Optionally filter by component type or category.

  • type: string? — DataComponent or ObjectComponent.
  • category: string?

get_template (read)​

Returns a template's metadata together with its full XML content.

  • filePath: string (required) — the full filesystem path returned by list_templates.

get_template_xsd (read)​

Returns the XSD schema for a template type. Hand the XSD to an agent before asking it to author or edit a template.

  • type: string (required) — DataComponent or ObjectComponent.

save_template (write)​

Creates or updates a template at the given path. XML is validated against the appropriate XSD before being written; the file is only written if validation passes.

  • filePath: string (required) — must be inside one of the workspace's template directories and end with .xml.
  • xmlContent: string (required)
  • createNew: bool (required) — true requires that no file exists at the path (use for new templates); false requires that the file already exists (use to modify).

Deployment files​

get_deployment_file_storage_info (read)​

Reports where the deployment file for a task is stored: as a task attachment, as a workspace file, or not yet created. The exists field is only populated for workspace storage.

  • taskId: string? — optional. When omitted, the workspace's active task is used. Fails if neither is set.

manage_deployment_file (write)​

Reads, writes, or summarises the deployment file for a task. Routes between task-attachment storage and workspace-file storage based on workspace configuration.

  • taskId: string? — optional. When omitted, the workspace's active task is used. Fails if neither is set.
  • action: string (required) — one of:
    • get — returns the raw XML in Content.
    • set — writes xmlContent (creating parent directories as needed) and returns location info. Requires write operations enabled.
    • describe — returns a structured summary (VcsType, WorkingBranch, Items).
  • xmlContent: string? — required for action='set'.

Reversal scripts​

generate_reversal_scripts (read)​

Generates reversal (rollback) scripts for the deployment file attached to a task, against a named target database. Read-only: produces scripts, does not apply them.

  • taskId: string? — optional. When omitted, the workspace's active task is used. Fails if neither is set.
  • connectionName: string (required)

For object components, reversal SQL is queried from the target database's current state; static-data templates are copied from the workspace file verbatim.

Task tracking​

get_task_tracking_capabilities (read)​

Reports what the connected task tracker supports (create, update, comment, transition, query, metadata, link). Returns IsConnected=false when no tracker is connected.

get_task_tracking_metadata (read)​

Returns metadata from the connected task tracker. Only the field matching kind is populated in the result.

  • kind: string (required) — one of:
    • types — lists the task types (e.g. Bug, Story, Task, Epic).
    • statuses — lists the statuses a task of the given type can hold. Requires taskType.
    • fields — lists the fields for a task type, including custom fields with name/type/required. Requires taskType.
    • priorities — lists the priority levels.
    • projects — lists the projects accessible to the authenticated user.
    • link_types — lists the issue link types (use before link_tasks to find valid names).
  • taskType: string? — required for statuses and fields.
  • project: string? — project key (e.g. DAT). Required by Jira for types, statuses, and fields, because these are governed by per-project schemes; the call will fail with a clear error if it's missing. Azure Boards connections are bound to a single project, so the parameter is accepted and ignored there. Use kind='projects' first if you need to discover available keys.

get_available_transitions (read)​

Lists the status transitions a specific task can make from its current state. Use this before transition_task.

  • taskId: string (required)

get_current_user (read)​

Returns the authenticated user's account ID, display name, and email as known to the task tracker.

lookup_user (read)​

Searches for users by display name or email address (partial matches supported). Use the returned account IDs when assigning tasks via create_task or update_task.

  • searchString: string (required)

run_query (read)​

Runs a raw provider-native query: JQL on Jira, WIQL on Azure Boards.

  • query: string (required)
  • maxResults: int = 50

search_tasks (read)​

Structured search across the tracker by any combination of text, status, assignee, type, and labels.

  • text: string?
  • status: string?
  • assignee: string? — pass me to match the authenticated user.
  • type: string?
  • labels: string[]?
  • maxResults: int = 50

get_task (read)​

Returns the full details of a task by its ID.

  • taskId: string (required)

create_task (write)​

Creates a task in the connected task tracker.

  • type: string (required)
  • title: string (required)
  • project: string? — required for Jira unless parentId is provided.
  • description: string? — supports Markdown.
  • assignee: string?
  • priority: string?
  • labels: string[]?
  • parentId: string?
  • customFields: dict<string,JsonElement>? — provider-specific fields as a JSON object. Each value is forwarded as-is, so use the JSON shape the provider's REST API expects. Jira: text fields take a bare string (Markdown in rich-text custom fields is converted to ADF); single-select takes {"value":"Option"}; multi-select takes [{"value":"A"},{"value":"B"}]; user-picker takes {"accountId":"…"}; number takes a raw number; date takes "YYYY-MM-DD". Use field IDs such as customfield_10001. Azure DevOps: use reference names like System.AreaPath or Custom.YourField with the type the field expects. For Html- or History-typed fields (e.g. Repro Steps, Acceptance Criteria, custom HTML fields), pass Markdown — it's converted to HTML on the way out.

update_task (write)​

Updates one or more fields on an existing task. At least one field must be supplied.

  • taskId: string (required)
  • title: string?
  • description: string? — supports Markdown.
  • assignee: string?
  • priority: string?
  • labels: string[]?
  • parentId: string?
  • customFields: dict<string,JsonElement>? — same shape and provider rules as on create_task.

transition_task (write)​

Moves a task to a new status. Optionally attaches a comment with the transition.

  • taskId: string (required)
  • targetStatus: string (required)
  • comment: string? — Markdown is supported.

manage_task_comments (write)​

Reads or posts comments on a task.

  • taskId: string (required)
  • action: string (required) — list returns every comment oldest-first (read-only); add posts a new comment (requires comment; needs write access).
  • comment: string? — required for action='add'. Markdown is supported.

Creates a link of the given type between two tasks, optionally with a comment. Use get_task_tracking_metadata with kind='link_types' first to discover available link types and their directionality.

  • linkType: string (required)
  • inwardTaskId: string (required)
  • outwardTaskId: string (required)
  • comment: string? — Markdown is supported.
Last updated on