Boilerplate: Add software tests and CI configuration

Author: amotl

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/release-pypi.yml

@@ -0,0 +1,61 @@
+# Use Trusted Publishing to stage Python packages through GitHub Actions (GHA) to the Python Package Index (PyPI).
+name: "Release: Python package"
+
+on:
+
+  # Build and publish packages when running a release.
+  push:
+    tags:
+      - '*'
+
+  # Build packages on each pull request for validation purposes.
+  pull_request:
+
+  # Build packages each night for validation purposes.
+  schedule:
+    - cron: '0 4 * * *'
+
+  # Allow the job to be triggered manually.
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: "Build and publish to PyPI"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.13"]
+    env:
+      OS_TYPE: ${{ matrix.os }}
+      PYTHON_VERSION: ${{ matrix.python-version }}
+
+    # Trusted publishing.
+    # Specifying a GitHub environment is optional, but strongly encouraged.
+    environment: pypi
+    # IMPORTANT: This permission is mandatory for Trusted Publishing.
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Acquire sources
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          cache-dependency-glob: |
+            pyproject.toml
+          cache-suffix: ${{ matrix.python-version }}
+          enable-cache: true
+          version: "latest"
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish package to PyPI
+        if: startsWith(github.event.ref, 'refs/tags')
+        run: |
+          uv publish

.github/workflows/tests.yml

@@ -0,0 +1,79 @@
+name: "Tests"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  test:
+    name: "
+    Python ${{ matrix.python-version }}
+    "
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu-latest']
+        python-version: [
+          '3.9',
+          '3.13',
+        ]
+        cratedb-version: [
+          'nightly',
+        ]
+
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: ${{ matrix.python-version }}
+      UV_SYSTEM_PYTHON: true
+
+    services:
+      cratedb:
+        image: crate/crate:${{ matrix.cratedb-version }}
+        ports:
+          - 4200:4200
+          - 5432:5432
+        env:
+          CRATE_HEAP_SIZE: 4g
+
+    steps:
+
+      - name: Acquire sources
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          cache-dependency-glob: |
+            pyproject.toml
+          cache-suffix: ${{ matrix.python-version }}
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up project
+        run: |
+          uv pip install --editable='.[all,develop,test]'
+
+      - name: Run linter and software tests
+        run: poe check
+
+      # https://github.com/codecov/codecov-action
+      - name: Upload coverage results to Codecov
+        uses: codecov/codecov-action@v5
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        with:
+          env_vars: OS,PYTHON
+          fail_ci_if_error: true

CHANGES.md

@@ -0,0 +1,12 @@
+# CrateDB MCP changelog
+
+## Unreleased
+
+## v0.0.1 - 2025-05-xx
+- Project: Established project layout
+- Features: First working version
+- Packaging: Adjusted package dependencies for interoperability
+- Packaging: Added basic CLI entry point and server launcher `cratedb-mcp`
+- Documentation: Show a simple Claude Desktop configuration
+- MCP documentation: Add reference to medium-sized llms.txt context file
+- Boilerplate: Added software tests and CI configuration

README.md

@@ -3,6 +3,8 @@
 [![Bluesky][badge-bluesky]][target-bluesky]
 [![Status][badge-status]][target-project]
 [![License][badge-license]][target-license]
+[![CI][badge-ci]][project-ci]
+[![Coverage][badge-coverage]][project-coverage]
 
 » [Documentation]
 | [Releases]
@@ -99,11 +101,15 @@ omit the `uv run` prefix displayed above.
 [Source code]: https://github.com/crate/cratedb-mcp
 [Releases]: https://github.com/surister/cratedb-mcp/releases
 
+[badge-ci]: https://github.com/crate/cratedb-mcp/actions/workflows/tests.yml/badge.svg
+[badge-coverage]: https://codecov.io/gh/crate/cratedb-mcp/branch/main/graph/badge.svg
 [badge-bluesky]: https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff&label=Follow%20%40CrateDB
 [badge-issues]: https://img.shields.io/github/issues/crate/cratedb-mcp
 [badge-license]: https://img.shields.io/github/license/crate/cratedb-mcp
 [badge-release-notes]: https://img.shields.io/badge/Release%20Notes-v0.0.0-blue
 [badge-status]: https://img.shields.io/badge/status--alpha-orange
+[project-ci]: https://github.com/crate/cratedb-mcp/actions/workflows/tests.yml
+[project-coverage]: https://app.codecov.io/gh/crate/cratedb-mcp
 [target-bluesky]: https://bsky.app/search?q=cratedb
 [target-license]: https://github.com/crate/cratedb-mcp/blob/main/LICENSE
 [target-project]: https://github.com/crate/cratedb-mcp

cratedb_mcp/__main__.py

@@ -1,22 +1,20 @@
-import os
-
 import httpx
-
 from mcp.server.fastmcp import FastMCP
 
-from .constants import Queries, DOCUMENTATION_INDEX
+from .constants import DOCUMENTATION_INDEX, Queries
+from .settings import HTTP_URL
 
 mcp = FastMCP("cratedb-mcp")
 
 
 def query_cratedb(query: str) -> list[dict]:
-    return httpx.post(f'{os.getenv("CRATEDB_MCP_HTTP_URL")}/_sql', json={'stmt': query}).json()
+    return httpx.post(f'{HTTP_URL}/_sql', json={'stmt': query}).json()
 
 
 @mcp.tool(description="Send a SQL query to CrateDB, only 'SELECT' queries are allows, queries that"
                       " modify data, columns or are otherwise deemed un-safe are rejected.")
 def query_sql(query: str):
-    if not 'select' in query.lower():
+    if 'select' not in query.lower():
         raise ValueError('Only queries that have a SELECT statement are allowed.')
     return query_cratedb(query)
 
@@ -29,7 +27,7 @@ def get_cratedb_documentation_index():
                       ' Only used to download CrateDB docs.')
 def fetch_cratedb_docs(link: str):
     """Fetches a CrateDB documentation link from GitHub raw content."""
-    if not 'https://raw.githubusercontent.com/crate/crate/' in link:
+    if 'https://raw.githubusercontent.com/crate/crate/' not in link:
         raise ValueError('Only github cratedb links can be fetched.')
     return httpx.get(link).text
 

cratedb_mcp/cli.py

@@ -11,4 +11,4 @@ def main():
     if transport not in ("stdio", "sse"):
         raise ValueError(f"Unsupported transport: '{transport}'. Please use one of 'stdio', 'sse'.")
     logger.info(f"Starting CrateDB MCP server using transport '{transport}'")
-    mcp.run(transport=transport)
+    mcp.run(transport=transport)  # type: ignore[arg-type]

cratedb_mcp/constants.py

@@ -1,3 +1,5 @@
+# ruff: noqa: E501
+
 class Queries:
     TABLES_METADATA = """
 WITH partitions_health AS (SELECT table_name,

cratedb_mcp/settings.py

@@ -0,0 +1,3 @@
+import os
+
+HTTP_URL = os.getenv("CRATEDB_MCP_HTTP_URL", "http://localhost:4200")