cloud-bicep-mcp-server 0.3.0__tar.gz

cloud_bicep_mcp_server-0.3.0/.env.example

@@ -0,0 +1,33 @@
+# Server Configuration
+# Default binds to loopback for security; set 0.0.0.0 for containers/production behind ingress
+MCP_HOST=127.0.0.1
+MCP_PORT=8080
+MCP_DEBUG=false
+LOG_LEVEL=INFO
+
+# API Key Configuration (REQUIRED for client authentication)
+# Generate a strong, random API key for production
+MCP_API_KEY=your-api-key-here
+
+# GitHub Repository Configuration (owner and repository REQUIRED - no defaults)
+GITHUB_REPO_OWNER=xtratuscloud
+GITHUB_REPO_NAME=cloud_bicep-registry-modules
+# Optional: branch used to build documentation links (defaults to main)
+GITHUB_DEFAULT_BRANCH=main
+
+# GitHub Token Configuration
+# Generate a PAT at: https://github.com/settings/tokens
+# Scope: repo (for private repositories)
+# IMPORTANT: This token must be authorized for SAML SSO if organization has it enabled
+GITHUB_TOKEN=your-github-token-here
+
+# Bicep module registry (REQUIRED - no defaults)
+# OCI registry and repository path where bicep modules are published
+# Used to build the module references (br:<registry>/<name>:<version>)
+BICEP_MODULE_REGISTRY=yourregistry.azurecr.io/bicep/modules
+
+# Cache Configuration
+# Disk cache directory: empty = system temp directory
+MCP_CACHE_DIR=
+# TTL for cache entries in seconds (default 24h)
+MCP_CACHE_TTL_SECONDS=86400

cloud_bicep_mcp_server-0.3.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+
+# Test scripts
+/test_*.py
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+.hypothesis/
+/results.xml
+/coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

cloud_bicep_mcp_server-0.3.0/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-10-15
+
+### Changed
+
+- **Inventory caching for `list_bicep_modules` and `search_bicep_modules`**: the module inventory is now cached, keyed by a fingerprint of the module directory listing (names and tree SHAs)
+  - Any content change inside a module folder (including version bumps) changes its tree SHA and invalidates the cache
+  - Steady-state calls use a single GitHub API request instead of one version request and one metadata request per module
+  - Reduces latency and GitHub rate-limit consumption, and prevents fallback versions ("1.0.0") caused by rate limiting
+- **Required settings** (breaking change): `GITHUB_REPO_OWNER`, `GITHUB_REPO_NAME` and `BICEP_MODULE_REGISTRY` no longer have default values; the server fails to start with a validation error when any of them is not explicitly configured (`GITHUB_DEFAULT_BRANCH` keeps its `main` default)
+- **Renamed `ACR_REGISTRY` to `BICEP_MODULE_REGISTRY`** (breaking change): the setting now contains the full OCI registry and repository path (e.g., `yourregistry.azurecr.io/bicep/modules`) instead of just the registry host
+  - Module references are built as `br:<BICEP_MODULE_REGISTRY>/<name>:<version>`; the `/bicep/modules/` path is no longer hardcoded
+  - Registry-agnostic: supports ACR, ghcr.io, Docker Hub or any OCI-compliant registry, at any repository path depth
+  - The tool output field `acrReference` is now `moduleReference`, and the `## ACR Reference` section in `scrape_bicep_module_details` is now `## Module Reference` (no compatibility alias: this is the first public release)
+- **Removed the Redis cache backend** (breaking change): the disk cache is now the only backend, which persists across sessions in local STDIO deployments without requiring external services
+  - Removed settings: `MCP_CACHE_BACKEND` and `MCP_CACHE_REDIS_URL`
+  - Removed the `RedisCacheBackend` class and its tests
+- **Removed GitHub OIDC authentication** (breaking change): the server now authenticates against GitHub exclusively with the configured `GITHUB_TOKEN`
+  - Removed GitHub App OIDC token exchange, OIDC token validation and the request-scoped OIDC token storage
+  - Removed settings: `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_ID`, `OIDC_ENABLED`, `OIDC_ISSUER`, `OIDC_AUDIENCE`, `OIDC_ALLOWED_REPOSITORIES`
+  - Removed the `pyjwt` and `cryptography` dependencies (only used for OIDC)
+  - `GITHUB_TOKEN` is required when accessing private repositories; authenticated HTTP/SSE requests also enforce its presence (health and icon routes remain public, and public-repository STDIO use can omit it)
+- **Local-first distribution**: `server.json` now declares STDIO packages for GitHub Packages (`ghcr.io`, `runtimeHint: docker`) and PyPI (`runtimeHint: uvx`), surfacing the required environment variables to MCP clients
+- **Docker image moved to GitHub Packages** (breaking change): the CI workflow now publishes the image to `ghcr.io/xtratuscloud/cloud-bicep-mcp-server` instead of the internal ACR registry; the release workflow publishes the package to PyPI
+  - Image tags: pre-releases `<BASE_VERSION>.YYYYMMDD.<RUN_NUMBER>`, official releases `<BASE_VERSION>` and `latest`
+  - Required repository secrets: `GHCR_USERNAME`, `GHCR_TOKEN`, `PYPI_API_TOKEN`
+- **Documentation now focuses on local execution**: client setup sections (VSCode, Devin) document local uvx and Docker STDIO configurations instead of remote HTTP deployments
+- **Package metadata cleanup**: author, repository URLs and icon references no longer point to internal resources; the icon is served from a public URL
+
+## [0.2.1] - 2026-10-13
+
+### Changed
+
+- **Release workflow**: aligned `bicep-mcp-release.yml` with the modules release implementation
+  - Uses the official GitHub CLI (`gh release create`) instead of the third-party `softprops/action-gh-release` action
+  - Release notes now embed the changelog section for the released version under "What's Changed" (previously just a link to the CHANGELOG)
+- **Idempotent releases**: rerunning the release workflow no longer skips the whole job when the tag already exists
+  - Only tag creation is skipped; a missing GitHub Release is still created
+  - Existing releases get their notes regenerated from the changelog (`gh release edit`)
+  - The same idempotency fix was applied to `bicep-modules-release.yml` to keep both release workflows aligned
+- **Deployment metadata**: server version references are now driven by `server.json`/`pyproject.toml`
+  - `server.json` package version kept in sync with the project version
+  - The `/health` endpoint reports the version from `server.json` instead of a hardcoded string
+
+## [0.2.0] - 2026-10-13
+
+### Added
+
+- **Health Check Endpoint**: Added `/health` endpoint for Kubernetes liveness, readiness, and startup probes
+  - Returns server status, version, and timestamp
+  - Returns 200 status when server is healthy
+  - Returns 503 status on errors
+- **Caching System**: Implemented comprehensive caching for module README content to reduce GitHub API calls
+  - Disk-based cache backend (default) with configurable TTL
+  - Redis-based cache backend for distributed deployments
+  - Version-aware caching: cache is invalidated when module version changes
+  - Configurable cache directory and TTL via environment variables
+  - Thread-safe cache operations
+- **Enhanced README Extraction**: Improved pattern matching for module README sections
+  - Support for multiple resource section patterns: "Resources Created", "Deployed Resources", "Resource Types"
+  - Support for multiple usage example patterns: "Usage Examples", "Examples"
+  - Better handling of different README structures
+- **Documentation**: Added comprehensive README format documentation
+  - Documented expected section names and patterns
+  - Listed module compliance status
+  - Provided examples for each section type
+- **ACR Module References**: Bicep module references (`br:<registry>/bicep/modules/<name>:<version>`) are now exposed to MCP clients
+  - New `acrReference` field in `list_bicep_modules` output
+  - New `## ACR Reference` section in `scrape_bicep_module_details` output
+  - New `ACR_REGISTRY` setting (default: `yourregistry.azurecr.io`), documented in `.env.example` and README
+- **Module Search**: New `search_bicep_modules` tool with a required search term
+  - Matches against module name, display name, canonical Azure resource type and description (case-insensitive)
+  - Multi-word terms match when the full term (or its compact/hyphenated variants) is a substring, or when every word is present
+  - Complements `list_bicep_modules` (full inventory) with a dedicated filtering tool
+
+### Changed
+
+- `list_bicep_modules` now returns a lightweight full module inventory (`name`, `displayName`, `acrReference`) to keep responses small; the optional `modulename` filter moved to `search_bicep_modules`, which returns complete module information
+- Removed the `find_bicep_module_prompt` prompt (redundant with the new `search_bicep_modules` tool)
+- Integrated caching into `scrape_bicep_module_details` tool
+  - Checks cache before fetching from GitHub
+  - Updates cache after successful extraction
+  - Logs cache hits and misses for monitoring
+- Updated Dockerfile to include new `cache.py` module
+- Updated package configuration (pyproject.toml) to include cache.py in distribution
+- Enhanced test coverage with comprehensive cache tests
+  - Disk cache backend tests (TTL, expiration, thread safety)
+  - Redis cache backend tests (connection, operations)
+  - Integration tests for cache functions
+- **Refactored code organization for better separation of concerns**:
+  - Created `github.py` for all GitHub API interactions
+    - Functions: `get_github_headers`, `get_github_token_from_oidc`, `get_cached_github_token`,
+      `validate_github_oidc_token`, `get_allowed_repositories`, `get_module_version_from_github`,
+      `get_effective_github_token`, `set_oidc_github_token`
+  - Created `auth.py` for authentication middleware
+    - Contains `APIKeyAuthMiddleware` class for client authentication
+    - Designed to support additional authentication mechanisms in the future
+  - Renamed `test_auth.py` to `test_github.py` to reflect the new module structure
+  - Created new `test_auth.py` for authentication middleware tests
+  - `server.py` now focuses solely on MCP server logic and tool definitions
+
+### Fixed
+
+- **Security**: SSE transport now uses ASGI app with API Key middleware (previously bypassed authentication)
+- **Security**: The OIDC-exchanged GitHub token is now stored request-scoped (`contextvars.ContextVar`) and cleared after each request (previously stored in `threading.local` without reset, leaking the token to concurrent or subsequent requests on the same ASGI worker thread)
+- Renamed `list_bicep_modules` field from `versions` to `currentVersion` to accurately reflect that only the current version is returned
+- Updated documentation to clarify that `currentVersion` returns the version from `version.json`, not all historical versions
+- Fixed documentation URL to use `GITHUB_DEFAULT_BRANCH` instead of hardcoded "main"
+- Fixed README path construction in `scrape_bicep_module_details` to handle both direct README.md URLs and directory URLs
+- **README section extraction**: fixed two regex bugs in `scrape_bicep_module_details`
+  - "Usage Examples" as the last section of a README returned only the heading (multiline `$` matched the end of the heading line instead of the end of the document)
+  - Sections containing `###` subsections (e.g. "Type definitions") were truncated at the first subsection because the section terminator was not anchored to the start of a line
+
+### Performance
+
+- Reduced GitHub API calls through intelligent caching
+- Faster response times for repeated module detail requests
+- Configurable cache TTL (default 24 hours) to balance freshness and performance
+
+
+## [0.1.0] - 2026-10-07
+
+### Added
+
+- `list_bicep_modules` tool to search and list Cloud Bicep modules from the private GitHub repository
+- `scrape_bicep_module_details` tool to extract Resource Types, Parameters, Outputs, and Usage Examples from module READMEs
+- Support for multiple transport methods: STDIO (default), HTTP, and SSE
+- API Key authentication for client validation (mandatory for all requests)
+- GitHub authentication support with two methods:
+  - GitHub Personal Access Token (PAT) for initial testing
+  - GitHub Actions OIDC with GitHub App for production deployments (not tested yet)
+- Intelligent module search with fuzzy matching (supports multiple name formats)
+- Module metadata integration (reads metadata.json and version.json files)
+- MCP prompts for finding modules, getting module details, and suggesting modules for Azure services
+- Docker container support for easy deployment
+- Configuration via environment variables with .env file support
+- Comprehensive documentation including Kubernetes deployment guide
+- Debug logging mode for troubleshooting production issues
+- Code linting with ruff for consistent code style
+
+### Changed
+
+- Refactored server to use FastMCP V2 native HTTP and SSE support instead of manual Starlette implementation
+- Reduced code from ~839 lines to ~736 lines (~12% reduction)
+- Simplified STDIO transport using `mcp.run()` directly
+- Simplified HTTP transport using `mcp.http_app(middleware=middleware)`
+- Simplified SSE transport using `mcp.run(transport="sse")`
+- Simplified custom routes using `@mcp.custom_route()` decorator
+- Updated code style to comply with ruff linting rules
+- Improved test mocks to properly simulate HTTP responses with headers
+
+### Features
+
+- Search modules by name with intelligent matching (exact, hyphenated, space-separated, compact formats)
+- Retrieve module versions directly from the repository
+- Extract detailed parameter information and usage examples from module documentation
+- Direct repository access to private GitHub repository with proper authentication
+- Configurable host, port, and debug settings
+- Support for both development (PAT) and production (OIDC) authentication scenarios
+- Ready-to-use Docker images for containerized deployments
+- Complete setup guides for Claude Desktop, VSCode, and Kubernetes
+
+[0.3.0]: https://github.com/xtratuscloud/cloud_bicep-registry-modules/releases/tag/mcp/v0.3.0
+[0.2.0]: https://github.com/xtratuscloud/cloud_bicep-registry-modules/releases/tag/mcp/v0.2.0
+[0.1.0]: https://github.com/xtratuscloud/cloud_bicep-registry-modules/releases/tag/v0.1.0

cloud_bicep_mcp_server-0.3.0/Dockerfile

@@ -0,0 +1,79 @@
+# Build stage
+FROM python:3.13.2-slim AS builder
+
+WORKDIR /app
+
+# Install Poetry
+RUN pip install --no-cache-dir poetry
+
+# Copy Poetry configuration files and README
+COPY pyproject.toml poetry.lock* README.md ./
+
+# Copy application code
+COPY server.py server.json config.py github.py cache.py auth.py ./
+COPY images/cloud-bicep-mcp-96.png ./images/
+
+# Configure Poetry to not create virtualenv and install dependencies
+RUN poetry config virtualenvs.create false \
+  && poetry install --no-interaction --without dev \
+  && poetry check \
+  && rm -rf ~/.cache/pypoetry \
+  && rm -rf ~/.cache/pip
+
+# Runtime stage
+FROM python:3.13.2-slim
+
+WORKDIR /app
+
+# Copy application code from builder
+COPY --from=builder /app /app
+
+# Copy installed dependencies from builder
+COPY --from=builder /usr/local/lib /usr/local/lib
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Clean up pip cache in runtime stage
+RUN pip cache purge \
+  && rm -rf /tmp/* /var/tmp/* ~/.cache/pip
+
+# Set environment variables with defaults that can be overridden
+# the transport can be set to "stdio", "sse" or "http". Defaults to "http".
+# "stdio" uses standard input/output for communication.
+# "sse" is the server-sent events mode and uses HTTP (Server-Sent Events) for communication.
+# "http" enables the Streamable HTTP transport as defined by the MCP specification.
+ENV MCP_TRANSPORT=http
+# The port is used by the "sse" and "http" transport modes and defaults to 8080.
+ENV MCP_PORT=8080
+# The host address to bind to. Defaults to 0.0.0.0 for containerized deployments.
+# WARNING: When using 0.0.0.0, MCP_API_KEY must be set for security.
+ENV MCP_HOST=0.0.0.0
+
+# Create entrypoint script
+RUN echo '#!/bin/bash\n\
+  TRANSPORT_ARG=""\n\
+  PORT_ARG=""\n\
+  HOST_ARG=""\n\
+  \n\
+  # Only add transport parameter if MCP_TRANSPORT is set\n\
+  if [ -n "$MCP_TRANSPORT" ]; then\n\
+  TRANSPORT_ARG="--transport $MCP_TRANSPORT"\n\
+  fi\n\
+  \n\
+  # Only add port parameter if MCP_PORT is set\n\
+  if [ -n "$MCP_PORT" ]; then\n\
+  PORT_ARG="--port $MCP_PORT"\n\
+  fi\n\
+  \n\
+  # Only add host parameter if MCP_HOST is set\n\
+  if [ -n "$MCP_HOST" ]; then\n\
+  HOST_ARG="--host $MCP_HOST"\n\
+  fi\n\
+  \n\
+  python server.py $TRANSPORT_ARG $PORT_ARG $HOST_ARG\n\
+  ' > /app/docker-entrypoint.sh \
+  && chmod +x /app/docker-entrypoint.sh
+
+EXPOSE 8080
+
+# Set the entry point for the container
+ENTRYPOINT ["/app/docker-entrypoint.sh"]