diff --git a/.github/workflows/build-and-publish.yml b/.github/workflows/build-and-publish.yml index 4210532..0887c5e 100644 --- a/.github/workflows/build-and-publish.yml +++ b/.github/workflows/build-and-publish.yml @@ -15,10 +15,10 @@ jobs: contents: write steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Build Artifacts run: poetry build diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml index 835095d..1fb0e2e 100644 --- a/.github/workflows/cd.yml +++ b/.github/workflows/cd.yml @@ -4,6 +4,7 @@ on: push: tags: - '**' + - '!v*' jobs: @@ -14,6 +15,7 @@ jobs: contents: read cd-job: + needs: [ check-tag-version-job ] name: Continuous Delivery uses: ./.github/workflows/build-and-publish.yml permissions: @@ -29,4 +31,3 @@ jobs: contents: read pages: write id-token: write - diff --git a/.github/workflows/check-release-tag.yml b/.github/workflows/check-release-tag.yml index 8f69a2f..fc8c8ae 100644 --- a/.github/workflows/check-release-tag.yml +++ b/.github/workflows/check-release-tag.yml @@ -12,10 +12,10 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Check Tag Version # make sure the pushed/created tag matched the project version diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 4ed59d8..7c4fe83 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -11,38 +11,36 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Check Version(s) run: poetry run -- nox -s version:check - # Will be re-enabled once the User Guide is moved to sphinx - # - # Documentation: - # name: Docs - # needs: [ Version-Check ] - # runs-on: ubuntu-24.04 - # permissions: - # contents: read - # steps: - # - name: SCM Checkout - # uses: actions/checkout@v4 - # - # - name: Setup Python & Poetry Environment - # uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 - # - # - name: Build Documentation - # run: | - # poetry run -- nox -s docs:build - # - # - name: Link Check - # run: | - # poetry run -- nox -s links:check + Documentation: + name: Docs + needs: [ Version-Check ] + runs-on: ubuntu-24.04 + permissions: + contents: read + steps: + - name: SCM Checkout + uses: actions/checkout@v5 + + - name: Setup Python & Poetry Environment + uses: exasol/python-toolbox/.github/actions/python-environment@v1 + + - name: Build Documentation + run: | + poetry run -- nox -s docs:build + + - name: Link Check + run: | + poetry run -- nox -s links:check build-matrix: name: Generate Build Matrix @@ -58,10 +56,10 @@ jobs: if: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/master' }} steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Run changelog update check run: poetry run -- nox -s changelog:updated @@ -77,10 +75,10 @@ jobs: matrix: ${{ fromJson(needs.build-matrix.outputs.matrix) }} steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -88,7 +86,7 @@ jobs: run: poetry run -- nox -s lint:code - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: lint-python${{ matrix.python-version }} path: | @@ -108,10 +106,10 @@ jobs: steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -130,10 +128,10 @@ jobs: steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -141,7 +139,7 @@ jobs: run: poetry run -- nox -s lint:security - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: security-python${{ matrix.python-version }} path: .security.json @@ -154,32 +152,46 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Run format check run: poetry run -- nox -s project:format + Build-Packages: + name: Build Package Check + needs: [ Documentation, Lint, Type-Check, Security, Format ] + runs-on: ubuntu-24.04 + permissions: + contents: read + steps: + - name: SCM Checkout + uses: actions/checkout@v5 + + - name: Setup Python & Poetry Environment + uses: exasol/python-toolbox/.github/actions/python-environment@v1 + + - name: Run Distribution Check + run: poetry run -- nox -s package:check + Tests: name: Unit-Tests (Python-${{ matrix.python-version }}) - needs: [ Lint, Type-Check, Security, Format, build-matrix ] + needs: [ Build-Packages, build-matrix ] runs-on: ubuntu-24.04 permissions: contents: read - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} strategy: fail-fast: false matrix: ${{ fromJson(needs.build-matrix.outputs.matrix) }} steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -187,7 +199,7 @@ jobs: run: poetry run -- nox -s test:unit -- --coverage - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: coverage-python${{ matrix.python-version }}-fast path: .coverage diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 305dbe6..b2d9ee5 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -12,12 +12,12 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Build Documentation run: | diff --git a/.github/workflows/matrix-all.yml b/.github/workflows/matrix-all.yml index 1e51af9..8cdb5b1 100644 --- a/.github/workflows/matrix-all.yml +++ b/.github/workflows/matrix-all.yml @@ -14,10 +14,10 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Generate matrix run: poetry run -- nox -s matrix:all diff --git a/.github/workflows/matrix-exasol.yml b/.github/workflows/matrix-exasol.yml index 577910b..fd3225b 100644 --- a/.github/workflows/matrix-exasol.yml +++ b/.github/workflows/matrix-exasol.yml @@ -14,10 +14,10 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Generate matrix run: poetry run -- nox -s matrix:exasol diff --git a/.github/workflows/matrix-python.yml b/.github/workflows/matrix-python.yml index 6c26e57..404e246 100644 --- a/.github/workflows/matrix-python.yml +++ b/.github/workflows/matrix-python.yml @@ -14,10 +14,10 @@ jobs: contents: read steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Generate matrix run: poetry run -- nox -s matrix:python diff --git a/.github/workflows/report.yml b/.github/workflows/report.yml index 7442494..3222943 100644 --- a/.github/workflows/report.yml +++ b/.github/workflows/report.yml @@ -14,15 +14,15 @@ jobs: steps: - name: SCM Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 - name: Download Artifacts - uses: actions/download-artifact@v4.2.1 + uses: actions/download-artifact@v6 with: path: ./artifacts @@ -41,7 +41,7 @@ jobs: run: poetry run -- nox -s project:report -- --format json | tee metrics.json - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: metrics.json path: metrics.json diff --git a/.github/workflows/slow-checks-itde.yml b/.github/workflows/slow-checks-itde.yml index 301638b..78f2122 100644 --- a/.github/workflows/slow-checks-itde.yml +++ b/.github/workflows/slow-checks-itde.yml @@ -32,7 +32,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -44,7 +44,7 @@ jobs: poetry run -- nox -s test:integration -- -s --coverage --db-version ${{ matrix.exasol-version }} --backend=onprem --itde-additional-db-parameter="$JWK_URL" --itde-additional-db-parameter="$TOK_AUD" --itde-additional-db-parameter="$TOK_ISS" - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: coverage-python${{ matrix.python-version }}-itde path: .coverage diff --git a/.github/workflows/slow-checks-saas.yml b/.github/workflows/slow-checks-saas.yml index c05fe3a..f2595ba 100644 --- a/.github/workflows/slow-checks-saas.yml +++ b/.github/workflows/slow-checks-saas.yml @@ -32,7 +32,7 @@ jobs: uses: actions/checkout@v4 - name: Setup Python & Poetry Environment - uses: exasol/python-toolbox/.github/actions/python-environment@1.6.1 + uses: exasol/python-toolbox/.github/actions/python-environment@v1 with: python-version: ${{ matrix.python-version }} @@ -44,7 +44,7 @@ jobs: run: poetry run -- nox -s test:integration -- -s --coverage --db-version ${{ matrix.exasol-version }} --backend=saas - name: Upload Artifacts - uses: actions/upload-artifact@v4.6.2 + uses: actions/upload-artifact@v5 with: name: coverage-python${{ matrix.python-version }}-saas path: .coverage diff --git a/README.md b/README.rst similarity index 53% rename from README.md rename to README.rst index 5ebdb74..af0b0c6 100644 --- a/README.md +++ b/README.rst @@ -1,54 +1,66 @@ -# Exasol MCP Server - -

- - - License - - - Downloads - - - Supported Python Versions - - - PyPi Package - -

+Exasol MCP Server +================= Provides an LLM access to the Exasol database via MCP tools. Includes the tools for reading the database metadata and executing data reading queries. -## Features +.. image:: https://img.shields.io/pypi/l/exasol-mcp-server + :target: https://opensource.org/licenses/MIT + :alt: License + +.. image:: https://img.shields.io/pypi/dm/exasol-mcp-server + :target: https://pypi.org/project/exasol-mcp-server/ + :alt: Downloads + +.. image:: https://img.shields.io/pypi/pyversions/exasol-mcp-server + :target: https://pypi.org/project/exasol-mcp-server/ + :alt: Supported Python Versions + +.. image:: https://img.shields.io/pypi/v/exasol-mcp-server + :target: https://pypi.org/project/exasol-mcp-server/ + :alt: PyPi Package + +🚀 Features +----------- + +* Collects the metadata. -- Collects the metadata. * Enumerates the existing database objects, including schemas, tables, views, functions and UDF scripts. * Provides a filtering mechanisms to use with object enumeration. * Describes the database objects: for tables returns the list of columns and constraints; for functions and scripts - the list of input and output parameters. -- Executes provided data reading SQL query. Disallows any other type of query. + * Enables keyword search of database objects. + +* Executes provided SQL query. + +🔌️ Prerequisites +----------------- -## Prerequisites +* `Python `__ >= 3.10 +* MCP Client application, e.g. `Claude Desktop `__ -- [Python](https://www.python.org/) >= 3.10. -- MCP Client application, e.g. [Claude Desktop](https://claude.ai/download). +💾 Installation +--------------- -## Installation +Ensure the *uv* package is installed. If uncertain call -Ensure the `uv` package is installed. If uncertain call -```bash -uv --version -``` -To install `uv` on macOS please use `brew`, i.e. -```bash -brew install uv -``` -For other operating systems, please follow [the instructions](https://docs.astral.sh/uv/getting-started/installation/) -in the `uv` official documentation. +.. code-block:: shell -## Using the server with the Claude Desktop. + uv --version + +To install *uv* on macOS please use *brew*, i.e. + +.. code-block:: shell + + brew install uv + +For other operating systems, please follow `the instructions `__ +in the *uv* official documentation. + +🧠 Using the server with the Claude Desktop +------------------------------------------- To enable the Claude Desktop using the Exasol MCP server, the latter must be listed -in the configuration file `claude_desktop_config.json`. A similar configuration file +in the configuration file *claude_desktop_config.json*. A similar configuration file would exist for most other MCP Client applications. To find the Claude Desktop configuration file, click on the Settings and navigate to the @@ -58,83 +70,95 @@ the editor of your choice. Add the Exasol MCP server to the list of MCP servers as shown in this configuration example. -```json -{ - "mcpServers": { - "exasol_db": { - "command": "uvx", - "args": ["exasol-mcp-server@latest"], - "env": { - "EXA_DSN": "my-dsn", - "EXA_USER": "my-user-name", - "EXA_PASSWORD": "my-password" - } - }, - "other_server": {} - } -} -``` - -With these settings, `uv` will execute the latest version of the `exasol-mcp-server` + +.. code-block:: json + + { + "mcpServers": { + "exasol_db": { + "command": "uvx", + "args": ["exasol-mcp-server@latest"], + "env": { + "EXA_DSN": "my-dsn", + "EXA_USER": "my-user-name", + "EXA_PASSWORD": "my-password" + } + } + } + } + + +With these settings, *uv* will execute the latest version of the `exasol-mcp-server` in an ephemeral environment, without installing it. Alternatively, the `exasol-mcp-server` can be installed using the command: -```bash -uv tool install exasol-mcp-server@latest -``` -For further details on installing and upgrading the server using `uv` see the -[uv Tools](https://docs.astral.sh/uv/concepts/tools/) documentation. + +.. code-block:: shell + + uv tool install exasol-mcp-server@latest + +For further details on installing and upgrading the server using *uv* see the +`uv Tools `__ documentation. If the server is installed, the Claude configuration file should look like this: -```json -{ - "mcpServers": { - "exasol_db": { - "command": "exasol-mcp-server", - "env": "same as above" + +.. code-block:: json + + { + "mcpServers": { + "exasol_db": { + "command": "exasol-mcp-server", + "env": "same as above" + } + } } - } -} -``` Please note that any changes to the Claude configuration file will only take effect after restarting Claude Desktop. -## Running modes +🟠 🟢 Running modes +------------------- The MCP server can be deployed either locally, as described above, or as a remote HTTP server. To run the server as a Direct HTTP Server execute the command: -```bash -exasol-mcp-server-http --host --port -``` -The `host` defaults to 0.0.0.0. +.. code-block:: shell + + exasol-mcp-server-http --host --port + +The *host* defaults to 0.0.0.0. This command provides a simple way to verify the setup for a remote MCP Server deployment. For the production environment, one might consider using an ASGI server like Unicorn. The most flexible approach is implementing a wrapper for the Exasol MCP server that will provide the desired control options. For further information and ideas, please check the -[HTTP Deployment](https://gofastmcp.com/deployment/http) in the FastMCP documentation. +`HTTP Deployment `__ in the FastMCP documentation. Here is an example code creating the Exasol MCP server from a wrapper. -```python -from exasol.ai.mcp.server import mcp_server -exasol_mcp = mcp_server() -``` +.. code-block:: python + + from exasol.ai.mcp.server import mcp_server + + exasol_mcp = mcp_server() -## Configuration settings + +🔧 Configuration settings +------------------------- The server is configured using environment variables and optionally a json file. In the above example, the server is provided with the database connection parameters, all other settings left to default. For the information on how to customize server settings -please see the [Server Setup User Guide](doc/user_guide/server_setup.md). +please see the `Server Setup `_ +in the User Guide. -## License +📜 License +---------- This project is licensed under the MIT License - see the LICENSE file for details. -### Safe Harbor Statement: Exasol MCP Server & AI Solutions +Safe Harbor Statement: Exasol MCP Server & AI Solutions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Exasol’s AI solutions (including MCP Server) are designed to enable intelligent, autonomous, and highly performant access to data through AI and LLM-powered agents. @@ -153,3 +177,8 @@ and system owner, assume full responsibility for managing these solutions within environment. This includes establishing appropriate governance, authorization controls, sandboxing mechanisms, and operational guardrails to mitigate risks to your organization, your customers, and their data. + +📚 Documentation +---------------- + +For further details, check out the latest `documentation `_. diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index e106470..e82b3d2 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -9,3 +9,7 @@ ## Refactoring * #90: Disabled OIDC tests with OAuthProxy. + +## Documentation + +* #94: Moved the documentation from md to rst diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..d266224 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,91 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../")) + +# -- Project information ----------------------------------------------------- + +project = "Exasol MCP Server" +copyright = "2025, Exasol" # pylint: disable=redefined-builtin +author = "Exasol" + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.todo", + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.autosummary", + "sphinx_copybutton", + "myst_parser", + "sphinx_design", + "exasol.toolbox.sphinx.multiversion", +] + +intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} + +# Make sure the target is unique +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} + +todo_include_todos = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".build-docu"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "shibuya" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_title = "Exasol MCP Server" +html_theme_options = { + "light_logo": "_static/light-exasol-logo.svg", + "dark_logo": "_static/dark-exasol-logo.svg", + "github_url": "https://github.com/exasol/mcp-server", + "accent_color": "grass", +} + +# -- Configure link checking behavior ---------------------------------------- +linkcheck_rate_limit_timeout = 60 +linkcheck_timeout = 15 +linkcheck_delay = 30 +linkcheck_retries = 2 +linkcheck_anchors = False +linkcheck_ignore: list[str] = [] +linkcheck_allowed_redirects = { + # All HTTP redirections from the source URI to + # the canonical URI will be treated as "working". + r"https://github\.com/.*": r"https://github\.com/login*" +} diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst new file mode 100644 index 0000000..c8a3c48 --- /dev/null +++ b/doc/developer_guide/developer_guide.rst @@ -0,0 +1,6 @@ +.. _developer_guide: + +:octicon:`tools` Developer Guide +================================ + +To be provided. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..2784d3a --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,27 @@ +Documentation of Exasol MCP Server +----------------------------------- + +.. grid:: 1 1 3 2 + :gutter: 2 + :padding: 0 + :class-container: surface + + .. grid-item-card:: :octicon:`person` User Guide + :link: user_guide + :link-type: ref + + Resource for users to understand how to utilize this project and its features. + + .. grid-item-card:: :octicon:`tools` Developer Guide + :link: developer_guide + :link-type: ref + + Instructions and best practices to help developers contribute to the project and set up their development environment. + +.. toctree:: + :maxdepth: 4 + :hidden: + + user_guide/user_guide + developer_guide/developer_guide + changes/changelog diff --git a/doc/user_guide/db_connection_setup.md b/doc/user_guide/db_connection_setup.rst similarity index 62% rename from doc/user_guide/db_connection_setup.md rename to doc/user_guide/db_connection_setup.rst index ce41477..8d66186 100644 --- a/doc/user_guide/db_connection_setup.md +++ b/doc/user_guide/db_connection_setup.rst @@ -1,49 +1,66 @@ -# Database Connection Setup +Database Connection Setup +========================= The MCP server supports two user authentication methods available in Exasol database - password and an OpenID token. The MCP server can be deployed in two ways: locally or as a remote HTTP server. In the latter case, the server works in the multiple-user mode, and its tools must be -protected with OAuth2 authorization. Please refer to [OpenID Setup](open_id_setup.md) +protected with OAuth2 authorization. Please refer to :doc:`open_id_setup` guide for details on the OAuth configuration. The choice of the database connection parameters depends on the MCP server deployment mode. This section of the User Guide explains possible deployment options in the context of the database connection and lists the expected environment variables in each of these cases. -## Local MCP Server +Local MCP Server +---------------- In this mode, the server should be configured to use particular database credentials, e.g. username and password (On-Prem). Presumably, these will be Exasol credentials given to the user of an AI Application hosting the MCP server. The application is running on the user's machine. -### On-Prem Backend +On-Prem Backend +^^^^^^^^^^^^^^^ ++----------------------------------------+----------+ | Variable Name | Required | -|----------------------------------------|:--------:| ++========================================+==========+ | EXA_DSN (e.g. demodb.exasol.com:8563") | yes | ++----------------------------------------+----------+ | EXA_USER | yes | ++----------------------------------------+----------+ | EXA_PASSWORD | no | ++----------------------------------------+----------+ | EXA_ACCESS_TOKEN | no | ++----------------------------------------+----------+ | EXA_REFRESH_TOKEN | no | ++----------------------------------------+----------+ One of the EXA_PASSWORD, EXA_ACCESS_TOKEN, EXA_REFRESH_TOKEN must be provided, depending on how the EXA_USER is identified. -### SaaS Backend +SaaS Backend +^^^^^^^^^^^^ ++------------------------------------------------------+----------+ | Variable Name | Required | -|------------------------------------------------------|:--------:| ++======================================================+==========+ | EXA_SAAS_HOST (defaults to https://cloud.exasol.com) | no | ++------------------------------------------------------+----------+ | EXA_SAAS_ACCOUNT_ID | yes | ++------------------------------------------------------+----------+ | EXA_SAAS_PAT (Personal Access Token) | yes | ++------------------------------------------------------+----------+ | EXA_SAAS_DATABASE_ID | no | ++------------------------------------------------------+----------+ | EXA_SAAS_DATABASE_NAME | no | ++------------------------------------------------------+----------+ Either EXA_SAAS_DATABASE_ID or EXA_SAAS_DATABASE_NAME must be provided, -## HTTP MCP Server +HTTP MCP Server +--------------- This is the multiuser setup. The MCP Server may be able to identify the user, if the server authorization is configured in a certain way. The username can be stored in one @@ -54,7 +71,8 @@ the name of this claim. Being able to identify the user gives two possibilities for making the database connection user special. -### Passthrough Access Token (On-Prem) +Passthrough Access Token (On-Prem) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Under certain conditions, the access token can be extracted from the MCP Authentication context and used to open the database connection on behalf of the user calling an MCP @@ -70,16 +88,21 @@ refresh token. Currently, the refresh token identification is not supported. Thi doesn't mean the identity provider cannot use a refresh token. If it does, the MCP client will request access token regeneration when its validity period expires. ++----------------------------------------+----------+ | Variable Name | Required | -|----------------------------------------|:--------:| ++========================================+==========+ | EXA_DSN (e.g. demodb.exasol.com:8563") | yes | ++----------------------------------------+----------+ | EXA_USERNAME_CLAIM | yes | ++----------------------------------------+----------+ | EXA_POOL_SIZE | no | ++----------------------------------------+----------+ EXA_USERNAME_CLAIM is where the name of the username claim should be provided. EXA_POOL_SIZE is the maximum size of the connection pool, defaults to 5. -### User Impersonation (On-Prem) +User Impersonation (On-Prem) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the users are not identified by access tokens in the database, but their names can be made visible through a claim, it is possible to make the connection using a separate MCP @@ -88,37 +111,53 @@ executed by the server tools will be subject to permissions of the user who init the request. For this to work, the server's own credentials must have the "IMPERSONATE ANY USER" or "IMPERSONATION ON " privileges. ++----------------------------------------+----------+ | Variable Name | Required | -|----------------------------------------|:--------:| ++========================================+==========+ | EXA_DSN (e.g. demodb.exasol.com:8563") | yes | ++----------------------------------------+----------+ | EXA_USER | yes | ++----------------------------------------+----------+ | EXA_PASSWORD | no | ++----------------------------------------+----------+ | EXA_ACCESS_TOKEN | no | ++----------------------------------------+----------+ | EXA_REFRESH_TOKEN | no | ++----------------------------------------+----------+ | EXA_USERNAME_CLAIM | yes | ++----------------------------------------+----------+ | EXA_POOL_SIZE | no | ++----------------------------------------+----------+ Here, EXA_USER is the server's own username. One of the EXA_PASSWORD, EXA_ACCESS_TOKEN, EXA_REFRESH_TOKEN must be provided, depending on how the server's username is identified. -### Passthrough PAT (SaaS) +Passthrough PAT (SaaS) +^^^^^^^^^^^^^^^^^^^^^^ For this option, the MCP Client should be configured to pass the user's PAT in the HTTP headers, e.g. as X-API-KEY. The exact name of the header doesn't matter, so long as the MCP Server knows it. Apart from that, the configuration of the SaaS backend connection is similar to the local deployment case. ++------------------------------------------------------+----------+ | Variable Name | Required | -|------------------------------------------------------|:--------:| ++======================================================+==========+ | EXA_SAAS_HOST (defaults to https://cloud.exasol.com) | no | ++------------------------------------------------------+----------+ | EXA_SAAS_ACCOUNT_ID | yes | ++------------------------------------------------------+----------+ | EXA_SAAS_PAT_HEADER | yes | ++------------------------------------------------------+----------+ | EXA_SAAS_DATABASE_ID | no | ++------------------------------------------------------+----------+ | EXA_SAAS_DATABASE_NAME | no | ++------------------------------------------------------+----------+ Either EXA_SAAS_DATABASE_ID or EXA_SAAS_DATABASE_NAME must be provided, -### Delegated database access +Delegated database access +^^^^^^^^^^^^^^^^^^^^^^^^^ This is a backup option for the case when the user cannot be identified or the server's username cannot be granted the impersonation privilege. In principle, it is identical to @@ -128,15 +167,24 @@ is concerned, this is irrelevant. To keep the database access integrity, the ser username must have the permission that is the least common denominator of the permissions of the users allowed to access the MCP server. -## SSL Options +SSL Options +----------- Exasol MCP Server supports configuration of the Transport Layer Security (TLS) or Secure Sockets Layer (SSL) protocols. Below is a list of TLS/SSL options that can be specified. These options are applicable to all connection modes described above. -| Variable Name | Description | -|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| -| EXA_SSL_CERT_VALIDATION (defaults to true) | Other peers’ certificate verification (true/false).
Can be set to false for testing purpose, but never in production. | -| EXA_SSL_TRUSTED_CA | Custom path to a directory with Certification Authority (CA) certificates,
or a single CA file. | -| EXA_SSL_CLIENT_CERT | Custom path to the own certificate file in PEM format. | -| EXA_SSL_PRIVATE_KEY | Path to the private key file, if separate from the certificate.
This SSL feature is currently not supported by the Exasol database. | ++--------------------------------------------+---------------------------------------------------------------------+ +| Variable Name | Description | ++============================================+=====================================================================+ +| EXA_SSL_CERT_VALIDATION (defaults to true) | Other peers’ certificate verification (true/false). | +| | Can be set to false for testing purpose, but never in production. | ++--------------------------------------------+---------------------------------------------------------------------+ +| EXA_SSL_TRUSTED_CA | Custom path to a directory with Certification Authority (CA) | +| | certificates, or a single CA file. | ++--------------------------------------------+---------------------------------------------------------------------+ +| EXA_SSL_CLIENT_CERT | Custom path to the own certificate file in PEM format. | ++--------------------------------------------+---------------------------------------------------------------------+ +| EXA_SSL_PRIVATE_KEY | Path to the private key file, if separate from the certificate. | +| | This SSL feature is currently not supported by the Exasol database. | ++--------------------------------------------+---------------------------------------------------------------------+ diff --git a/doc/user_guide/open_id_setup.md b/doc/user_guide/open_id_setup.md deleted file mode 100644 index 68402ac..0000000 --- a/doc/user_guide/open_id_setup.md +++ /dev/null @@ -1,169 +0,0 @@ -# OpenID Setup - -A production installation of the MCP server may require proper security configuration. -This is certainly the case if the server is deployed as an HTTP server. Then its tools -must be protected with an authorisation mechanism. This section of the User Guide -provides details on how Exasol MCP server can be configured in the remote deployment -scenario, i.e., as an HTTP server. - -The MCP supports and recommends OAuth2 as the authorization framework for protecting -the tools and resources from unauthorized access. OAuth2 and OpenID Connect are modern -and widely used specifications for resource protection. Exasol MCP server supports -OAuth2-based authorization to control access to its own tools, as well as the Exasol -database. The authentication options for the database connection are described in -the [Database Connection Setup](db_connection_setup.md) guide. This section focuses -on the configuration of the MCP Server authorization. - -It is assumed that the reader has some familiarity with the basic concepts of OAuth2. -Without going into details on how OAuth2 works, let us recap what roles exist in -this specification and how they map onto MCP interaction. - -The OAuth2 defines four actors: -- The resource with a certain API. -- The client, usually an application that wants to access the resource. -- The resource owner, usually a human, who can authorize the client to access the resource. -- The identity server, a service used to facilitate the authorization. - -In the MCP case, the resource API is the server tools, and the client is the MCP client -application, e.g. Claude Desktop. - -## OAuth in FastMCP - -The implementation of Exasol MCP Server is based on FastMCP package, hence its -authentication layer is based on [FastMCP Authentication](https://gofastmcp.com/servers/auth/authentication). -Exasol MCP Server supports all authentication mechanisms provided by FastMCP at the -moment of the release. However, the FastMCP authentication is currently in active -development. - -### FastMCP Integration with Identity Providers - -The FastMCP provides an integration with several popular OAuth providers. -At the time of writing, the following providers are supported: -- [Auth0](https://gofastmcp.com/integrations/auth0) -- [AuthKit](https://gofastmcp.com/integrations/authkit) -- [AWS Cognito](https://gofastmcp.com/integrations/aws-cognito) -- [Azure](https://gofastmcp.com/integrations/azure) -- [Descope](https://gofastmcp.com/integrations/descope) -- [GitHub](https://gofastmcp.com/integrations/github) -- [Scalekit](https://gofastmcp.com/integrations/scalekit) -- [Google](https://gofastmcp.com/integrations/google) -- [WorkOS](https://gofastmcp.com/integrations/workos) - -To configure the MCP authentication with any of these providers, please set the -environment variables, as described in the FastMCP documentation for a particular -provider. As an example, the following environment variables shall be set when -working with AuthKit: -```bash -export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.AuthKitProvider -export FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN=https://your-project.authkit.app -export FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_BASE_URL=https://your-server.com -``` -Note that the `FASTMCP_SERVER_AUTH` should always be set to the module path of the -provider's class. - -### FastMCP Generic OAuth Providers - -The FastMCP also provides three generic ways to configure the OAuth2 authentication. -- [Remote OAuth](https://gofastmcp.com/servers/auth/remote-oauth), to work with identity -servers supporting Dynamic Client Registration (DCR). -- [OAuth Proxy](https://gofastmcp.com/servers/auth/oauth-proxy), to work with identity -servers that do not support DCR. -- [Token Verification](https://gofastmcp.com/servers/auth/token-verification), for the -case when the MCP server only verifies a bearer token, not being concerned about how this -token is acquired. - -If the chosen identity provider is not in the above list, it should still be possible to -configure the MCP server authentication using one of those generic providers. Please use -[Remote OAuth](https://gofastmcp.com/servers/auth/remote-oauth) if the provider supports -DCR, and [OAuth Proxy](https://gofastmcp.com/servers/auth/oauth-proxy) if it doesn't. - -Currently, FastMCP does not define environment variables for generic providers. Exasol -MCP Server fills the gap by providing its own set of variables in a similar fashion. -As with specific providers, the variable `FASTMCP_SERVER_AUTH` should be set to the path -of the chosen generic auth provider class. The required value for this variable can be -found in one of the tables below. - -Normally, two sets of variables must be configured - one for a Token Verifier and another -one for the provider - Remote OAuth or OAuth Proxy. - -The tables below list all possible variables in each set. Note that the column `Required` -means whether the value is mandatory or not in the corresponding FastMCP module. An -optional (for FastMCP) variable may be required by a particular identity provider. One -need to check the provider's specification to find out what information should be supplied. - -The rest of this section provides information about the environment variables defined by -Exasol MCP Server. - -### Token Verification - -Both `Remote OAuth` and `OAuthProxy` require a [Token Verifier](https://gofastmcp.com/servers/auth/token-verification). -The choice of the token verifier depends on the token verification model supported by a -particular identity provider. - -At the time of writing, the latest release of the FastMCP - 2.12.5 - only offers the -JWT Token Verification. The Opaque Token Verification should be added soon. - -A token verifier provider may be the only module needed if the MCP Authentication uses -an externally supplied bearer token. However, this guide doesn't give any details on how -such a system could be configured. Also, in this scenario, we recommend using FastMCP's -[environment variables](https://gofastmcp.com/servers/auth/token-verification), not the Exasol ones. - -#### JWT Token Verification. - -| Variable Name | Required | Value | -|--------------------------|:--------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| EXA_AUTH_PUBLIC_KEY | no | For asymmetric algorithms (RS256, ES256, etc.): PEM-encoded public key.
For symmetric algorithms (HS256, HS384, HS512): The shared secret string. | -| EXA_AUTH_JWKS_URI | no | URI to fetch JSON Web Key Set (only for asymmetric algorithms). | -| EXA_AUTH_ISSUER | no | Expected issuer claim. | -| EXA_AUTH_AUDIENCE | no | Expected audience claim(s). | -| EXA_AUTH_ALGORITHM | no | JWT signing algorithm. Supported algorithms:
- Asymmetric: RS256/384/512, ES256/384/512, PS256/384/512 (default: RS256).
- Symmetric: HS256, HS384, HS512. | -| EXA_AUTH_REQUIRED_SCOPES | no | Required scopes for all tokens. | -| EXA_AUTH_BASE_URL | no | Base URL for TokenVerifier protocol. | - -Either of `EXA_AUTH_PUBLIC_KEY` or `EXA_AUTH_JWKS_URI` must be set. - -### Remote OAuth - -| Variable Name | Required | Value | -|---------------------------------|:--------:|---------------------------------------------------| -| FASTMCP_SERVER_AUTH | yes | fastmcp.server.auth.auth.RemoteAuthProvider. | -| EXA_AUTH_AUTHORIZATION_SERVERS | yes | List of identity servers that issue valid tokens. | -| EXA_AUTH_BASE_URL | yes | Base URL of the MCP server. | -| EXA_AUTH_RESOURCE_NAME | no | Name for the protected resource. | -| EXA_AUTH_RESOURCE_DOCUMENTATION | no | Documentation URL for the protected resource. | - -### OAuth Proxy - -| Variable Name | Required | Value | -|------------------------------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| FASTMCP_SERVER_AUTH | yes | fastmcp.server.auth.oauth_proxy.OAuthProxy | -| EXA_AUTH_UPSTREAM_AUTHORIZATION_ENDPOINT | yes | URL of upstream authorization endpoint. | -| EXA_AUTH_UPSTREAM_TOKEN_ENDPOINT | yes | URL of upstream token endpoint. | -| EXA_AUTH_UPSTREAM_CLIENT_ID | yes | Client ID registered with upstream server. | -| EXA_AUTH_UPSTREAM_CLIENT_SECRET | yes | Client secret for upstream server. | -| EXA_AUTH_UPSTREAM_REVOCATION_ENDPOINT | no | Optional upstream revocation endpoint. | -| EXA_AUTH_BASE_URL | yes | Public URL of the MCP server.
Redirect path is relative to this URL. | -| EXA_AUTH_REDIRECT_PATH | no | Redirect path configured in upstream OAuth app.
Defaults to "/auth/callback". | -| EXA_AUTH_ISSUER_URL | no | Issuer URL for OAuth metadata. Defaults to EXA_AUTH_BASE_URL. | -| EXA_AUTH_SERVICE_DOCUMENTATION_URL | no | Optional service documentation URL. | -| EXA_AUTH_ALLOWED_CLIENT_REDIRECT_URIS | no | List of allowed redirect URI patterns for MCP clients.
Patterns support wildcards (e.g., "http://localhost:*", "https://*.example.com/*").
If not set, only localhost redirect URIs are allowed.
These are for MCP clients performing loopback redirects,
NOT for the upstream OAuth app. | -| EXA_AUTH_VALID_SCOPES | no | List of all the possible valid scopes for a client. These are
advertised to clients through the `/.well-known` endpoints.
If not set, defaults to EXA_AUTH_REQUIRED_SCOPES. | -| EXA_AUTH_FORWARD_PKCE | no | Whether to forward PKCE to upstream server. Defaults to True.
Enable for providers that support/require PKCE (Google, Azure, AWS, etc.).
Disable only if upstream provider doesn't support PKCE. | -| EXA_AUTH_TOKEN_ENDPOINT_AUTH_METHOD | no | Token endpoint authentication method for upstream server.
Common values: "client_secret_basic","client_secret_post", "none".
If not set, the provider will use default (typically "client_secret_basic"). | -| EXA_AUTH_EXTRA_AUTHORIZE_PARAMS | no | Additional parameters to forward to the upstream authorization
endpoint. Useful for provider-specific parameters like Auth0's "audience".
Example: {"audience": "https://api.example.com"} | -| EXA_AUTH_EXTRA_TOKEN_PARAMS | no | Additional parameters to forward to the upstream token endpoint.
Useful for provider-specific parameters during token exchange. | - -## OpenID with SaaS Backend - -The information in this guide is mostly relevant to the On-Prem backend. The -authentication in SaaS backend is based on OpenID Connect (OIDC), which is an -authentication layer built on top of OAuth. For details please refer to the Exasol -SaaS [Access Management](https://docs.exasol.com/saas/administration/access_mngt/access_management.htm) -documentation, and in particular to the [Personal Access Token (PAT)](https://docs.exasol.com/saas/administration/access_mngt/access_token.htm) -section. - -Essentially, an Exasol SaaS user is issued a PAT. They need to pass this token to the -MCP Server. This can be done using an HTTP header, as described in the [Database Connection Setup](db_connection_setup.md) guide. - -Besides that, the MCP server tools can also be protected using one of the authorization -schemas described earlier in this guide, but in case of SaaS backend this is optional. diff --git a/doc/user_guide/open_id_setup.rst b/doc/user_guide/open_id_setup.rst new file mode 100644 index 0000000..8bd33b8 --- /dev/null +++ b/doc/user_guide/open_id_setup.rst @@ -0,0 +1,254 @@ +OpenID Setup +============ + +A production installation of the MCP server may require proper security configuration. +This is certainly the case if the server is deployed as an HTTP server. Then its tools +must be protected with an authorisation mechanism. This section of the User Guide +provides details on how Exasol MCP server can be configured in the remote deployment +scenario, i.e., as an HTTP server. + +The MCP supports and recommends OAuth2 as the authorization framework for protecting +the tools and resources from unauthorized access. OAuth2 and OpenID Connect are modern +and widely used specifications for resource protection. Exasol MCP server supports +OAuth2-based authorization to control access to its own tools, as well as the Exasol +database. The authentication options for the database connection are described in +the :doc:`db_connection_setup` guide. This section focuses +on the configuration of the MCP Server authorization. + +It is assumed that the reader has some familiarity with the basic concepts of OAuth2. +Without going into details on how OAuth2 works, let us recap what roles exist in +this specification and how they map onto MCP interaction. + +The OAuth2 defines four actors: +- The resource with a certain API. +- The client, usually an application that wants to access the resource. +- The resource owner, usually a human, who can authorize the client to access the resource. +- The identity server, a service used to facilitate the authorization. + +In the MCP case, the resource API is the server tools, and the client is the MCP client +application, e.g. Claude Desktop. + +OAuth in FastMCP +---------------- + +The implementation of Exasol MCP Server is based on FastMCP package, hence its +authentication layer is based on `FastMCP Authentication `__. +Exasol MCP Server supports all authentication mechanisms provided by FastMCP at the +moment of the release. However, the FastMCP authentication is currently in active +development. + +FastMCP Integration with Identity Providers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The FastMCP provides an integration with several popular OAuth providers. +At the time of writing, the following providers are supported: + +* `Auth0 `__ +* `AuthKit `__ +* `AWS Cognito `__ +* `Azure `__ +* `Descope `__ +* `GitHub `__ +* `Scalekit `__ +* `Google `__ +* `WorkOS `__ + +To configure the MCP authentication with any of these providers, please set the +environment variables, as described in the FastMCP documentation for a particular +provider. As an example, the following environment variables shall be set when +working with AuthKit: + +.. code-block:: shell + + export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.workos.AuthKitProvider + export FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_AUTHKIT_DOMAIN=https://your-project.authkit.app + export FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_BASE_URL=https://your-server.com + +Note that the ``FASTMCP_SERVER_AUTH`` should always be set to the module path of the +provider's class. + +FastMCP Generic OAuth Providers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The FastMCP also provides three generic ways to configure the OAuth2 authentication. + +* `Remote OAuth `__, + to work with identity servers supporting Dynamic Client Registration (DCR). +* `OAuth Proxy `__, + to work with identity servers that do not support DCR. +* `Token Verification `__, + for the case when the MCP server only verifies a bearer token, not being concerned about + how this token is acquired. + +If the chosen identity provider is not in the above list, it should still be possible to +configure the MCP server authentication using one of those generic providers. Please use +`Remote OAuth `__ if the provider supports +DCR, and `OAuth Proxy `__ if it doesn't. + +Currently, FastMCP does not define environment variables for generic providers. Exasol +MCP Server fills the gap by providing its own set of variables in a similar fashion. +As with specific providers, the variable ``FASTMCP_SERVER_AUTH`` should be set to the path +of the chosen generic auth provider class. The required value for this variable can be +found in one of t +he tables below. + +Normally, two sets of variables must be configured - one for a Token Verifier and another +one for the provider - Remote OAuth or OAuth Proxy. + +The tables below list all possible variables in each set. Note that the column *Required* +means whether the value is mandatory or not in the corresponding FastMCP module. An +optional (for FastMCP) variable may be required by a particular identity provider. One +need to check the provider's specification to find out what information should be supplied. + +The rest of this section provides information about the environment variables defined by +Exasol MCP Server. + +Token Verification +^^^^^^^^^^^^^^^^^^ + +Both *Remote OAuth* and *OAuthProxy* require a `Token Verifier `__. +The choice of the token verifier depends on the token verification model supported by a +particular identity provider. + +At the time of writing, the latest release of the FastMCP - 2.13.0 - offers two types of +verification - `JWT Token Verification `__ +and `Opaque Token Verification `__. +The variation of the former is `Static Public Key Verification `__. + +A token verifier provider may be the only module needed if the MCP Authentication uses +an externally supplied bearer token. However, this guide doesn't give any details on how +such a system could be configured. Also, in this scenario, we recommend using FastMCP's +`environment variables `__, not the Exasol ones. + +JWT Token Verification +++++++++++++++++++++++ + ++--------------------------+----------+-----------------------------------------------------------------------------+ +| Variable Name | Required | Value | ++==========================+==========+=============================================================================+ +| EXA_AUTH_PUBLIC_KEY | no | For asymmetric algorithms (RS256, ES256, etc.): PEM-encoded public key. | +| | | For symmetric algorithms (HS256, HS384, HS512): The shared secret string. | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_JWKS_URI | no | URI to fetch JSON Web Key Set (only for asymmetric algorithms). | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_ISSUER | no | Expected issuer claim. | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_AUDIENCE | no | Expected audience claim(s). | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_ALGORITHM | no | JWT signing algorithm. Supported algorithms: | +| | | - Asymmetric: RS256/384/512, ES256/384/512, PS256/384/512 (default: RS256). | +| | | - Symmetric: HS256, HS384, HS512. | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_REQUIRED_SCOPES | no | Required scopes for all tokens. | ++--------------------------+----------+-----------------------------------------------------------------------------+ +| EXA_AUTH_BASE_URL | yes | Base URL for TokenVerifier protocol. | ++--------------------------+----------+-----------------------------------------------------------------------------+ + +Either of ``EXA_AUTH_PUBLIC_KEY`` or ``EXA_AUTH_JWKS_URI`` must be set. + +Opaque Token Verification (Token Introspection) ++++++++++++++++++++++++++++++++++++++++++++++++ + ++----------------------------+----------+-----------------------------------------------------------------------+ +| Variable Name | Required | Value | ++============================+==========+=======================================================================+ +| EXA_AUTH_INTROSPECTION_URL | yes | URL of the OAuth token introspection endpoint. | ++----------------------------+----------+-----------------------------------------------------------------------+ +| EXA_AUTH_CLIENT_ID | yes | OAuth client ID for authenticating to the introspection endpoint. | ++----------------------------+----------+-----------------------------------------------------------------------+ +| EXA_AUTH_CLIENT_SECRET | yes | OAuth client secret for authenticating to the introspection endpoint. | ++----------------------------+----------+-----------------------------------------------------------------------+ +| EXA_AUTH_TIMEOUT_SECONDS | no | HTTP request timeout in seconds (default: 10). | ++----------------------------+----------+-----------------------------------------------------------------------+ +| EXA_AUTH_REQUIRED_SCOPES | no | Required scopes for all tokens. | ++----------------------------+----------+-----------------------------------------------------------------------+ +| EXA_AUTH_BASE_URL | yes | Base URL for TokenVerifier protocol. | ++----------------------------+----------+-----------------------------------------------------------------------+ + +Remote OAuth +^^^^^^^^^^^^ + ++---------------------------------+----------+---------------------------------------------------+ +| Variable Name | Required | Value | ++=================================+==========+===================================================+ +| FASTMCP_SERVER_AUTH | yes | fastmcp.server.auth.auth.RemoteAuthProvider. | ++---------------------------------+----------+---------------------------------------------------+ +| EXA_AUTH_AUTHORIZATION_SERVERS | yes | List of identity servers that issue valid tokens. | ++---------------------------------+----------+---------------------------------------------------+ +| EXA_AUTH_BASE_URL | yes | Base URL of the MCP server. | ++---------------------------------+----------+---------------------------------------------------+ +| EXA_AUTH_RESOURCE_NAME | no | Name for the protected resource. | ++---------------------------------+----------+---------------------------------------------------+ +| EXA_AUTH_RESOURCE_DOCUMENTATION | no | Documentation URL for the protected resource. | ++---------------------------------+----------+---------------------------------------------------+ + +OAuth Proxy +^^^^^^^^^^^ + ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| Variable Name | Required | Value | ++==========================================+==========+==============================================================================+ +| FASTMCP_SERVER_AUTH | yes | fastmcp.server.auth.oauth_proxy.OAuthProxy | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_UPSTREAM_AUTHORIZATION_ENDPOINT | yes | URL of upstream authorization endpoint. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_UPSTREAM_TOKEN_ENDPOINT | yes | URL of upstream token endpoint. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_UPSTREAM_CLIENT_ID | yes | Client ID registered with upstream server. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_UPSTREAM_CLIENT_SECRET | yes | Client secret for upstream server. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_UPSTREAM_REVOCATION_ENDPOINT | no | Optional upstream revocation endpoint. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_BASE_URL | yes | Public URL of the MCP server. | +| | | Redirect path is relative to this URL. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_REDIRECT_PATH | no | Redirect path configured in upstream OAuth app. | +| | | Defaults to ``/auth/callback``. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_ISSUER_URL | no | Issuer URL for OAuth metadata. Defaults to EXA_AUTH_BASE_URL. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_SERVICE_DOCUMENTATION_URL | no | Optional service documentation URL. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_ALLOWED_CLIENT_REDIRECT_URIS | no | List of allowed redirect URI patterns for MCP clients. | +| | | Patterns support wildcards | +| | | (e.g., ``http://localhost:*``, ``https://*.example.com/*``). | +| | | If not set, only localhost redirect URIs are allowed. | +| | | These are for MCP clients performing loopback redirects, | +| | | NOT for the upstream OAuth app. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_VALID_SCOPES | no | List of all the possible valid scopes for a client. These are | +| | | advertised to clients through the ``/.well-known`` endpoints. | +| | | If not set, defaults to EXA_AUTH_REQUIRED_SCOPES. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_FORWARD_PKCE | no | Whether to forward PKCE to upstream server. Defaults to True. | +| | | Enable for providers that support/require PKCE (Google, Azure, AWS, etc.). | +| | | Disable only if upstream provider doesn't support PKCE. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_TOKEN_ENDPOINT_AUTH_METHOD | no | Token endpoint authentication method for upstream server. | +| | | Common values: "client_secret_basic","client_secret_post", "none". | +| | | If not set, the provider will use default (typically "client_secret_basic"). | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_EXTRA_AUTHORIZE_PARAMS | no | Additional parameters to forward to the upstream authorization endpoint. | +| | | Useful for provider-specific parameters like Auth0's "audience". | +| | | Example: {"audience": ``"https://api.example.com"``} | ++------------------------------------------+----------+------------------------------------------------------------------------------+ +| EXA_AUTH_EXTRA_TOKEN_PARAMS | no | Additional parameters to forward to the upstream token endpoint. | +| | | Useful for provider-specific parameters during token exchange. | ++------------------------------------------+----------+------------------------------------------------------------------------------+ + +OpenID with SaaS Backend +------------------------ + +The information in this guide is mostly relevant to the On-Prem backend. The +authentication in SaaS backend is based on OpenID Connect (OIDC), which is an +authentication layer built on top of OAuth. For details please refer to the Exasol +SaaS `Access Management `__ +documentation, and in particular to the `Personal Access Token (PAT) `__ +section. + +Essentially, an Exasol SaaS user is issued a PAT. They need to pass this token to the +MCP Server. This can be done using an HTTP header, as described in the :doc:`db_connection_setup` guide. + +Besides that, the MCP server tools can also be protected using one of the authorization +schemas described earlier in this guide, but in case of SaaS backend this is optional. diff --git a/doc/user_guide/server_setup.md b/doc/user_guide/server_setup.md deleted file mode 100644 index b44f3ce..0000000 --- a/doc/user_guide/server_setup.md +++ /dev/null @@ -1,59 +0,0 @@ -# MCP Server Setup - -Essentially, the sever is configured using environment variables. - -In case of the MCP Sever running locally, under the control of an MCP client application, -the latter usually provides a convenient way of creating an environment from some kind -of configuration file. Below is an example of Claude Desktop configuration file that -references the Exasol MCP Server. - -```json -{ - "mcpServers": { - "exasol_db": { - "command": "uvx", - "args": ["exasol-mcp-server@latest"], - "env": { - "EXA_DSN": "my-dsn, e.g. demodb.exasol.com:8563", - "EXA_USER": "my-user-name", - "EXA_PASSWORD": "my-password", - "EXA_MCP_SETTINGS": "{\"schemas\": {\"like_pattern\": \"MY_SCHEMA\"}" - } - } - } -} -``` - -The `env` section of this file lists the environment variables that will be created in -the environment where the MCP Server is going to run. - -The environment variables can be divided into three groups. - -- [OpenID settings](open_id_setup.md). -- [Database connection settings](db_connection_setup.md) -- [Tool settings](tool_setup.md) - -All settings are described in details in respective sections of the User Guide. - -## Tool settings - -The tool settings are stored in a single variable - `EXA_MCP_SETTINGS`. The settings -are written in the json format. The json string can be set directly in the environment -variable, as shown in the above example. Note that double quotes in the json string must -be escaped, otherwise the environment variable value will be interpreted, not as text, -but as a part of the outer json. - -Alternatively, the settings can be written in a json file. In this case, the `EXA_MCP_SETTINGS` -should contain the path to this file, e.g. - -```json -{ - "env": { - "other": "variables", - "EXA_MCP_SETTINGS": "path_to_settings.json" - } -} -``` - -Please see the [Tool Setup](tool_setup.md) for details on how the MCP Server tools -can be customised. diff --git a/doc/user_guide/server_setup.rst b/doc/user_guide/server_setup.rst new file mode 100644 index 0000000..4d9e36e --- /dev/null +++ b/doc/user_guide/server_setup.rst @@ -0,0 +1,61 @@ +MCP Server Setup +================ + +Essentially, the sever is configured using environment variables. + +In case of the MCP Sever running locally, under the control of an MCP client application, +the latter usually provides a convenient way of creating an environment from some kind +of configuration file. Below is an example of Claude Desktop configuration file that +references the Exasol MCP Server. + +.. code-block:: json + + { + "mcpServers": { + "exasol_db": { + "command": "uvx", + "args": ["exasol-mcp-server@latest"], + "env": { + "EXA_DSN": "my-dsn, e.g. demodb.exasol.com:8563", + "EXA_USER": "my-user-name", + "EXA_PASSWORD": "my-password", + "EXA_MCP_SETTINGS": "{\"schemas\": {\"like_pattern\": \"MY_SCHEMA\"}" + } + } + } + } + +The ``env`` section of this file lists the environment variables that will be created in +the environment where the MCP Server is going to run. + +The environment variables can be divided into three groups. + +* :doc:`open_id_setup` +* :doc:`db_connection_setup` +* :doc:`tool_setup` + +All settings are described in details in respective sections of the User Guide. + +Tool settings +------------- + +The tool settings are stored in a single variable - ``EXA_MCP_SETTINGS``. The settings +are written in the json format. The json string can be set directly in the environment +variable, as shown in the above example. Note that double quotes in the json string must +be escaped, otherwise the environment variable value will be interpreted, not as text, +but as a part of the outer json. + +Alternatively, the settings can be written in a json file. In this case, the ``EXA_MCP_SETTINGS`` +should contain the path to this file, e.g. + +.. code-block:: json + + { + "env": { + "other": "variables", + "EXA_MCP_SETTINGS": "path_to_settings.json" + } + } + +Please see the :doc:`tool_setup` for details on how the MCP Server tools +can be customised. diff --git a/doc/user_guide/tool_setup.md b/doc/user_guide/tool_setup.md deleted file mode 100644 index 4f90442..0000000 --- a/doc/user_guide/tool_setup.md +++ /dev/null @@ -1,155 +0,0 @@ -# Tool setup: - -This guide provides detailed information on how to configure Exasol MCP Server tools -to address the requirements of a specific use case. - -## Enable SQL queries - -Most importantly, the server configuration specifies if reading and/or writing the data -using SQL queries is enabled. Note that both options are disabled by default. To enable -the data reading, set the `enable_read_query` property to true, as shown below. - -To enable Data Modification and Data Definition queries set `enable_write_query` property -to true. This option is not recommended since it can cause unintended loss of data. -Before the query is executed the user will be asked to review the query and accept its -execution. This is done through the elicitation mechanism. If the client application -does not support elicitation, the tool will return an error. - -```json -{ - "enable_read_query": true, - "enable_write_query": true -} -``` - -## Set DB object listing filters - -The server configuration settings can also be used to enable/disable or filter the -listing of a particular type of database objects. Similar settings are defined for -the following object types: -``` -schemas, -tables, -views, -functions, -scripts -``` -The settings include the following properties: -- `enable`: a boolean flag that enables or disables the listing. -- `like_pattern`: filters the output by applying the specified SQL LIKE condition to -the object name. -- `regexp_pattern`: filters the output by matching the object name with the specified -regular expression. - -In the following example, the listing of schemas is limited to only one schema, -the listings of functions and scripts are disabled and the visibility of tables is -limited to tables with certain name pattern. - -```json -{ - "schemas": { - "like_pattern": "MY_SCHEMA" - }, - "tables": { - "like_pattern": "MY_TABLE%" - }, - "functions": { - "enable": false - }, - "scripts": { - "enable": false - } -} -``` - -## Set the language - -The language, if specified, can help the tools execute more precise search of requested -database object. This should be the language of communication with the LLM and also the -language used for naming and documenting the database objects. The language must be set -to its english name, e.g. "spanish", not "español". -Below is an example of configuration settings that sets the language to English. - -```json -{ - "language": "english" -} -``` - -## Set the case-sensitive search option - -By default, the database objects are searched in case-insensitive way, i.e. it is assumed -that the names "My_Table" and "MY_TABLE" refer to the same table. If this is undesirable, -the configuration setting `case_sensitive` should be set to true, as in the example below. - -```json -{ - "case_sensitive": true -} -``` - -## Add the server configuration to the MCP Client configuration - -The customised settings can be specified directly in the MCP Client configuration file -using another environment variable - `EXA_MCP_SETTINGS`: -```json -{ - "env": { - "EXA_DSN": "my-dsn", - "EXA_USER": "my-user-name", - "EXA_PASSWORD": "my-password", - "EXA_MCP_SETTINGS": "{\"schemas\": {\"like_pattern\": \"MY_SCHEMA\"}" - } -} -``` -Note that double quotes in the json text must be escaped, otherwise the environment -variable value will be interpreted, not as a text, but as a part of the outer json. - -Alternatively, the settings can be written in a json file. In this case, the -`EXA_MCP_SETTINGS` should contain the path to this file, e.g. -```json -{ - "env": { - "EXA_DSN": "my-dsn", - "EXA_USER": "my-user-name", - "EXA_PASSWORD": "my-password", - "EXA_MCP_SETTINGS": "path_to_settings.json" - } -} -``` - -## Default server settings - -The following json shows the default settings. -```json -{ - "schemas": { - "enable": true, - "like_pattern": "", - "regexp_pattern": "" - }, - "tables": { - "enable": true, - "like_pattern": "", - "regexp_pattern": "" - }, - "views": { - "enable": false, - "like_pattern": "", - "regexp_pattern": "" - }, - "functions": { - "enable": true, - "like_pattern": "", - "regexp_pattern": "" - }, - "scripts": { - "enable": true, - "like_pattern": "", - "regexp_pattern": "" - }, - "enable_read_query": false, - "language": "" -} -``` -The default values do not need to be repeated in the customised settings. diff --git a/doc/user_guide/tool_setup.rst b/doc/user_guide/tool_setup.rst new file mode 100644 index 0000000..f0bd1f1 --- /dev/null +++ b/doc/user_guide/tool_setup.rst @@ -0,0 +1,167 @@ +Tool Setup +========== + +This guide provides detailed information on how to configure Exasol MCP Server tools +to address the requirements of a specific use case. + +Enable SQL queries +------------------ + +Most importantly, the server configuration specifies if reading and/or writing the data +using SQL queries is enabled. Note that both options are disabled by default. To enable +the data reading, set the ``enable_read_query`` property to true, as shown below. + +To enable Data Modification and Data Definition queries set ``enable_write_query`` property +to true. This option is not recommended since it can cause unintended loss of data. +Before the query is executed the user will be asked to review the query and accept its +execution. This is done through the elicitation mechanism. If the client application +does not support elicitation, the tool will return an error. + +.. code-block:: json + + { + "enable_read_query": true, + "enable_write_query": true + } + +Set DB object listing filters +----------------------------- + +The server configuration settings can also be used to enable/disable or filter the +listing of a particular type of database objects. Similar settings are defined for +the following object types: + +* ``schemas`` +* ``tables`` +* ``views`` +* ``functions`` +* ``scripts`` + +The settings include the following properties: + +* ``enable``: a boolean flag that enables or disables the listing. +* ``like_pattern``: filters the output by applying the specified SQL LIKE condition to the object name. +* ``regexp_pattern``: filters the output by matching the object name with the specified regular expression. + +In the following example, the listing of schemas is limited to only one schema, +the listings of functions and scripts are disabled and the visibility of tables is +limited to tables with certain name pattern. + +.. code-block:: json + + { + "schemas": { + "like_pattern": "MY_SCHEMA" + }, + "tables": { + "like_pattern": "MY_TABLE%" + }, + "functions": { + "enable": false + }, + "scripts": { + "enable": false + } + } + +Set the language +---------------- + +The language, if specified, can help the tools execute more precise search of requested +database object. This should be the language of communication with the LLM and also the +language used for naming and documenting the database objects. The language must be set +to its english name, e.g. "spanish", not "español". +Below is an example of configuration settings that sets the language to English. + +.. code-block:: json + + { + "language": "english" + } + +Set the case-sensitive search option +------------------------------------ + +By default, the database objects are searched in case-insensitive way, i.e. it is assumed +that the names "My_Table" and "MY_TABLE" refer to the same table. If this is undesirable, +the configuration setting ``case_sensitive`` should be set to true, as in the example below. + +.. code-block:: json + + { + "case_sensitive": true + } + +Add the server configuration to the MCP Client configuration +------------------------------------------------------------ + +The customised settings can be specified directly in the MCP Client configuration file +using another environment variable - ``EXA_MCP_SETTINGS``: + +.. code-block:: json + + { + "env": { + "EXA_DSN": "my-dsn", + "EXA_USER": "my-user-name", + "EXA_PASSWORD": "my-password", + "EXA_MCP_SETTINGS": "{\"schemas\": {\"like_pattern\": \"MY_SCHEMA\"}" + } + } + +Note that double quotes in the json text must be escaped, otherwise the environment +variable value will be interpreted, not as a text, but as a part of the outer json. + +Alternatively, the settings can be written in a json file. In this case, the +``EXA_MCP_SETTINGS`` should contain the path to this file, e.g. + +.. code-block:: json + + { + "env": { + "EXA_DSN": "my-dsn", + "EXA_USER": "my-user-name", + "EXA_PASSWORD": "my-password", + "EXA_MCP_SETTINGS": "path_to_settings.json" + } + } + +Default server settings +----------------------- + +The following json shows the default settings. + +.. code-block:: json + + { + "schemas": { + "enable": true, + "like_pattern": "", + "regexp_pattern": "" + }, + "tables": { + "enable": true, + "like_pattern": "", + "regexp_pattern": "" + }, + "views": { + "enable": false, + "like_pattern": "", + "regexp_pattern": "" + }, + "functions": { + "enable": true, + "like_pattern": "", + "regexp_pattern": "" + }, + "scripts": { + "enable": true, + "like_pattern": "", + "regexp_pattern": "" + }, + "enable_read_query": false, + "enable_write_query": false, + "language": "" + } + +The default values do not need to be repeated in the customised settings. diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst new file mode 100644 index 0000000..dcab125 --- /dev/null +++ b/doc/user_guide/user_guide.rst @@ -0,0 +1,12 @@ +.. _user_guide: + +:octicon:`person` User Guide +============================ + +.. toctree:: + :maxdepth: 2 + + server_setup + tool_setup + db_connection_setup + open_id_setup diff --git a/pyproject.toml b/pyproject.toml index 71004d3..4c688d5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ description = "Exasol MCP Server" authors = [ {name = "Mikhail Beck", email = "mikhail.beck@exasol.com"}, ] -readme = "README.md" +readme = "README.rst" license = "MIT" keywords = ['exasol', 'MCP server'] dynamic = ["dependencies"] diff --git a/test/integration/conftest.py b/test/integration/conftest.py index 4fee67e..8a719e3 100644 --- a/test/integration/conftest.py +++ b/test/integration/conftest.py @@ -359,6 +359,7 @@ def setup_database( ) pyexasol_connection.execute(query=query) + pyexasol_connection.execute(query="COMMIT") yield finally: