bazis-mcp 2.4.0__tar.gz

bazis_mcp-2.4.0/.dockerignore

@@ -0,0 +1,3 @@
+.gitlab-ci.yml
+.gitignore
+.dockerignore

bazis_mcp-2.4.0/.github/workflows/build-publish.yml

@@ -0,0 +1,20 @@
+name: Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  # started by the Release workflow on the tag it creates: a tag pushed with the
+  # workflow token does not trigger the push event above
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    if: startsWith(github.ref, 'refs/tags/v')
+    uses: ecofuture-tech/.github/.github/workflows/reusable-build-publish.yml@main
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      TEST_PYPI_TOKEN: ${{ secrets.TEST_PYPI_TOKEN }}

bazis_mcp-2.4.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+# Creates the release tag vX.Y.Z on the current main commit and starts Build and Publish
+# for it. Run it from the Actions tab (or through the GitHub API) on the main branch.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version without the "v" prefix, e.g. 2.3.0 or 2.4.0-rc1'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  actions: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.ref == 'refs/heads/main'
+    env:
+      GH_TOKEN: ${{ github.token }}
+      VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate the version
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)[0-9]+)?$ ]]; then
+            echo "::error::Invalid version '$VERSION', expected e.g. 2.3.0 or 2.4.0-rc1"
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+            echo "::error::Tag v$VERSION already exists"
+            exit 1
+          fi
+          # versionsort.suffix: a pre-release (v2.4.0-rc1) sorts before its release (v2.4.0)
+          LAST_TAG=$(git -c versionsort.suffix=- tag --list 'v*' --sort=-v:refname | head -n 1)
+          echo "Last release: ${LAST_TAG:-none}, new release: v$VERSION"
+          # sort -V orders "~" before anything, as versionsort.suffix does with "-"
+          NEWEST=$(printf '%s\n%s\n' "${LAST_TAG#v}" "$VERSION" | sed 's/-/~/' | sort -V | tail -n 1)
+          if [ -n "$LAST_TAG" ] && [ "$NEWEST" != "${VERSION/-/\~}" ]; then
+            echo "::error::Version $VERSION is not newer than $LAST_TAG"
+            exit 1
+          fi
+
+      - name: Require green tests on this commit
+        run: |
+          CONCLUSION=$(gh run list --workflow tests.yml --commit "$GITHUB_SHA" --status completed \
+            --json conclusion --jq 'map(.conclusion) | first // "none"')
+          echo "Tests on $GITHUB_SHA: $CONCLUSION"
+          if [ "$CONCLUSION" != "success" ]; then
+            echo "::error::The Tests workflow has not succeeded on $GITHUB_SHA ($CONCLUSION)"
+            exit 1
+          fi
+
+      - name: Create the tag
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git tag -a "v$VERSION" -m "${{ github.event.repository.name }} $VERSION" "$GITHUB_SHA"
+          git push origin "v$VERSION"
+
+      - name: Start Build and Publish
+        run: gh workflow run build-publish.yml --ref "v$VERSION"
+
+      - name: Summary
+        run: |
+          echo "Tagged \`v$VERSION\` at \`$GITHUB_SHA\` and started Build and Publish." >> "$GITHUB_STEP_SUMMARY"

bazis_mcp-2.4.0/.github/workflows/tests.yml

@@ -0,0 +1,74 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx ruff check bazis tests sample scripts
+
+  tests:
+    name: tests (python ${{ matrix.python }}, ${{ matrix.resolution }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+        resolution: [highest]
+        include:
+          # the lowest versions allowed by pyproject.toml
+          - python: '3.12'
+            resolution: lowest-direct
+
+    # the server reads the project without connecting to PostgreSQL or Redis: no services
+    env:
+      BS_DEBUG: 'true'
+      BS_SECRET_KEY: ci-only-secret-key-that-is-long-enough-0123456789
+      BS_DATABASES__DEFAULT__HOST: localhost
+      BS_DATABASES__DEFAULT__PORT: '5432'
+      BS_DATABASES__DEFAULT__NAME: bazis
+      BS_DATABASES__DEFAULT__USER: postgres
+      BS_DATABASES__DEFAULT__PASSWORD: postgres
+      BS_CACHES__DEFAULT__LOCATION: redis://localhost:6379/1
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install GDAL (required by the PostGIS database backend)
+        # a stalled Ubuntu mirror must fail the step quickly instead of hanging the job
+        timeout-minutes: 10
+        run: |
+          APT="sudo apt-get -o Acquire::Retries=3 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30"
+          $APT update
+          $APT install -y --no-install-recommends gdal-bin
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          activate-environment: true
+
+      - name: Install dependencies
+        run: uv pip install --resolution ${{ matrix.resolution }} -e '.[test]'
+
+      - name: Check for missing migrations
+        working-directory: sample
+        run: python manage.py makemigrations --check --dry-run
+
+      - name: Run tests
+        working-directory: sample
+        run: python -m pytest ../tests -o addopts="" -p no:cacheprovider

bazis_mcp-2.4.0/.github/workflows/update-licenses.yml

@@ -0,0 +1,18 @@
+name: Update Licenses
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+
+permissions:
+  contents: write
+
+jobs:
+  update-licenses:
+    uses: ecofuture-tech/.github/.github/workflows/reusable-update-licenses.yml@main
+    secrets:
+      WORKFLOW_LICENSE_TOKEN: ${{ secrets.WORKFLOW_LICENSE_TOKEN }}

bazis_mcp-2.4.0/.gitignore

@@ -0,0 +1,44 @@
+.idea
+.ipynb_checkpoints
+.mypy_cache
+.vscode
+__pycache__
+.pytest_cache
+htmlcov
+dist
+site
+.coverage
+coverage.xml
+.netlify
+test.db
+log.txt
+Pipfile.lock
+env3.*
+env
+docs_build
+venv
+.venv
+docs.zip
+archive.zip
+
+.env
+local.env
+*/.env*
+
+# vim temporary files
+*~
+.*.sw?
+*.DS_Store
+
+*.egg-info
+build
+dist
+
+docs/_autosummary
+docs/_build
+*.DS_Store
+*.log
+my-*
+My*
+*/**/_version.py
+/uv.lock

bazis_mcp-2.4.0/CLAUDE.md

@@ -0,0 +1,57 @@
+# bazis-mcp
+
+The MCP server of a Bazis project (`bazis-mcp` command, `MCPServer` of the official `mcp`
+SDK 2.x): the catalog of the Bazis packages and the facts and system checks of the
+project, for AI agents. All tools only read.
+
+- `bazis/contrib/mcp/server.py` — the tools, the resource, the prompts and `main()`;
+- `bazis/contrib/mcp/catalog.py` — the installed packages and the snapshot `catalog.json`;
+- `bazis/contrib/mcp/project.py` — loading the project, `bazis.core.introspect` and the
+  system checks;
+- `scripts/update_catalog.py` — rebuilds `catalog.json` from the wheels on PyPI.
+
+stdout is the protocol channel of the stdio transport: nothing may print to it.
+`main()` sends the output of loading the project to stderr, and the SDK diverts stdout
+while it serves.
+
+The sample project used by the tests is in `sample/`, the tests are in `tests/`.
+
+## Running the tests
+
+The tests need neither PostgreSQL nor Redis (only GDAL for the PostGIS backend).
+Run them from the `sample` directory:
+
+```bash
+cd sample
+BS_DEBUG=true \
+BS_SECRET_KEY=local-secret-key-that-is-long-enough-0123456789 \
+BS_DATABASES__DEFAULT__HOST=localhost BS_DATABASES__DEFAULT__NAME=bazis \
+BS_DATABASES__DEFAULT__USER=postgres BS_DATABASES__DEFAULT__PASSWORD=postgres \
+BS_CACHES__DEFAULT__LOCATION=redis://localhost:6379/1 \
+python -m pytest ../tests -o addopts="" -p no:cacheprovider
+```
+
+Lint: `ruff check bazis tests sample scripts`.
+
+## Releasing
+
+A release is the tag `vX.Y.Z` on `main`: the Build and Publish workflow builds the package
+(the version comes from the tag through setuptools-scm) and publishes it to PyPI
+(pre-releases `-alphaN`/`-betaN`/`-rcN` go to Test PyPI) and creates the GitHub release.
+
+Claude Code sessions cannot push tags. Release through the **Release** workflow instead:
+
+1. Rebuild the catalog with `python scripts/update_catalog.py` after the releases of the
+   other Bazis packages, and commit it.
+2. Make sure the changes are merged into `main` and the Tests workflow is green on the
+   `main` head commit (the Release workflow checks this and refuses otherwise).
+3. Add the release notes as `docs/releases/X.Y.Z.md` in the change being released.
+4. Start the workflow `release.yml` on `ref: main` with the input `version: X.Y.Z`
+   (GitHub API: `POST /repos/ecofuture-tech/bazis-mcp/actions/workflows/release.yml/dispatches`;
+   with the GitHub MCP tools: `actions_run_trigger`, method `run_workflow`).
+5. The Release run creates the annotated tag and starts Build and Publish on it. Check
+   that both runs succeed and that the version appears on https://pypi.org/project/bazis-mcp/.
+
+bazis-mcp is released after the other Bazis packages: its catalog describes their latest
+releases. Pick the version by semver: breaking changes (tools renamed or removed, their
+results changed) bump the minor version while the project is below 3.0.

bazis_mcp-2.4.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: bazis-mcp
+Version: 2.4.0
+Summary: MCP server of Bazis projects: the catalog of the Bazis packages and the facts and checks of the project for AI agents.
+Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
+Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Home, https://github.com/ecofuture-tech/bazis-mcp
+Keywords: bazis,django,fastapi,pydantic,framework,jsonapi,mcp,ai,agents
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: bazis>=2.4.1
+Requires-Dist: mcp>=2.0
+Provides-Extra: test
+Requires-Dist: bazis-test-utils>=2.3.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+
+# bazis-mcp
+
+The [MCP](https://modelcontextprotocol.io) server of a [Bazis](https://github.com/ecofuture-tech/bazis)
+project. It gives AI agents (Claude Code, IDEs with MCP support) what they need to build and
+check a Bazis project from the project itself rather than from memory:
+
+- the catalog of the Bazis packages, also the ones not installed: what each one solves,
+  what it requires, and its guide for agents (`AGENTS.md` and `bazis_manifest.toml`);
+- the facts about the project: installed packages, settings (secrets hidden), models and
+  routes (`bazis.core.introspect`);
+- the system checks of the project and of its Bazis packages (`manage.py bazis_doctor`).
+
+All tools only read. The agent changes the files itself and checks the result with the
+server.
+
+## Installation
+
+Install it as a development dependency of the project:
+
+```bash
+pip install bazis-mcp
+```
+
+Register the server for the MCP client with the directory of `manage.py` (MCP clients
+start servers in their own working directory, usually the repository root):
+
+```bash
+# Claude Code, run in the repository root
+claude mcp add bazis -- .venv/bin/bazis-mcp --project-dir app
+```
+
+or in `.mcp.json` of the repository:
+
+```json
+{
+  "mcpServers": {
+    "bazis": {"command": ".venv/bin/bazis-mcp", "args": ["--project-dir", "app"]}
+  }
+}
+```
+
+(`app` is the directory of `manage.py`; leave `--project-dir` out if it is the root.)
+
+`bazis-mcp [--project-dir DIR] [--settings MODULE]`:
+
+- `--project-dir` — the directory of `manage.py` and `project.env` (default: the current
+  directory);
+- `--settings` — the settings module (default: `DJANGO_SETTINGS_MODULE`, or the module
+  that `manage.py` sets).
+
+The environment of the project (`project.env`, `BS_*` variables) is read as by
+`manage.py`. The server needs neither the database nor Redis. It loads the settings and
+the application of the project, so it runs the project code like `manage.py` does. If the
+project cannot be loaded, the catalog tools still work and the project tools return the
+error.
+
+`bazis-mcp` is not a Django app: do not add it to `BS_INSTALLED_APPS`.
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `list_packages` | Every Bazis package: `summary`, `solves`, `requires`, `pairs_well`, `installed_version`, `catalog_version`, `guide_version` |
+| `package_guide(name)` | The `AGENTS.md` and the manifest of a package (`bazis` for the core) |
+| `project_info(sections)` | `packages`, `settings`, `models`, `routes` of the project |
+| `run_doctor(deploy)` | The messages of the system checks; `ok` is false if there is an error |
+
+Resource: `bazis://packages/{name}/agents.md`. Prompts: `add_package(name)` (add a package
+and make the checks pass) and `audit_project` (review the project against the guides and
+checks of its packages).
+
+An installed package is described by its installed files. The packages that are not
+installed, and those installed in a version without a guide (before 2.4), come from
+`catalog.json`, a snapshot of the latest releases taken at the release of bazis-mcp;
+`guide_version` is the version the guide describes.
+
+The settings are shown with the secrets hidden by `bazis.core.introspect` (by the names
+of the settings and keys, the passwords of URLs and the credentials of `Authorization`
+values). The tool results go to the model of the MCP client: review what the project keeps
+in its settings before connecting it.

bazis_mcp-2.4.0/README.md

@@ -0,0 +1,80 @@
+# bazis-mcp
+
+The [MCP](https://modelcontextprotocol.io) server of a [Bazis](https://github.com/ecofuture-tech/bazis)
+project. It gives AI agents (Claude Code, IDEs with MCP support) what they need to build and
+check a Bazis project from the project itself rather than from memory:
+
+- the catalog of the Bazis packages, also the ones not installed: what each one solves,
+  what it requires, and its guide for agents (`AGENTS.md` and `bazis_manifest.toml`);
+- the facts about the project: installed packages, settings (secrets hidden), models and
+  routes (`bazis.core.introspect`);
+- the system checks of the project and of its Bazis packages (`manage.py bazis_doctor`).
+
+All tools only read. The agent changes the files itself and checks the result with the
+server.
+
+## Installation
+
+Install it as a development dependency of the project:
+
+```bash
+pip install bazis-mcp
+```
+
+Register the server for the MCP client with the directory of `manage.py` (MCP clients
+start servers in their own working directory, usually the repository root):
+
+```bash
+# Claude Code, run in the repository root
+claude mcp add bazis -- .venv/bin/bazis-mcp --project-dir app
+```
+
+or in `.mcp.json` of the repository:
+
+```json
+{
+  "mcpServers": {
+    "bazis": {"command": ".venv/bin/bazis-mcp", "args": ["--project-dir", "app"]}
+  }
+}
+```
+
+(`app` is the directory of `manage.py`; leave `--project-dir` out if it is the root.)
+
+`bazis-mcp [--project-dir DIR] [--settings MODULE]`:
+
+- `--project-dir` — the directory of `manage.py` and `project.env` (default: the current
+  directory);
+- `--settings` — the settings module (default: `DJANGO_SETTINGS_MODULE`, or the module
+  that `manage.py` sets).
+
+The environment of the project (`project.env`, `BS_*` variables) is read as by
+`manage.py`. The server needs neither the database nor Redis. It loads the settings and
+the application of the project, so it runs the project code like `manage.py` does. If the
+project cannot be loaded, the catalog tools still work and the project tools return the
+error.
+
+`bazis-mcp` is not a Django app: do not add it to `BS_INSTALLED_APPS`.
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `list_packages` | Every Bazis package: `summary`, `solves`, `requires`, `pairs_well`, `installed_version`, `catalog_version`, `guide_version` |
+| `package_guide(name)` | The `AGENTS.md` and the manifest of a package (`bazis` for the core) |
+| `project_info(sections)` | `packages`, `settings`, `models`, `routes` of the project |
+| `run_doctor(deploy)` | The messages of the system checks; `ok` is false if there is an error |
+
+Resource: `bazis://packages/{name}/agents.md`. Prompts: `add_package(name)` (add a package
+and make the checks pass) and `audit_project` (review the project against the guides and
+checks of its packages).
+
+An installed package is described by its installed files. The packages that are not
+installed, and those installed in a version without a guide (before 2.4), come from
+`catalog.json`, a snapshot of the latest releases taken at the release of bazis-mcp;
+`guide_version` is the version the guide describes.
+
+The settings are shown with the secrets hidden by `bazis.core.introspect` (by the names
+of the settings and keys, the passwords of URLs and the credentials of `Authorization`
+values). The tool results go to the model of the MCP client: review what the project keeps
+in its settings before connecting it.

bazis_mcp-2.4.0/bazis/contrib/mcp/AGENTS.md

@@ -0,0 +1,44 @@
+# bazis-mcp — guide for AI agents
+
+The MCP server of a Bazis project. It gives an agent the catalog of the Bazis packages
+(also the ones not installed) with their guides, and the facts and system checks of the
+project it runs in. All tools only read; the agent changes the files itself.
+
+## Setup
+
+Install it as a development dependency of the project (`pip install bazis-mcp`) and
+register the command for the MCP client with the directory of `manage.py` (the client
+starts it in its own working directory):
+
+```bash
+claude mcp add bazis -- .venv/bin/bazis-mcp --project-dir <directory of manage.py>
+```
+
+`bazis-mcp [--project-dir DIR] [--settings MODULE]` loads the project in `DIR` (default:
+the current directory) with `project.env` and the settings module of `manage.py` (or
+`DJANGO_SETTINGS_MODULE`). It is not a Django app: do not add it to `BS_INSTALLED_APPS`.
+
+## Tools
+
+- `list_packages` — every Bazis package: `summary`, `solves`, `requires`, `pairs_well`,
+  `installed_version` (null if not installed), `catalog_version` and `guide_version`.
+- `package_guide(name)` — AGENTS.md and manifest of a package (`bazis` for the core).
+  An installed package is described by its installed files, the others (and installed
+  versions without a guide, before 2.4) by the catalog; `guide_version` says which.
+- `project_info(sections)` — `packages`, `settings` (secrets hidden), `models`, `routes`
+  of the project (`bazis.core.introspect`).
+- `run_doctor(deploy)` — the Django system checks with the checks of the Bazis packages
+  (`manage.py bazis_doctor`); `ok` is false if there is an error.
+
+The resource `bazis://packages/{name}/agents.md` is the AGENTS.md of a package; the prompts
+`add_package(name)` and `audit_project` describe these tasks step by step.
+
+## Rules
+
+- Choose packages by `solves` and read `package_guide` before using a package; follow the
+  guide of the installed version (when `guide_version` differs from `installed_version`,
+  upgrade the package or check the guide against its code).
+- Run `run_doctor` and the tests after every change. If the project cannot be loaded, the
+  project tools return the error and the catalog tools still work.
+- The catalog of the packages that are not installed is a snapshot made at the release of
+  bazis-mcp; their latest version may be newer.

bazis_mcp-2.4.0/bazis/contrib/mcp/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+    __version__ = version('bazis-mcp')
+except PackageNotFoundError:
+    __version__ = 'dev'

bazis_mcp-2.4.0/bazis/contrib/mcp/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
+
+__commit_id__ = commit_id = 'g08858be18'

bazis_mcp-2.4.0/bazis/contrib/mcp/bazis_manifest.toml

@@ -0,0 +1,29 @@
+# What the package is for and how to use it, for tools and AI agents (see AGENTS.md).
+# `import` paths and `check` ids are verified by tests/test_manifest.py.
+
+[package]
+name = "bazis-mcp"
+summary = "MCP server of a Bazis project: the catalog of the Bazis packages and the facts and checks of the project for AI agents"
+solves = [
+    "an AI agent chooses the Bazis packages a project needs and reads how to use them",
+    "an AI agent reads the models, routes and settings of the project",
+    "an AI agent checks the project after a change",
+]
+requires = ["bazis"]
+pairs_well = []
+
+[[extension_points]]
+name = "bazis-mcp"
+import = "bazis.contrib.mcp.server.main"
+use_when = "the command that MCP clients run in the project directory"
+
+[[extension_points]]
+name = "server"
+import = "bazis.contrib.mcp.server.server"
+use_when = "the MCPServer instance, to mount it in another server or test it in-process"
+
+[[pitfalls]]
+text = "the server loads the settings and the application of the project: it runs the project code, like manage.py"
+
+[[pitfalls]]
+text = "the guides of packages that are not installed come from a snapshot taken at the release of bazis-mcp"