quickshell-docs-mcp

AI 코딩 에이전트를 위한 실시간 Quickshell 문서입니다.

AI 에이전트에게 공식 Quickshell 문서에 대한 실시간 액세스를 제공하는 MCP 서버로, 오래된 학습 데이터에서 QML API 이름을 추측하지 않도록 해줍니다.

또한 포함:

• doc.qt.io의 Qt 기본 타입 (Rectangle, RowLayout, ...)

• quickshell-examples의 공식 예제 구성

• Caelestia 및 Noctalia 셸에서 검색 가능한 실제 구현

모든 결과에는 소스 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: claude_desktop_config.json에 동일한 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