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.

  • 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?
  • searchContent: bool = false
  • maxResults: int = 200

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.

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?

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,string>?

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?

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?
Last updated on