Add dev tools

.github/workflows/auto-assign-on-comment.yaml → .github/workflows/auto-assign-on-comment.yml

@@ -6,7 +6,9 @@ permissions:
   issues: write
 jobs:
   assign:
-    runs-on: ubuntu-latest
+    runs-on:
+      group: databrickslabs-protected-runner-group
+      labels: linux-ubuntu-latest
     if: (!github.event.issue.pull_request) && contains(github.event.comment.body, 'take')
     concurrency:
       group: ${{ github.actor }}-auto-assign-issue

.github/workflows/unit_tests.yml

@@ -1,66 +1,43 @@
 name: Unit Tests
 
 on:
-  push:
-    paths:
-      - "servers/**"
-      - ".github/workflows/unit_tests.yml"
   pull_request:
-    paths:
-      - "servers/**"
-      - ".github/workflows/unit_tests.yml"
+    types: [opened, synchronize]
+  merge_group:
+    types: [checks_requested]
+  push:
+    # Always run on push to main. The build cache can only be reused
+    # if it was saved by a run from the repository's default branch.
+    # The run result will be identical to that from the merge queue
+    # because the commit is identical, yet we need to perform it to
+    # seed the build cache.
+    branches:
+      - master
 
 jobs:
-  discover:
-    runs-on:
-      group: databrickslabs-protected-runner-group
-      labels: linux-ubuntu-latest
-    outputs:
-      server_dirs: ${{ steps.set-matrix.outputs.server_dirs }}
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Discover server dirs with tests
-        id: set-matrix
-        run: |
-          dirs=$(find servers -mindepth 1 -maxdepth 1 -type d -exec test -d "{}/tests" \; -print | sed 's|servers/||' | jq -R . | jq -cs .)
-          echo "Found directories: $dirs"
-          echo "server_dirs=$dirs" >> "$GITHUB_OUTPUT"
-
-
 
   test:
-    needs: discover
     runs-on:
       group: databrickslabs-protected-runner-group
       labels: linux-ubuntu-latest
-    strategy:
-      matrix:
-        server-dir: ${{ fromJson(needs.discover.outputs.server_dirs) }}
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-
-      - name: Install dependencies with uv
-        working-directory: servers/${{ matrix.server-dir }}
-        run: |
-          uv sync
-          uv pip install --group dev
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
 
       - name: Run tests
-        working-directory: servers/${{ matrix.server-dir }}
         run: uv run pytest tests
+
   lint:
     runs-on:
       group: databrickslabs-protected-runner-group
@@ -69,15 +46,15 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
-      - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
 
       - name: Run lint checks
-        run: ./dev/lint.sh
+        run: make lint

.gitignore

@@ -120,3 +120,8 @@ a.md
 
 # Ignore a gunicorn config file
 gunicorn.conf.py
+
+# ignore version file
+src/databricks/labs/mcp/_version.py
+
+.ruff_cache/

CONTRIBUTING.md

@@ -10,11 +10,10 @@ before sending a pull request. For smaller changes (e.g. fixing a bug, adding a
 
 ### Running tests
 
-First, install test requirements from within the directory of the server you're working on:
+First, install all requirements from within the directory of the server you're working on:
 
 ```bash
 uv sync
-uv pip install --group dev
 ```
 
 To run tests:
@@ -25,7 +24,8 @@ uv run pytest tests
 
 To run and fix lint errors, run the following from the repo root directory:
 ```bash
-./dev/lint.sh --fix
+make fmt # to format code
+make lint # to run linters
 ```
 
 ### Guidelines for MCP servers

Makefile

@@ -0,0 +1,7 @@
+fmt:
+	uv run black .
+	uv run ruff check . --fix
+
+lint:
+	uv run black . --check
+	uv run ruff check .

README.md

@@ -2,25 +2,46 @@
 
 ![Test Status](https://github.com/databrickslabs/mcp/actions/workflows/unit_tests.yml/badge.svg)
 
+Table of Contents
+=================
+
+- [Databricks MCP servers](#databricks-mcp-servers)
+- [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Unity Catalog Server](#unity-catalog-server)
+    - [Overview](#overview-1)
+    - [Usage](#usage)
+    - [Supported tools](#supported-tools)
+  - [Developer Tools Server](#developer-tools-server)
+  - [Support](#support)
+  - [Contributing](#contributing)
+
 ## Overview
 An experimental collection of [MCP](https://modelcontextprotocol.io/introduction) servers to help AI agents fetch enterprise data from Databricks, automate common developer actions on Databricks, etc:
 
 * ![status: Beta](https://img.shields.io/badge/status-Beta-yellow?style=flat-square&logo=databricks)
-  [Databricks Unity Catalog server](./servers/unity_catalog/README.md): Fetch data and run tools registered in from Unity Catalog, making agents aware of your enterprise data
+  [Databricks Unity Catalog server](#unity-catalog-server): Fetch data and run tools registered in from Unity Catalog, making agents aware of your enterprise data
 * ![status: Under construction](https://img.shields.io/badge/status-Under_construction-red?style=flat-square&logo=databricks)
-  [Databricks developer tools server](./servers/developer_tools/README.md): Perform common developer actions in Databricks, like creating and updating notebooks, running jobs, etc. This server is not yet usable, but contributions are welcome!
+  [Databricks developer tools server](#developer-tools-server): Perform common developer actions in Databricks, like creating and updating notebooks, running jobs, etc. This server is not yet usable, but contributions are welcome! 
+  Note: if developing from within the Databricks product (e.g. using Databricks notebooks), we recommend using [Databricks Assistant](https://docs.databricks.com/aws/en/notebooks/databricks-assistant-faq)
 
 The set of servers and tools in this repo is fluid and will evolve over time. We welcome contributions to this repo - please first
 read the [contributor guidelines](CONTRIBUTING.md) to streamline the process and discover areas where help is needed.
 
-## Usage
-See the `README.md` in each server's directory for detailed instructions.
-For most servers, the following steps work: 
+## Unity Catalog Server
+
+![status: Beta](https://img.shields.io/badge/status-Beta-yellow?style=flat-square&logo=databricks)
+
+### Overview
+A Model Context Protocol server that exposes structured and unstructured data in Unity Catalog ([vector search indexes](https://docs.databricks.com/gcp/en/generative-ai/vector-search), [functions](https://docs.databricks.com/aws/en/generative-ai/agent-framework/create-custom-tool), and [Genie spaces](https://docs.databricks.com/aws/en/genie/)), as tools.
+
+<img src="docs/images/demo.png" alt="Demo image" height="400px">
 
+### Usage
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
 1. Install Python using `uv python install 3.12`
 1. [Configure Databricks credentials](https://docs.databricks.com/aws/en/dev-tools/cli/authentication) with access to the required APIs
-1. Add the server to your MCP client configuration. For example, to use the Databricks Unity Catalog MCP server with Claude Desktop, add the following to your `claude_desktop_config.json`:
+1. Add the server to your MCP client configuration. For example, to use this server with Claude Desktop, add the following to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -29,7 +50,7 @@ For most servers, the following steps work:
       "command": "/path/to/uv/executable/uv",
       "args": [
         "--directory",
-        "/path/to/this/repo/servers/unity_catalog",
+        "/path/to/this/repo",
         "run",
         "unitycatalog-mcp",
         "-s",
@@ -42,6 +63,20 @@ For most servers, the following steps work:
 }
 ```
 
+### Supported tools
+
+The list of tools supported by this server is dynamically inferred at startup time based on the functions and vector search indexes
+within the specified Unity Catalog schema, as well as any specified Genie spaces. In particular, the server exposes
+the following tools:
+
+* **UC Functions**: for each UC function, the server exposes a tool with the same name, arguments, and return type as the function
+* **Vector search indexes**: for each vector search index, the server exposes a tool for querying that vector search index
+* **Genie spaces**: for each Genie space, the server exposes tools for managing conversations and sending questions to the space
+
+## Developer Tools Server
+
+This server is currently under construction. It is not yet usable, but contributions are welcome!
+
 ## Support
 Please note that all projects in the `databrickslabs` GitHub organization are provided for your exploration only, and are not formally supported by Databricks with Service Level Agreements (SLAs).  They are provided AS-IS and we do not make any guarantees of any kind.  Please do not submit a support ticket relating to any issues arising from the use of these projects.
 

pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+
+name = "databricks-labs-mcp"
+dynamic = ["version", "readme"]
+description = "Databricks MCP servers"
+authors = [{ name = "renardeinside", email = "[email protected]" }]
+requires-python = ">=3.10"
+keywords = ["databricks", "unity catalog", "mcp", "agents", "llm", "automation", "genie"]
+
+dependencies = [
+    "mcp>=1.2.1",
+    "pydantic>=2.10.6",
+    "pydantic-settings>=2.7.1",
+    "unitycatalog-ai>=0.1.0",
+    "databricks-sdk>=0.49.0",
+    "databricks-openai>=0.3.1",
+]
+license-files = ["LICENSE", "NOTICE"]
+
+[tool.uv]
+dev-dependencies = [
+    "black>=25.1.0",
+    "pyright>=1.1.393",
+    "ruff>=0.9.4",
+    "pytest>=8.3.4",
+    "isort>=6.0.1",
+]
+
+[project.scripts]
+unitycatalog-mcp = "databricks.labs.mcp.servers.unity_catalog:main"
+
+[build-system]
+requires = ["hatchling", "hatch-fancy-pypi-readme", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+# for compatability with databricks.labs.* layout
+[tool.hatch.build]
+sources = ["src"]
+include = ["src"]
+
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/databricks/labs/mcp/_version.py"
+
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+# replace relative links with absolute links
+pattern = '\[(.+?)\]\(((?!https?://)\S+?)\)'
+replacement = '[\1](https://github.com/databrickslabs/mcp/tree/main/\g<2>)'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+# replace relative image links with absolute links
+pattern = '<img (.*?)src="((?!https?://)\S+?)"(.*?)>'
+replacement = '<img \1src="https://raw.githubusercontent.com/databrickslabs/mcp/refs/heads/main/\g<2>"\g<3>>'
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"