From 74f3a21cb056563665fd7d9aaa1da3a62295c145 Mon Sep 17 00:00:00 2001 From: bobby-smedley Date: Wed, 15 Apr 2026 10:12:55 -0400 Subject: [PATCH 1/2] docs: add missing asset creation tools to README and SKILLS --- README.md | 48 ++++++++++++++++++++++++++---------------------- SKILLS.md | 19 +++++++++++++++++++ 2 files changed, 45 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 3ed745e..ab73ea7 100644 --- a/README.md +++ b/README.md @@ -6,28 +6,32 @@ A Model Context Protocol (MCP) server that provides AI agents with access to Col This Go-based MCP server acts as a bridge between AI applications and Collibra, enabling intelligent data discovery and governance operations through the following tools: -- [`add_data_classification_match`](pkg/tools/add_data_classification_match.go) - Associate a data class with an asset -- [`discover_business_glossary`](pkg/tools/discover_business_glossary.go) - Ask questions about terms and definitions -- [`discover_data_assets`](pkg/tools/discover_data_assets.go) - Query available data assets using natural language -- [`get_asset_details`](pkg/tools/get_asset_details.go) - Retrieve detailed information about specific assets by UUID -- [`get_business_term_data`](pkg/tools/get_business_term_data.go) - Trace a business term back to its connected physical data assets -- [`get_column_semantics`](pkg/tools/get_column_semantics.go) - Retrieve data attributes, measures, and business assets connected to a column -- [`get_measure_data`](pkg/tools/get_measure_data.go) - Trace a measure back to its underlying physical columns and tables -- [`get_table_semantics`](pkg/tools/get_table_semantics.go) - Retrieve the semantic layer for a table: columns, data attributes, and connected measures -- [`list_asset_types`](pkg/tools/list_asset_types.go) - List available asset types -- [`list_data_contract`](pkg/tools/list_data_contracts.go) - List data contracts with pagination -- [`pull_data_contract_manifest`](pkg/tools/pull_data_contract_manifest.go) - Download manifest for a data contract -- [`push_data_contract_manifest`](pkg/tools/push_data_contract_manifest.go) - Upload manifest for a data contract -- [`removedata_classification_match`](pkg/tools/remove_data_classification_match.go) - Remove a classification match -- [`search_asset_keyword`](pkg/tools/search_asset_keyword.go) - Wildcard keyword search for assets -- [`search_data_class`](pkg/tools/search_data_classes.go) - Search for data classes with filters -- [`search_data_classification_match`](pkg/tools/search_data_classification_matches.go) - Search for associations between data classes and assets -- [`get_lineage_entity`](pkg/tools/get_lineage_entity.go) - Get metadata about a specific entity in the technical lineage graph -- [`get_lineage_upstream`](pkg/tools/get_lineage_upstream.go) - Get upstream technical lineage (sources) for a data entity -- [`get_lineage_downstream`](pkg/tools/get_lineage_downstream.go) - Get downstream technical lineage (consumers) for a data entity -- [`search_lineage_entities`](pkg/tools/search_lineage_entities.go) - Search for entities in the technical lineage graph -- [`get_lineage_transformation`](pkg/tools/get_lineage_transformation.go) - Get details and logic of a specific data transformation -- [`search_lineage_transformations`](pkg/tools/search_lineage_transformations.go) - Search for transformations in the technical lineage graph +- [`add_business_term`](pkg/tools/add_business_term/) - Create a business term asset with definition and optional attributes +- [`add_data_classification_match`](pkg/tools/add_data_classification_match/) - Associate a data class with an asset +- [`create_asset`](pkg/tools/create_asset/) - Create a new data asset with optional attributes +- [`discover_business_glossary`](pkg/tools/discover_business_glossary/) - Ask questions about terms and definitions +- [`discover_data_assets`](pkg/tools/discover_data_assets/) - Query available data assets using natural language +- [`get_asset_details`](pkg/tools/get_asset_details/) - Retrieve detailed information about specific assets by UUID +- [`get_business_term_data`](pkg/tools/get_business_term_data/) - Trace a business term back to its connected physical data assets +- [`get_column_semantics`](pkg/tools/get_column_semantics/) - Retrieve data attributes, measures, and business assets connected to a column +- [`get_lineage_downstream`](pkg/tools/get_lineage_downstream/) - Get downstream technical lineage (consumers) for a data entity +- [`get_lineage_entity`](pkg/tools/get_lineage_entity/) - Get metadata about a specific entity in the technical lineage graph +- [`get_lineage_transformation`](pkg/tools/get_lineage_transformation/) - Get details and logic of a specific data transformation +- [`get_lineage_upstream`](pkg/tools/get_lineage_upstream/) - Get upstream technical lineage (sources) for a data entity +- [`get_measure_data`](pkg/tools/get_measure_data/) - Trace a measure back to its underlying physical columns and tables +- [`get_table_semantics`](pkg/tools/get_table_semantics/) - Retrieve the semantic layer for a table: columns, data attributes, and connected measures +- [`list_asset_types`](pkg/tools/list_asset_types/) - List available asset types +- [`list_data_contract`](pkg/tools/list_data_contracts/) - List data contracts with pagination +- [`prepare_add_business_term`](pkg/tools/prepare_add_business_term/) - Validate business term data, resolve domains, and check for duplicates +- [`prepare_create_asset`](pkg/tools/prepare_create_asset/) - Resolve asset type, domain, hydrate attribute schema, and check duplicates +- [`pull_data_contract_manifest`](pkg/tools/pull_data_contract_manifest/) - Download manifest for a data contract +- [`push_data_contract_manifest`](pkg/tools/push_data_contract_manifest/) - Upload manifest for a data contract +- [`remove_data_classification_match`](pkg/tools/remove_data_classification_match/) - Remove a classification match +- [`search_asset_keyword`](pkg/tools/search_asset_keyword/) - Wildcard keyword search for assets +- [`search_data_class`](pkg/tools/search_data_classes/) - Search for data classes with filters +- [`search_data_classification_match`](pkg/tools/search_data_classification_matches/) - Search for associations between data classes and assets +- [`search_lineage_entities`](pkg/tools/search_lineage_entities/) - Search for entities in the technical lineage graph +- [`search_lineage_transformations`](pkg/tools/search_lineage_transformations/) - Search for transformations in the technical lineage graph ## Quick Start diff --git a/SKILLS.md b/SKILLS.md index e4cc2c4..c032593 100644 --- a/SKILLS.md +++ b/SKILLS.md @@ -15,6 +15,16 @@ Reach for Collibra tools when the user's question is about **understanding, disc ## Tool Inventory +### Asset Creation + +**`prepare_create_asset`** — Resolve asset type and domain by name or ID, hydrate the full attribute schema, and check for duplicates. Returns a structured status (`ready`, `incomplete`, `needs_clarification`, `duplicate_found`) with pre-fetched options for missing fields. **Always call this before `create_asset`** to obtain the resolved UUIDs and validate inputs. Read-only. + +**`create_asset`** — Create a new data asset in Collibra with optional attributes. Requires the resolved asset type UUID, domain UUID, and asset name — use the values returned by `prepare_create_asset`. Destructive (creates a new asset). + +**`prepare_add_business_term`** — Validate business term data, resolve domains by name, check for duplicates, and hydrate the attribute schema for the Business Term type. Returns structured status with pre-fetched options for missing fields. **Always call this before `add_business_term`**. Read-only. + +**`add_business_term`** — Create a business term asset with an optional definition and additional attributes. Requires the domain UUID — use the resolved domain from `prepare_add_business_term`. Destructive (creates a new asset). + ### Discovery & Search **`discover_data_assets`** — Natural language semantic search over data assets (tables, columns, datasets). Use when the user asks open-ended questions like "what data do we have about customers?". Requires `dgc.ai-copilot` permission. @@ -79,6 +89,14 @@ These tools query the technical lineage graph — a map of all data objects and ## Common Workflows +### Create any asset +1. `prepare_create_asset` with the asset name, asset type (publicId), and domain ID → check status is `ready` +2. `create_asset` with the resolved `assetTypeId` and `domainId` from step 1 + +### Add a business term +1. `prepare_add_business_term` with the term name and domain name or ID → check status is `ready` +2. `add_business_term` with the resolved `domainId` from step 1, plus optional definition and attributes + ### Find an asset and get its details 1. `search_asset_keyword` with the asset name → get UUID from results 2. `get_asset_details` with the UUID → get full attributes and relations @@ -119,6 +137,7 @@ These tools query the technical lineage graph — a map of all data objects and ## Tips +- **Always prepare before creating.** Call `prepare_create_asset` before `create_asset` and `prepare_add_business_term` before `add_business_term`, even if you already have the UUIDs. The prepare tools validate inputs, check for duplicates, and return the attribute schema. - **UUIDs are required for most tools.** When you only have a name, start with `search_asset_keyword` or the natural language discovery tools to get the UUID first. - **`discover_data_assets` vs `search_asset_keyword`**: Prefer `discover_data_assets` for open-ended semantic questions; prefer `search_asset_keyword` when you know the exact name or need to filter by type/community/domain. - **Permissions**: `discover_data_assets` and `discover_business_glossary` require the `dgc.ai-copilot` permission. Classification tools require `dgc.classify` + `dgc.catalog`. If a tool fails with a permission error, let the user know which permission is needed. From eeacb5ced3b6894a12a399462c724492127decb8 Mon Sep 17 00:00:00 2001 From: bobby-smedley Date: Wed, 15 Apr 2026 10:29:58 -0400 Subject: [PATCH 2/2] docs: split README into read/write sections --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ab73ea7..527dfa9 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,8 @@ A Model Context Protocol (MCP) server that provides AI agents with access to Col This Go-based MCP server acts as a bridge between AI applications and Collibra, enabling intelligent data discovery and governance operations through the following tools: -- [`add_business_term`](pkg/tools/add_business_term/) - Create a business term asset with definition and optional attributes -- [`add_data_classification_match`](pkg/tools/add_data_classification_match/) - Associate a data class with an asset -- [`create_asset`](pkg/tools/create_asset/) - Create a new data asset with optional attributes +### Read Tools + - [`discover_business_glossary`](pkg/tools/discover_business_glossary/) - Ask questions about terms and definitions - [`discover_data_assets`](pkg/tools/discover_data_assets/) - Query available data assets using natural language - [`get_asset_details`](pkg/tools/get_asset_details/) - Retrieve detailed information about specific assets by UUID @@ -25,14 +24,20 @@ This Go-based MCP server acts as a bridge between AI applications and Collibra, - [`prepare_add_business_term`](pkg/tools/prepare_add_business_term/) - Validate business term data, resolve domains, and check for duplicates - [`prepare_create_asset`](pkg/tools/prepare_create_asset/) - Resolve asset type, domain, hydrate attribute schema, and check duplicates - [`pull_data_contract_manifest`](pkg/tools/pull_data_contract_manifest/) - Download manifest for a data contract -- [`push_data_contract_manifest`](pkg/tools/push_data_contract_manifest/) - Upload manifest for a data contract -- [`remove_data_classification_match`](pkg/tools/remove_data_classification_match/) - Remove a classification match - [`search_asset_keyword`](pkg/tools/search_asset_keyword/) - Wildcard keyword search for assets - [`search_data_class`](pkg/tools/search_data_classes/) - Search for data classes with filters - [`search_data_classification_match`](pkg/tools/search_data_classification_matches/) - Search for associations between data classes and assets - [`search_lineage_entities`](pkg/tools/search_lineage_entities/) - Search for entities in the technical lineage graph - [`search_lineage_transformations`](pkg/tools/search_lineage_transformations/) - Search for transformations in the technical lineage graph +### Write Tools + +- [`add_business_term`](pkg/tools/add_business_term/) - Create a business term asset with definition and optional attributes +- [`add_data_classification_match`](pkg/tools/add_data_classification_match/) - Associate a data class with an asset +- [`create_asset`](pkg/tools/create_asset/) - Create a new data asset with optional attributes +- [`push_data_contract_manifest`](pkg/tools/push_data_contract_manifest/) - Upload manifest for a data contract +- [`remove_data_classification_match`](pkg/tools/remove_data_classification_match/) - Remove a classification match + ## Quick Start ### Prerequisites