imbi-mcp 0.0.0__tar.gz

imbi_mcp-0.0.0/.github/workflows/docker.yml

@@ -0,0 +1,95 @@
+name: "Build and Publish Docker Image"
+on:
+  release:
+    types: [published]
+
+permissions:
+  attestations: write
+  contents: write
+  id-token: write
+  packages: write
+
+jobs:
+  build-python-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build python package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-distributions
+          path: dist/*
+
+      - name: Attach distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          tag="$RELEASE_TAG"
+          existing=$(gh release view "$tag" --json assets --jq '.assets[].name')
+          for file in dist/*.whl dist/*.tar.gz; do
+            name=$(basename "$file")
+            if echo "$existing" | grep -Fxq "$name"; then
+              echo "Asset exists, skipping: $name"
+            else
+              gh release upload "$tag" "$file"
+            fi
+          done
+
+  build-and-publish-docker:
+    runs-on: ubuntu-latest
+    needs: build-python-package
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Download python distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-distributions
+          path: dist
+
+      - uses: docker/setup-qemu-action@v3
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ghcr.io/${{ github.repository }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true

imbi_mcp-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

imbi_mcp-0.0.0/.github/workflows/test.yml

@@ -0,0 +1,50 @@
+name: "Run Tests"
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    name: "Static Analysis"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Run lint checks
+        run: just lint
+
+  test:
+    name: "Automated Tests"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [ "3.14" ]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - name: Run tests
+        env:
+          UV_FROZEN: "1"
+        run: just test
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: "build/coverage.xml"
+          flags: unittests

imbi_mcp-0.0.0/.gitignore

@@ -0,0 +1,8 @@
+.*
+!/.coderabbit.yaml
+!/.github
+!/.gitignore
+!/.pre-commit-config.yaml
+!/.python-version
+/build
+/dist

imbi_mcp-0.0.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0  # unrelated to the pre-commit utility version
+    hooks:
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-shebang-scripts-are-executable
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.27
+    hooks:
+      - id: tombi-format

imbi_mcp-0.0.0/.python-version

@@ -0,0 +1 @@
+3.14

imbi_mcp-0.0.0/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Instructions for imbi-mcp
+
+## Project Overview
+
+imbi-mcp is an MCP (Model Context Protocol) server that auto-generates tools
+and resources from the imbi-api OpenAPI specification. It acts as a bridge
+between AI agents and the Imbi DevOps service management platform.
+
+## Architecture
+
+```
+AI Agent ──MCP──► imbi-mcp ──HTTP──► imbi-api ──► Neo4j / ClickHouse
+```
+
+- `src/imbi_mcp/server.py` -- Core server logic. Fetches the OpenAPI spec
+  from imbi-api at startup and generates MCP tools/resources via FastMCP.
+  Route maps control which endpoints are exposed and how they are classified.
+- `src/imbi_mcp/app.py` -- Typer CLI entry point. The `serve` command
+  creates the server and starts it on the configured transport.
+- `src/imbi_mcp/__init__.py` -- Package version from installed metadata.
+
+## Key Design Decisions
+
+- The server requires a running imbi-api instance at startup to fetch the
+  OpenAPI spec. If the API is unreachable, startup fails with a clear error.
+- Auth is forwarded transparently: the MCP caller's `Authorization` header
+  is injected into every request to imbi-api via an httpx event hook.
+- Route maps are evaluated in order (first match wins). Exclusions come
+  before semantic mappings.
+
+## Code Standards
+
+- **Line length**: 79 characters
+- **Quotes**: Single quotes for strings, double quotes for docstrings
+- **Type checking**: basedpyright strict mode + mypy strict mode
+- **Testing**: unittest, 90% minimum coverage
+- **Imports**: Prefer module imports (`from unittest import mock`)
+  over object imports (`from unittest.mock import patch`)
+- **Logging**: Use `%s` formatting, not f-strings
+- **Async**: All I/O in production code must be async
+
+## Development Commands
+
+```bash
+just setup       # Install dependencies and pre-commit hooks
+just test        # Run pytest with coverage
+just lint        # Run pre-commit, basedpyright, mypy
+just format      # Auto-format with ruff and tombi
+```
+
+## Testing
+
+Tests use `unittest.TestCase` and `unittest.IsolatedAsyncioTestCase`.
+All external I/O (httpx calls, FastMCP context) is mocked.
+
+```bash
+uv run pytest                    # Run all tests
+uv run pytest tests/test_server.py  # Run specific test file
+```
+
+## CI/CD
+
+GitHub Actions runs on Python 3.12, 3.13, and 3.14:
+- **Static Analysis**: pre-commit hooks + basedpyright
+- **Automated Tests**: pytest with coverage reporting
+
+## Dependencies
+
+- **fastmcp** -- MCP server framework with OpenAPI auto-generation
+- **httpx** -- Async HTTP client for API communication
+- **imbi-common** -- Shared models and utilities (installed from git)
+- **typer** -- CLI framework (via fastmcp dependency)
+
+Manage dependencies with `uv`. After changing `pyproject.toml`, run
+`uv lock` to update the lock file.

imbi_mcp-0.0.0/Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.14-slim AS builder
+
+WORKDIR /tmp/install
+
+RUN pip install uv \
+ && apt update \
+ && apt install git --yes
+
+COPY dist/*.whl pyproject.toml uv.lock /tmp/install/
+
+RUN uv venv /app \
+ && . /app/bin/activate \
+ && uv sync --no-dev --active --frozen --no-install-project \
+ && uv pip install *.whl
+
+FROM python:3.14-slim AS service
+EXPOSE 8001
+ENV PATH="/app/bin:$PATH"
+WORKDIR /app
+COPY --from=builder /app/ /app/
+RUN useradd -r -g users imbi \
+ && chown -R imbi /app
+USER imbi
+CMD ["/app/bin/imbi-mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0"]

imbi_mcp-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Gavin M. Roy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imbi_mcp-0.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: imbi-mcp
+Version: 0.0.0
+Summary: Imbi MCP server
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: imbi-common
+Requires-Dist: pydantic~=2.12
+Description-Content-Type: text/markdown
+
+# imbi-mcp
+
+MCP server for the [Imbi](https://github.com/AWeber-Imbi/imbi) DevOps service
+management platform. Exposes Imbi API functionality to AI agents via the
+[Model Context Protocol](https://modelcontextprotocol.io/).
+
+## How It Works
+
+At startup the server fetches the OpenAPI spec from a running
+[imbi-api](https://github.com/AWeber-Imbi/imbi-api) instance and
+auto-generates MCP tools, resources, and resource templates using
+[FastMCP](https://github.com/jlowin/fastmcp).
+
+Route mapping rules control what gets exposed:
+
+- **Excluded** -- Auth, MFA, status, and thumbnail endpoints are hidden.
+- **Resources** -- `GET` endpoints that return collections.
+- **Resource templates** -- `GET` endpoints with path parameters.
+- **Tools** -- Everything else (create, update, delete operations).
+
+The caller's `Authorization` header is forwarded to the API so that
+requests run with the caller's permissions.
+
+## Requirements
+
+- Python 3.12+
+- A running imbi-api instance
+
+## Quick Start
+
+```bash
+# Install dependencies
+just setup
+
+# Run the server (imbi-api must be reachable)
+just serve
+
+# Or with explicit options
+imbi-mcp serve --api-url http://localhost:8000 --transport streamable-http
+```
+
+## CLI Options
+
+```
+imbi-mcp serve [OPTIONS]
+```
+
+| Option          | Default                  | Env Var        | Description              |
+| --------------- | ------------------------ | -------------- | ------------------------ |
+| `--api-url`     | `http://localhost:8000`  | `IMBI_INTERNAL_API_URL` | Base URL of the Imbi API |
+| `--transport`   | `streamable-http`        |                | MCP transport type       |
+| `--host`        | `127.0.0.1`              |                | Host to bind to          |
+| `--port`        | `8001`                   |                | Port to bind to          |
+
+Supported transports: `stdio`, `http`, `sse`, `streamable-http`
+
+## Docker
+
+```bash
+docker build -t imbi-mcp .
+docker run -p 8001:8001 -e IMBI_INTERNAL_API_URL=http://imbi-api:8000 imbi-mcp
+```
+
+## Development
+
+```bash
+just setup       # Install deps and pre-commit hooks
+just test        # Run tests (90% coverage minimum)
+just lint        # Run ruff, basedpyright, mypy
+just format      # Auto-format code
+```
+
+## License
+
+BSD-3-Clause

imbi_mcp-0.0.0/README.md

@@ -0,0 +1,75 @@
+# imbi-mcp
+
+MCP server for the [Imbi](https://github.com/AWeber-Imbi/imbi) DevOps service
+management platform. Exposes Imbi API functionality to AI agents via the
+[Model Context Protocol](https://modelcontextprotocol.io/).
+
+## How It Works
+
+At startup the server fetches the OpenAPI spec from a running
+[imbi-api](https://github.com/AWeber-Imbi/imbi-api) instance and
+auto-generates MCP tools, resources, and resource templates using
+[FastMCP](https://github.com/jlowin/fastmcp).
+
+Route mapping rules control what gets exposed:
+
+- **Excluded** -- Auth, MFA, status, and thumbnail endpoints are hidden.
+- **Resources** -- `GET` endpoints that return collections.
+- **Resource templates** -- `GET` endpoints with path parameters.
+- **Tools** -- Everything else (create, update, delete operations).
+
+The caller's `Authorization` header is forwarded to the API so that
+requests run with the caller's permissions.
+
+## Requirements
+
+- Python 3.12+
+- A running imbi-api instance
+
+## Quick Start
+
+```bash
+# Install dependencies
+just setup
+
+# Run the server (imbi-api must be reachable)
+just serve
+
+# Or with explicit options
+imbi-mcp serve --api-url http://localhost:8000 --transport streamable-http
+```
+
+## CLI Options
+
+```
+imbi-mcp serve [OPTIONS]
+```
+
+| Option          | Default                  | Env Var        | Description              |
+| --------------- | ------------------------ | -------------- | ------------------------ |
+| `--api-url`     | `http://localhost:8000`  | `IMBI_INTERNAL_API_URL` | Base URL of the Imbi API |
+| `--transport`   | `streamable-http`        |                | MCP transport type       |
+| `--host`        | `127.0.0.1`              |                | Host to bind to          |
+| `--port`        | `8001`                   |                | Port to bind to          |
+
+Supported transports: `stdio`, `http`, `sse`, `streamable-http`
+
+## Docker
+
+```bash
+docker build -t imbi-mcp .
+docker run -p 8001:8001 -e IMBI_INTERNAL_API_URL=http://imbi-api:8000 imbi-mcp
+```
+
+## Development
+
+```bash
+just setup       # Install deps and pre-commit hooks
+just test        # Run tests (90% coverage minimum)
+just lint        # Run ruff, basedpyright, mypy
+just format      # Auto-format code
+```
+
+## License
+
+BSD-3-Clause

imbi_mcp-0.0.0/justfile

@@ -0,0 +1,51 @@
+[doc("Bootstrap the environment and run the MCP server")]
+[group("Testing")]
+serve *ARGS: setup
+    -uv run --env-file=.env imbi-mcp serve {{ ARGS }}
+
+[default]
+[private]
+ci: lint test
+
+[doc("Set up your development environment")]
+[group("Environment")]
+setup:
+    uv sync --all-groups --all-extras --frozen
+    uv run pre-commit install --install-hooks --overwrite
+
+[doc("Run tests")]
+[group("Testing")]
+test: setup
+    uv run pytest
+
+[doc("Run linters")]
+[group("Testing")]
+lint: setup
+    uv run pre-commit run --all-files
+    uv run basedpyright
+    uv run mypy
+
+[doc("Reformat code (optionally pass specific files)")]
+[group("Development")]
+format *FILES: setup
+    #!/usr/bin/env sh
+    set -x
+    if [ "{{FILES}}" = '' ]; then
+        args='--all-files'
+    else
+        args='--files {{FILES}}'
+    fi
+    uv run pre-commit run ruff-format $args
+    uv run pre-commit run tombi-format $args
+
+[doc("Remove runtime artifacts")]
+[group("Environment")]
+clean:
+    rm -f .coverage
+    rm -fR build
+
+[confirm]
+[doc("Remove caches, virtual env, and output files")]
+[group("Environment")]
+real-clean: clean
+    rm -fR .venv .*_cache dist

imbi_mcp-0.0.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "imbi-mcp"
+version = "0.0.0"
+description = "Imbi MCP server"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "BSD-3-Clause"
+authors = [{ name = "Gavin M. Roy", email = "gavinr@aweber.com" }]
+dependencies = [
+  "fastmcp>=2.0.0",
+  "httpx>=0.28.1",
+  "imbi-common",
+  "pydantic~=2.12",
+]
+
+[project.scripts]
+imbi-mcp = "imbi_mcp.app:cli"
+
+[dependency-groups]
+dev = [
+  "basedpyright>=1.37.1",
+  "coverage[toml]>=7.13.1",
+  "mypy~=1.19.1",
+  "pre-commit>=4.5.1",
+  "pytest>=9.0.2",
+  "pytest-cov>=7.0.0",
+  "python-dotenv>=1.1.0",
+  "ruff~=0.14.6",
+]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.mypy]
+namespace_packages = true
+show_error_codes = true
+strict = true
+packages = ["imbi_mcp", "tests"]
+
+[tool.pyright]
+deprecateTypingAliases = true
+reportMissingSuperCall = "hint"
+typeCheckingMode = "strict"
+
+[[tool.pyright.executionEnvironments]]
+root = "src"
+reportUnusedFunction = "warning"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportPrivateUsage = "none"
+reportUnusedFunction = "none"
+extraPaths = ["src", "."]
+
+[tool.ruff]
+line-length = 79
+target-version = "py314"
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+  "A",
+  "ANN",
+  "ARG",
+  "ASYNC",
+  "B",
+  "BLE",
+  "C4",
+  "C90",
+  "DTZ",
+  "E",
+  "ERA",
+  "F",
+  "FLY",
+  "FURB",
+  "G",
+  "I",
+  "LOG",
+  "N",
+  "PIE",
+  "PL",
+  "PTH",
+  "Q",
+  "RET",
+  "RSE",
+  "RUF",
+  "S",
+  "SIM",
+  "T10",
+  "T20",
+  "TC",
+  "TRY",
+  "W",
+]
+ignore = [
+  "TRY003",
+  "TRY400",
+]
+flake8-quotes = { inline-quotes = "single" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--cov=src/imbi_mcp",
+  "--cov-report=xml:build/coverage.xml",
+  "--cov-report=term",
+]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true
+
+[tool.uv.sources]
+imbi-common = { git = "https://github.com/AWeber-Imbi/imbi-common", rev = "main" }