🍱 restructure project to make it databricks.labs compliant

🍱 restructure project to make it `databricks.labs` compliant

Author: renardeinside

.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,45 @@
 
 ![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
 * ![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](): Perform common developer actions in Databricks, like creating and updating notebooks, running jobs, etc. This server is not yet usable, but contributions are welcome!
 
 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 +49,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 +62,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.
 

dev/lint.sh

@@ -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_*"