quickshell-docs-mcp

为 AI 编码代理提供实时的 Quickshell 文档。

一个 MCP 服务器，让 AI 代理能够实时访问官方 Quickshell 文档，从而不再依赖过时的训练数据猜测 QML API 名称。

同时包含：

• 来自 doc.qt.io 的 Qt 基础类型（Rectangle、RowLayout 等）

• 来自 quickshell-examples 的官方示例配置

• 真实世界的实现，可在 Caelestia 和 Noctalia shell 中搜索

每个结果都带有其来源 URL。当实现与文档不一致时，以文档为准。

目录

• 安装

• 配置

• 工具

• 来源层级

• 参考

• 开发

• 限制

• 许可证

Related MCP server: Context7 MCP

安装

pip install quickshell-docs-mcp        # or: uvx quickshell-docs-mcp

git clone https://github.com/franklinnolasco7/quickshell-docs-mcp
cd quickshell-docs-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

nix run github:franklinnolasco7/quickshell-docs-mcp

docker build -t quickshell-docs-mcp .
docker run --rm -i quickshell-docs-mcp     # speaks MCP over stdio

配置

opencode（opencode.json）：

{
  "mcp": {
    "quickshell-docs": {
      "type": "local",
      "command": ["/absolute/path/to/quickshell-docs-mcp/.venv/bin/quickshell-docs-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop：相同的 JSON 放在 claude_desktop_config.json 中，并包裹在 mcpServers 里。对于 HTTP 传输，设置 QUICKSHELL_DOCS_MCP_TRANSPORT=http（以及可选的 HOST/PORT）。

设置 QUICKSHELL_DOCS_MCP_LOG=DEBUG 可在 stderr 上输出详细的请求日志。 批量文档索引会持久化到磁盘（~/.cache/quickshell-docs-mcp，30 天新鲜度）。可通过 QUICKSHELL_DOCS_MCP_DISK_CACHE 重新定位或禁用，通过 QUICKSHELL_DOCS_MCP_DISK_TTL_HOURS 重新调整。

工具

页面获取工具接受 version="latest"（默认）或显式版本，如 "v0.3.0"。缓存支持的工具接受 refresh=True 以绕过 30 分钟缓存。

来源层级

1. 官方文档（quickshell.org、doc.qt.io），具有权威性

2. 官方示例，其次

3. Caelestia / Noctalia 结果，标记为 real-world implementation 的实用参考

参考

数据来自以下上游来源：

开发

参见 CONTRIBUTING.md 了解设置、工作流程以及如何提交更改。

限制

• 深度类型页面搜索（include_type_pages=True）每台机器会获取一次所有类型页面（冷启动约 15 秒，之后在磁盘上缓存 30 天，跨会话有效；refresh=True 强制重新获取）。普通名称搜索保持即时。

• 示例配置可能针对与您不同的 Quickshell 版本；列表包含 last_modified 日期，以便您判断其时效。

许可证

MIT