keycloak-mcp-server 0.1.0__tar.gz

keycloak_mcp_server-0.1.0/.containerignore

@@ -0,0 +1,43 @@
+# Git and version control
+.git/
+.gitignore
+.gitlab-ci.yml
+
+# Python cache and build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+
+# IDE and editor files
+.cursor/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Development and documentation
+LICENSE
+Makefile
+.pre-commit-config.yaml
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+
+# Local environment, credentials, and OAuth state
+.env
+.venv/
+.keycloak-oauth/
+
+# Test files (optional - remove if you want tests in container)
+tests/
+
+# Container files themselves
+Containerfile
+.containerignore

keycloak_mcp_server-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+  "name": "Keycloak MCP Server",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "postCreateCommand": "curl -LsSf https://astral.sh/uv/install.sh | sh && \"$HOME/.local/bin/uv\" sync --locked && \"$HOME/.local/bin/uv\" run --locked pre-commit install && if [ ! -f .env ]; then cp .env.example .env; fi",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": ".venv/bin/python",
+        "python.terminal.activateEnvironment": false,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true
+        }
+      },
+      "extensions": [
+        "charliermarsh.ruff",
+        "ms-python.python",
+        "ms-python.mypy-type-checker",
+        "ms-python.debugpy",
+        "tamasfe.even-better-toml"
+      ]
+    }
+  },
+  "forwardPorts": [
+    5001
+  ],
+  "containerEnv": {
+    "PYTHONPATH": "${containerWorkspaceFolder}"
+  },
+  "remoteEnv": {
+    "PATH": "${containerEnv:HOME}/.local/bin:${containerEnv:PATH}"
+  }
+}

keycloak_mcp_server-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# Copy to .env. Discovery-only mode works without Keycloak credentials.
+MCP_HOST=localhost
+MCP_PORT=5001
+MCP_HOST_ENDPOINT=http://localhost:5001
+# http and streamable-http both use /mcp; sse is the legacy /sse transport.
+MCP_TRANSPORT_PROTOCOL=http
+ENABLE_AUTH=False
+ENVIRONMENT=development
+PYTHON_LOG_LEVEL=INFO
+
+# For browser OAuth, enable ENABLE_AUTH and configure the persistent signing key.
+# Register a public keycloak-mcp client in your realm, with redirect:
+# http://localhost:5001/auth/callback (see docs/authentication.md)
+# Base URL before /realms; legacy WildFly distributions add /auth.
+KEYCLOAK_SERVER_URL=https://keycloak.example.com
+KEYCLOAK_REALM=myrealm
+KEYCLOAK_OAUTH_CLIENT_ID=keycloak-mcp
+# Public client: no Keycloak client secret.
+# Optional only for a confidential upstream client:
+# KEYCLOAK_OAUTH_CLIENT_SECRET=
+# Generate once: uv run python -c 'import secrets; print(secrets.token_urlsafe(48))'
+# KEYCLOAK_OAUTH_SIGNING_KEY=
+# Add an audience mapper for the client's own ID and require it here.
+KEYCLOAK_OAUTH_AUDIENCE=keycloak-mcp
+KEYCLOAK_OAUTH_SCOPES="openid profile email"
+KEYCLOAK_OAUTH_STORAGE_DIR=.keycloak-oauth
+KEYCLOAK_TIMEOUT=30
+# TLS verification stays enabled; use a PEM bundle for internal certificate issuers.
+# KEYCLOAK_CA_BUNDLE=/path/to/trusted-ca-bundle.pem
+# Downstream clients use random loopback callback ports; these defaults allow them.
+# KEYCLOAK_OAUTH_CLIENT_REDIRECT_URIS=["http://localhost:*/*","http://127.0.0.1:*/*"]
+
+# Optional single-user localhost shortcut with ENABLE_AUTH=False only.
+# Must be removed before enabling OAuth. No service-account login is performed.
+# KEYCLOAK_DEV_ACCESS_TOKEN=

keycloak_mcp_server-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,101 @@
+name: Bug Report
+description: Report a bug or unexpected behavior.
+title: "[Bug]: "
+labels: ["type/bug", "status/triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: When I call the multiply tool with...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the behavior.
+      placeholder: |
+        1. Start the server with `make local`
+        2. Send a request to `/mcp` with payload...
+        3. Observe the error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include error messages or logs if available.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Which version of the server are you running?
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport protocol
+      description: Which transport protocol are you using?
+      options:
+        - streamable-http
+        - sse
+        - http
+        - Not applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        Provide details about your environment.
+      placeholder: |
+        - OS: macOS 15.2 / Ubuntu 24.04 / etc.
+        - Python: 3.12.2
+        - Deployment: local / container / OpenShift
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste any relevant log output. This will be formatted as code automatically.
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: I am using a supported Python version (3.12+).
+          required: false

keycloak_mcp_server-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/drtinkerer/keycloak-mcp-server/discussions
+    about: Ask questions, share ideas, or discuss the project.
+  - name: Security Vulnerabilities
+    url: https://github.com/drtinkerer/keycloak-mcp-server/security/advisories/new
+    about: Report security vulnerabilities privately (do NOT use public issues).

keycloak_mcp_server-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,79 @@
+name: Feature Request
+description: Suggest a new feature or improvement.
+title: "[Feature]: "
+labels: ["type/feature", "status/triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe the problem and your proposed solution.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What problem are you trying to solve? What's the use case?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the solution you'd like.
+      placeholder: I would like the server to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative solutions or workarounds you've considered?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of the project does this relate to?
+      options:
+        - MCP Tools
+        - Server Core
+        - OAuth / Authentication
+        - Storage
+        - Deployment / Infrastructure
+        - CI/CD
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How important is this to you?
+      options:
+        - Nice to have
+        - Important - affects my workflow
+        - Critical - blocking my use case
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context, screenshots, or examples.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be willing to submit a PR for this feature.
+          required: false

keycloak_mcp_server-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+## Description
+
+<!-- Briefly describe what this PR does and why. -->
+
+## Related Issues
+
+<!-- Link related issues: Closes #123, Fixes #456 -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] CI/CD or infrastructure change
+- [ ] Dependency update
+
+## Checklist
+
+- [ ] My code follows the project's coding standards (Ruff, MyPy, pydocstyle)
+- [ ] I have added tests that prove my fix is effective or my feature works
+- [ ] All new and existing tests pass (`make test`)
+- [ ] Pre-commit hooks pass (`make pre-commit`)
+- [ ] Code coverage remains >= 80% (`make coverage`)
+- [ ] I have updated documentation where necessary
+- [ ] I have updated `CHANGELOG.md` (if applicable)
+- [ ] My PR title follows [Conventional Commits](https://www.conventionalcommits.org/) format
+
+## Testing
+
+<!-- Describe how you tested your changes. -->
+
+## Screenshots / Logs
+
+<!-- If applicable, add screenshots or log output. -->

keycloak_mcp_server-0.1.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+
+updates:
+  # Python dependencies (pip)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "type/dependency"
+      - "area/python"
+    commit-message:
+      prefix: "build(deps):"
+    reviewers:
+      - "drtinkerer"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "type/dependency"
+      - "area/ci"
+    commit-message:
+      prefix: "ci(deps):"
+    reviewers:
+      - "drtinkerer"

keycloak_mcp_server-0.1.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,35 @@
+name: Pre-commit
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  pre-commit:
+    name: Pre Commit
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install locked dependencies
+      run: uv sync --locked --python ${{ env.PYTHON_VERSION }}
+
+    - name: Run Pre Commit
+      run: |
+        uv run --locked pre-commit run --all-files

keycloak_mcp_server-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,89 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      publish_to_test:
+        description: 'Publish to Test PyPI instead of PyPI'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Check release tag matches package version
+      if: github.event_name == 'release'
+      run: |
+        version=$(uv version --short)
+        if [ "${{ github.event.release.tag_name }}" != "v${version}" ]; then
+          echo "Release tag ${{ github.event.release.tag_name }} does not match pyproject version v${version}"
+          exit 1
+        fi
+
+    - name: Build package
+      run: uv build
+
+    - name: Check package
+      run: uvx twine check dist/*
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Install locked dependencies
+      run: uv sync --locked --python ${{ matrix.python-version }}
+
+    - name: Run tests
+      env:
+        ENABLE_AUTH: "False"
+      run: uv run --locked pytest --cov=keycloak_mcp_server --cov-report=term-missing
+
+  publish:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ github.event.inputs.publish_to_test == 'true' && 'test-pypi' || 'pypi' }}
+      url: ${{ github.event.inputs.publish_to_test == 'true' && 'https://test.pypi.org/p/keycloak-mcp-server' || 'https://pypi.org/p/keycloak-mcp-server' }}
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to Test PyPI
+      if: github.event.inputs.publish_to_test == 'true'
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+
+    - name: Publish to PyPI
+      if: github.event.inputs.publish_to_test != 'true'
+      uses: pypa/gh-action-pypi-publish@release/v1

keycloak_mcp_server-0.1.0/.github/workflows/stale.yml

@@ -0,0 +1,46 @@
+name: Stale Issues and PRs
+
+on:
+  schedule:
+    - cron: "0 9 * * 1"  # Every Monday at 9:00 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    name: Close stale issues and PRs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v11
+        with:
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not
+            had activity in the last 60 days. It will be closed in 14 days if no
+            further activity occurs. If this issue is still relevant, please
+            comment or remove the stale label.
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it
+            has not had activity in the last 30 days. It will be closed in 14
+            days if no further activity occurs. If this PR is still in progress,
+            please comment or push new commits.
+          close-issue-message: >
+            This issue was closed because it has been stale for 14 days with no
+            activity. Feel free to reopen if still relevant.
+          close-pr-message: >
+            This pull request was closed because it has been stale for 14 days
+            with no activity. Feel free to reopen if still relevant.
+          days-before-issue-stale: 60
+          days-before-pr-stale: 30
+          days-before-issue-close: 14
+          days-before-pr-close: 14
+          stale-issue-label: "status/stale"
+          stale-pr-label: "status/stale"
+          exempt-issue-labels: "priority/high,status/blocked,good first issue"
+          exempt-pr-labels: "priority/high,status/blocked"

keycloak_mcp_server-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install locked dependencies
+      run: uv sync --locked --python ${{ matrix.python-version }}
+
+    - name: Run tests with coverage
+      env:
+        ENABLE_AUTH: "False"
+      run: |
+        uv run --locked pytest --cov=keycloak_mcp_server --cov-report=xml --cov-report=term-missing --cov-fail-under=80
+
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

keycloak_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+eggs/
+.eggs/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.keycloak-oauth/
+.venv
+env/
+venv/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# pytype
+.pytype/
+
+# IDE files
+.cursor/
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Project-specific
+bandit-report.json
+safety-report.json
+.safety-project.ini
+build.log
+*.tmp
+*.bak