quickshell-mcp 1.4.1__tar.gz

quickshell_mcp-1.4.1/.coderabbit.yaml

@@ -0,0 +1,6 @@
+reviews:
+  finishing_touches:
+    autofix:
+      enabled: false  
+    fix_ci:
+      enabled: false   

quickshell_mcp-1.4.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,122 @@
+name: Bug report
+description: Report something broken
+title: "[Bug] "
+labels: [bug]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Fill in what you can; the more, the faster the fix.
+        If you can reproduce this with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), that isolates whether it's this server or your client config.
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How did you install?
+      options:
+        - pip
+        - uvx
+        - From source
+        - Nix
+        - Docker
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: quickshell-mcp version
+      description: Output of `quickshell-mcp --version` or `pip show quickshell-mcp`
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "e.g. NixOS 24.11, macOS 15, Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: input
+    id: transport
+    attributes:
+      label: Transport
+      description: stdio or http?
+      placeholder: stdio
+    validations:
+      required: true
+
+  - type: dropdown
+    id: source
+    attributes:
+      label: Which source is affected?
+      options:
+        - quickshell.org (types/guide)
+        - doc.qt.io (Qt types)
+        - quickshell-examples
+        - Caelestia/Noctalia implementations
+        - General / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Call tool `quickshell_get_type` with ...
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Error output
+      description: Paste stderr, traceback, or MCP error here. Set `QUICKSHELL_DOCS_MCP_LOG=DEBUG` for more detail.
+      render: text
+
+  - type: dropdown
+    id: cache
+    attributes:
+      label: Did clearing the disk cache change anything?
+      description: Try `refresh=True` on the affected tool, or clear `~/.cache/quickshell-mcp`.
+      options:
+        - Not tried
+        - "Yes, it fixed the issue"
+        - "No, same result after clearing"
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: regression
+    attributes:
+      label: Regression?
+      options:
+        - label: This used to work in a previous version
+          required: false

quickshell_mcp-1.4.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Quickshell documentation
+    url: https://quickshell.org
+    about: Official Quickshell docs, not this project's issue tracker.
+  - name: Quickshell examples
+    url: https://git.outfoxxed.me/quickshell/quickshell-examples
+    about: Official example configs maintained upstream.
+  - name: MCP Inspector
+    url: https://github.com/modelcontextprotocol/inspector
+    about: Debug this server interactively before filing a bug. See the README for steps.

quickshell_mcp-1.4.1/.github/ISSUE_TEMPLATE/config_help.yml

@@ -0,0 +1,70 @@
+name: Setup help
+description: Getting started or configuring the MCP server
+title: "[Help] "
+labels: [question]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, try the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug interactively. It often surfaces the issue faster than trial and error in your client.
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How did you install?
+      options:
+        - pip
+        - uvx
+        - From source
+        - Nix
+        - Docker
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Run `pip show quickshell-mcp` (or check `quickshell_about`) to find this.
+      placeholder: "0.4.1"
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: OS and Python version
+      placeholder: "e.g. NixOS 24.11, Python 3.12"
+    validations:
+      required: true
+
+  - type: textarea
+    id: goal
+    attributes:
+      label: What you're trying to do
+      description: Which client (opencode, Claude Desktop, etc.) and what setup?
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What you tried
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Your config
+      description: Paste your MCP client config (redact paths or tokens if needed).
+      render: json
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Output / errors
+      description: Any error messages or unexpected behavior. Set `QUICKSHELL_DOCS_MCP_LOG=DEBUG` for more detail.
+      render: text

quickshell_mcp-1.4.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,76 @@
+name: Feature request
+description: Suggest something new
+title: "[Feature] "
+labels: [enhancement]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to suggest a feature. Before filing, please [search existing issues](../issues) to see if it's already been requested.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What
+      description: The feature in one sentence.
+      placeholder: Add a tool to search deprecated type warnings across doc versions.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why
+      description: Pain point it solves or use case. Link a related issue if there is one.
+      placeholder: Agents keep suggesting types that were deprecated in v0.3.0 because nothing surfaces that signal today.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - New tool
+        - Existing tool improvement
+        - New upstream source
+        - Search / indexing
+        - Caching
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How it could work
+      description: Rough idea; which tool, which source, new endpoint, etc. Doesn't need to be a full spec.
+      placeholder: |
+        Could live as a flag on `quickshell_get_type` (`include_deprecated=True`), or a
+        standalone `quickshell_list_deprecated` tool. Deprecation notices already exist
+        in the changelog pages, so this might just be a targeted parse of those.
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about and why you didn't go with them. "None" is fine.
+
+  - type: dropdown
+    id: contribute
+    attributes:
+      label: Would you be willing to open a PR for this?
+      options:
+        - "Yes"
+        - "Yes, with some guidance"
+        - "No"
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Screenshots, links, related issues, or anything else that helps explain the request.

quickshell_mcp-1.4.1/.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## What
+
+Brief description of the change.
+
+## Why
+
+Link to issue or explain the problem. Use `Closes #123` if this resolves an open issue.
+
+## How
+
+Key implementation details or approach taken.
+
+## Type of Change
+
+- [ ] `feat` (new feature or tool)
+- [ ] `fix` (bug fix)
+- [ ] `docs` (documentation only)
+- [ ] `refactor` (code change with no behavior change)
+- [ ] `chore` (maintenance, deps, CI)
+
+## Breaking Changes
+
+- [ ] This PR introduces a breaking change (tool signature, config format, or output shape)
+
+If checked, describe the impact and migration path below.
+
+## Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Lint passes (`ruff check . && ruff format --check .`)
+- [ ] Types pass (`mypy quickshell_mcp`)
+- [ ] New tools have happy + failure path tests
+- [ ] Tool docstrings written for how users ask, not what code does
+- [ ] No hardcoded version strings outside `tests/fixtures/`
+- [ ] Docs updated (`README.md`, tool tables) if behavior or interface changed
+
+## Related Issues
+
+Closes #

quickshell_mcp-1.4.1/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.gitignore'
+  pull_request:
+    branches: [ main ]
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.gitignore'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Check flake
+        run: |
+          nix flake check
+          nix flake show --all-systems --json >/dev/null
+
+  build:
+    runs-on: ubuntu-latest
+    needs: check
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Build Nix package
+        run: nix build
+
+      - name: Test package runs
+        run: |
+          timeout 5s ./result/bin/quickshell-mcp || true
+
+      - name: Build Python distribution
+        run: |
+          nix develop --command python -m build --no-isolation
+          ls -la dist/
+
+      - name: Validate package metadata
+        run: nix develop --command twine check dist/*
+
+  lint:
+    runs-on: ubuntu-latest
+    needs: check
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Lint with ruff
+        run: |
+          nix develop --command ruff check quickshell_mcp/ tests/ scripts/
+          nix develop --command ruff format --check quickshell_mcp/ tests/ scripts/
+
+      - name: Type check with mypy
+        run: nix develop --command mypy quickshell_mcp/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: check
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Run tests (offline suite + code-quality gates)
+        run: |
+          nix develop --command pytest tests/ -v -n auto \
+            --cov=quickshell_mcp --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: franklinnolasco7/quickshell-mcp
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  docker-build:
+    runs-on: ubuntu-latest
+    needs: [build, lint, test]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build Docker image
+        run: docker build -t quickshell-mcp .
+
+      - name: Smoke-run image over stdio
+        run: |
+          docker run --rm -i -d --name qs-smoke quickshell-mcp &
+          sleep 3
+          docker stop qs-smoke >/dev/null
+
+  live-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e '.[dev]'
+
+      - name: Live smoke test against quickshell.org
+        run: QUICKSHELL_LIVE_TEST=1 pytest -m live -q

quickshell_mcp-1.4.1/.github/workflows/semantic-release.yml

@@ -0,0 +1,95 @@
+name: Semantic release
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing vX.Y.Z tag to build and publish"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: semantic-release
+
+jobs:
+  semantic-release:
+    runs-on: ubuntu-latest
+    outputs:
+      released: ${{ steps.sr.outputs.released }}
+      version: ${{ steps.sr.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install semantic-release and plugins
+        if: github.event_name == 'push'
+        run: |
+          npm install --no-save \
+            semantic-release@^25 \
+            @semantic-release/git@^11 \
+            @semantic-release/exec@^7 \
+            "@google/semantic-release-replace-plugin@^1.2.7"
+
+      - name: Release
+        id: sr
+        if: github.event_name == 'push'
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: npx semantic-release
+
+  publish:
+    needs: semantic-release
+    runs-on: ubuntu-latest
+    environment: pypi
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      needs.semantic-release.outputs.released == 'true'
+    steps:
+      - name: Resolve version
+        id: meta
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          SR_VERSION: ${{ needs.semantic-release.outputs.version }}
+        run: |
+          TAG="${INPUT_TAG:-$SR_VERSION}"
+          if [ -z "$TAG" ]; then
+            echo "::error::No version resolved. On workflow_dispatch you must pass the tag input (e.g. v1.0.0); push triggers get it from semantic-release."
+            exit 1
+          fi
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v6
+        with:
+          ref: "v${{ steps.meta.outputs.version }}"
+          persist-credentials: false
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Build Python distribution
+        run: |
+          nix develop --command python -m build --no-isolation
+          ls -la dist/
+
+      - name: Validate package metadata
+        run: nix develop --command twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quickshell_mcp-1.4.1/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Nix
+result
+result-*
+.direnv/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store

quickshell_mcp-1.4.1/.releaserc.json

@@ -0,0 +1,35 @@
+{
+  "branches": ["main"],
+  "tagFormat": "v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@google/semantic-release-replace-plugin",
+      {
+        "replacements": [
+          {
+            "files": ["pyproject.toml"],
+            "from": "version = \"[0-9]+\\.[0-9]+\\.[0-9]+[^\"]*\"",
+            "to": "version = \"${nextRelease.version}\"",
+            "results": [{ "file": "pyproject.toml", "hasChanged": true }]
+          }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["pyproject.toml"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]"
+      }
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "echo 'released=true' >> \"$GITHUB_OUTPUT\" && echo \"version=${nextRelease.version}\" >> \"$GITHUB_OUTPUT\""
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

quickshell_mcp-1.4.1/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml