printables-mcp 0.1.0__tar.gz

printables_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+
+updates:
+  # Python tooling: update the dev dependency group only.
+  # allow=development limits PRs to non-production deps; the runtime contract
+  # (mcp, httpx2, pydantic, markdownify, anyio) is bumped by hand.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    allow:
+      - dependency-type: "development"
+    groups:
+      python-dev:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+
+  # GitHub Actions pinned in the workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "ci"

printables_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: "Lint"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Check lockfile
+        run: uv lock --check
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github
+      - name: Ruff format
+        run: uv run ruff format --check
+      - name: Ty
+        run: uv run ty check
+
+  test:
+    name: "Test (${{ matrix.python }})"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Pytest
+        run: uv run pytest --cov
+
+  build:
+    name: "Build"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Build
+        run: uv build
+      # The installed wheel must import cleanly and expose all tools
+      - name: Smoke test the wheel
+        run: >-
+          uv run --isolated --no-project --with dist/*.whl
+          python -c "from printables_mcp.server import TOOLS, create_server; create_server(); assert len(TOOLS) == 8"

printables_mcp-0.1.0/.github/workflows/uv-publish.yml

@@ -0,0 +1,53 @@
+name: uv package publish
+on:
+  release:
+    types: ["published"]
+
+jobs:
+  ci:
+    name: "CI"
+    uses: ./.github/workflows/ci.yml
+
+  check-version:
+    name: "Check tag matches project version"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compare release tag with pyproject version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python3 - <<'EOF'
+          import os
+          import sys
+          import tomllib
+
+          with open("pyproject.toml", "rb") as f:
+              version = tomllib.load(f)["project"]["version"]
+
+          tag = os.environ["RELEASE_TAG"].removeprefix("v")
+          if tag != version:
+              sys.exit(f"Release tag {tag!r} does not match project version {version!r}")
+          print(f"Release tag matches project version {version}")
+          EOF
+
+  publish:
+    name: "Build and publish release"
+    runs-on: ubuntu-latest
+    needs: [ci, check-version]
+    environment:
+      name: pypi
+      url: https://pypi.org/project/printables-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

printables_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test artifacts
+.coverage
+.pytest_cache/
+
+# Docs build
+site/
+.cache/

printables_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

printables_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,37 @@
+# printables-mcp
+
+Public PyPI package: an MCP server (stdio) for Printables.com built on the official `mcp` SDK 2.x (`MCPServer`). Console script `printables-mcp` → `printables_mcp.server:main`.
+
+**Keep this file up to date** when the API knowledge or design decisions change.
+
+## Layout
+
+src-layout, `src/printables_mcp/`:
+
+- `client.py`: `PrintablesClient`, an async `httpx2` client with one `execute(query, variables)` method. Maps every failure to `PrintablesError`; retries network errors and 5xx (3 attempts, linear backoff).
+- `queries.py`: the GraphQL documents.
+- `models.py`: pydantic result models (structured tool output), built from raw payloads via `from_api`.
+- `refs.py`: parsing model/author references (IDs, URLs, handles) and building site/media URLs.
+- `markdown.py`: description HTML → Markdown (`markdownify`), site-relative targets made absolute.
+- `server.py`: module-level tool functions (`TOOLS`), `create_server(transport=None)` registering them with read-only annotations, `main()`.
+
+## Printables API facts (verified by hand; introspection and field suggestions are disabled)
+
+- Endpoint `https://api.printables.com/graphql/`; the website itself sits behind Cloudflare (403 for scripts), the API does not. An honest User-Agent is accepted.
+- Validation errors come back as **HTTP 400 with a JSON `errors` body**: read the body before looking at the status. Out-of-range values (e.g. `limit: 101`) give a 400 with a non-JSON body.
+- `searchPrints2(query, printType: print, limit ≤ 100, offset, ordering: SearchChoicesEnum, categoryId: ID, paid: PaidEnum{all,free,paid}, licenses: [ID], publishedDateLimitDays: Int, hasMake: Boolean)` → `{totalCount, items}`; `totalCount` caps at 10000.
+- `print(id)` returns `null` for a missing model. `printDuration` is hours as a decimal string, `weight` grams, `ratingAvg` a decimal string, `price` a decimal string or null, `premium` = club-only.
+- `getDownloadLink(id, printId, fileType: stl|gcode|sla|other|pack, source: model_detail)` → `{ok, errors{field messages}, output{link ttl}}`; paid/club files fail with `cannot_download_premium_file_as_anonymous_user`.
+- `user(id)` accepts a numeric ID or `"@handle"` (case-insensitive) and returns `null` when unknown. `userModels(userId, limit, cursor, ordering)` → `{cursor, items}`; ordering is a string (`[-]date_published`, `likes_count`, `download_count`, `rating_avg`, `makes_count`), cursor is `""` on an empty page.
+
+## Decisions
+
+- Own implementation, not a fork of any existing Printables MCP server.
+- Links only: the server never writes files to disk.
+- Per-file download failures are returned per file; only model-level failures raise `ToolError`.
+
+## Conventions
+
+- ruff `select = ["ALL"]` (preview), ty `all = "error"`, pytest with 100% branch coverage. Suppressions use `# ruff: ignore[rule-name]`.
+- Tests use `httpx2.MockTransport` with recorded responses in `tests/fixtures/` and an in-memory `mcp.Client`; live tests are marked `live` and excluded by default (`just test-live`).
+- Conventional Commits, GPG-signed, no Co-Authored-By trailer.

printables_mcp-0.1.0/Justfile

@@ -0,0 +1,17 @@
+# Show available recipes.
+help:
+    @just --list --unsorted
+
+# Check formatting, lint rules and types.
+lint:
+    uv run ruff format --check
+    uv run ruff check
+    uv run ty check
+
+# Run the test suite with coverage.
+test:
+    uv run pytest --cov
+
+# Run the end-to-end tests against the real Printables API.
+test-live:
+    uv run pytest -m live

printables_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fedor Ratschew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

printables_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: printables-mcp
+Version: 0.1.0
+Summary: MCP server for Printables.com: search 3D models, read model cards, list files and get download links
+Project-URL: Homepage, https://github.com/feodor-ra/printables-mcp
+Project-URL: Repository, https://github.com/feodor-ra/printables-mcp
+Project-URL: Issues, https://github.com/feodor-ra/printables-mcp/issues
+Author-email: Fedor Ratschew <feodor.ra@me.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printing,llm,mcp,model-context-protocol,printables
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.9
+Requires-Dist: httpx2>=2.10
+Requires-Dist: markdownify>=1.2
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.12
+Description-Content-Type: text/markdown
+
+# printables-mcp
+
+**English** · [Русский](README.ru.md)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/printables-mcp)](https://pypi.org/project/printables-mcp/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/printables-mcp)
+![PyPI - Status](https://img.shields.io/pypi/status/printables-mcp)
+[![CI](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml)
+
+**An [MCP](https://modelcontextprotocol.io) server for [Printables.com](https://www.printables.com)**: lets an AI agent search 3D models, read model cards, list files and get direct download links.
+
+It talks to the public Printables GraphQL API directly: no HTML scraping, no browser, no account. All tools are read-only and return structured results (JSON with an output schema), so agents get exact fields instead of prose.
+
+## Installation
+
+```bash
+uv tool install printables-mcp
+```
+
+Then register the `printables-mcp` command with your MCP client. Claude Code:
+
+```bash
+claude mcp add printables -s user -- printables-mcp
+```
+
+Any other client that speaks stdio:
+
+```json
+{
+  "mcpServers": {
+    "printables": { "command": "printables-mcp" }
+  }
+}
+```
+
+Without installing: `uvx printables-mcp`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_models` | Text search with pagination (`limit`, `offset`, total count) and filters: category, price (`free` / `paid`), licenses, published within N days, has user prints. Orderings: best match, popular, latest, rating, makes count. |
+| `get_model` | Full model card: description as Markdown, tags, category path, license, materials, printer, print time, filament weight, images, PDF, remix sources, stats, price. |
+| `list_model_files` | Every file group in one request: model files (STL/3MF/STEP…), G-code with printer, material, layer height, nozzle and print time, SLA files, other files, ZIP packs. |
+| `get_download_links` | Direct download URLs (valid 24 h) for all or selected files, fetched in parallel. Files of paid or club-only models come back with a per-file reason instead of failing the call. |
+| `list_categories` | All categories with their full paths (IDs for the search filter). |
+| `list_licenses` | All licenses (IDs for the search filter). |
+| `get_author` | Author profile by ID, handle or profile URL. |
+| `list_author_models` | An author's models, cursor-paginated, ordered by newest, oldest, likes, downloads, rating or makes. |
+
+Models and authors can be passed as IDs or as printables.com URLs (locale prefixes such as `/de/` are fine).
+
+## Limitations
+
+- Anonymous access only: paid and Printables Club models are visible, but their files cannot be downloaded.
+- The API is undocumented and may change without notice; the end-to-end suite (`just test-live`) checks it against the live service.
+
+## Development
+
+```bash
+uv sync
+just lint       # ruff format/check + ty
+just test       # pytest with 100% branch coverage
+just test-live  # end-to-end tests against the real API
+```
+
+## License
+
+[MIT](LICENSE)

printables_mcp-0.1.0/README.md

@@ -0,0 +1,69 @@
+# printables-mcp
+
+**English** · [Русский](README.ru.md)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/printables-mcp)](https://pypi.org/project/printables-mcp/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/printables-mcp)
+![PyPI - Status](https://img.shields.io/pypi/status/printables-mcp)
+[![CI](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml)
+
+**An [MCP](https://modelcontextprotocol.io) server for [Printables.com](https://www.printables.com)**: lets an AI agent search 3D models, read model cards, list files and get direct download links.
+
+It talks to the public Printables GraphQL API directly: no HTML scraping, no browser, no account. All tools are read-only and return structured results (JSON with an output schema), so agents get exact fields instead of prose.
+
+## Installation
+
+```bash
+uv tool install printables-mcp
+```
+
+Then register the `printables-mcp` command with your MCP client. Claude Code:
+
+```bash
+claude mcp add printables -s user -- printables-mcp
+```
+
+Any other client that speaks stdio:
+
+```json
+{
+  "mcpServers": {
+    "printables": { "command": "printables-mcp" }
+  }
+}
+```
+
+Without installing: `uvx printables-mcp`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_models` | Text search with pagination (`limit`, `offset`, total count) and filters: category, price (`free` / `paid`), licenses, published within N days, has user prints. Orderings: best match, popular, latest, rating, makes count. |
+| `get_model` | Full model card: description as Markdown, tags, category path, license, materials, printer, print time, filament weight, images, PDF, remix sources, stats, price. |
+| `list_model_files` | Every file group in one request: model files (STL/3MF/STEP…), G-code with printer, material, layer height, nozzle and print time, SLA files, other files, ZIP packs. |
+| `get_download_links` | Direct download URLs (valid 24 h) for all or selected files, fetched in parallel. Files of paid or club-only models come back with a per-file reason instead of failing the call. |
+| `list_categories` | All categories with their full paths (IDs for the search filter). |
+| `list_licenses` | All licenses (IDs for the search filter). |
+| `get_author` | Author profile by ID, handle or profile URL. |
+| `list_author_models` | An author's models, cursor-paginated, ordered by newest, oldest, likes, downloads, rating or makes. |
+
+Models and authors can be passed as IDs or as printables.com URLs (locale prefixes such as `/de/` are fine).
+
+## Limitations
+
+- Anonymous access only: paid and Printables Club models are visible, but their files cannot be downloaded.
+- The API is undocumented and may change without notice; the end-to-end suite (`just test-live`) checks it against the live service.
+
+## Development
+
+```bash
+uv sync
+just lint       # ruff format/check + ty
+just test       # pytest with 100% branch coverage
+just test-live  # end-to-end tests against the real API
+```
+
+## License
+
+[MIT](LICENSE)

printables_mcp-0.1.0/README.ru.md

@@ -0,0 +1,69 @@
+# printables-mcp
+
+[English](README.md) · **Русский**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/printables-mcp)](https://pypi.org/project/printables-mcp/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/printables-mcp)
+![PyPI - Status](https://img.shields.io/pypi/status/printables-mcp)
+[![CI](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/feodor-ra/printables-mcp/actions/workflows/ci.yml)
+
+**[MCP](https://modelcontextprotocol.io)-сервер для [Printables.com](https://www.printables.com).** Через него ИИ-агент ищет 3D-модели, читает их карточки, смотрит список файлов и получает прямые ссылки на скачивание.
+
+Сервер обращается напрямую к публичному GraphQL API Printables: без парсинга HTML, без браузера и без аккаунта. Все инструменты только читают данные и возвращают структурированный результат (JSON со схемой вывода), поэтому агент получает точные поля, а не текст.
+
+## Установка
+
+```bash
+uv tool install printables-mcp
+```
+
+Затем подключите команду `printables-mcp` в MCP-клиенте. Claude Code:
+
+```bash
+claude mcp add printables -s user -- printables-mcp
+```
+
+Любой другой клиент с транспортом stdio:
+
+```json
+{
+  "mcpServers": {
+    "printables": { "command": "printables-mcp" }
+  }
+}
+```
+
+Без установки: `uvx printables-mcp`.
+
+## Инструменты
+
+| Инструмент | Что делает |
+|---|---|
+| `search_models` | Поиск по тексту с пагинацией (`limit`, `offset`, общее число результатов) и фильтрами: категория, цена (`free` / `paid`), лицензии, опубликовано за N дней, есть фото печати. Сортировки: по релевантности, популярности, новизне, рейтингу, числу печатей. |
+| `get_model` | Полная карточка модели: описание в Markdown, теги, путь категории, лицензия, материалы, принтер, время печати, вес филамента, фото, PDF, источники ремикса, статистика, цена. |
+| `list_model_files` | Все группы файлов одним запросом: файлы модели (STL/3MF/STEP…), G-code с принтером, материалом, высотой слоя, соплом и временем печати, файлы SLA, прочие файлы, ZIP-архивы. |
+| `get_download_links` | Прямые ссылки на скачивание (живут 24 часа) для всех или выбранных файлов, запрашиваются параллельно. Для файлов платных моделей и моделей Printables Club по каждому файлу приходит причина отказа, остальные ссылки при этом выдаются. |
+| `list_categories` | Все категории с полным путём (ID для фильтра поиска). |
+| `list_licenses` | Все лицензии (ID для фильтра поиска). |
+| `get_author` | Профиль автора по ID, нику или ссылке на профиль. |
+| `list_author_models` | Модели автора постранично (курсор), сортировка: новые, старые, по лайкам, скачиваниям, рейтингу или числу печатей. |
+
+Модели и авторов можно передавать по ID или ссылкой на printables.com (префиксы локали вроде `/de/` поддерживаются).
+
+## Ограничения
+
+- Доступ только анонимный: платные модели и модели Printables Club видны, но их файлы скачать нельзя.
+- API не документирован и может поменяться без предупреждения. Сквозные тесты (`just test-live`) проверяют его на живом сервисе.
+
+## Разработка
+
+```bash
+uv sync
+just lint       # ruff format/check + ty
+just test       # pytest со 100% покрытием веток
+just test-live  # сквозные тесты против реального API
+```
+
+## Лицензия
+
+[MIT](LICENSE)

printables_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "printables-mcp"
+version = "0.1.0"
+description = "MCP server for Printables.com: search 3D models, read model cards, list files and get download links"
+readme = "README.md"
+authors = [
+    { name = "Fedor Ratschew", email = "feodor.ra@me.com" },
+]
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mcp", "model-context-protocol", "printables", "3d-printing", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.9",
+    "httpx2>=2.10",
+    "markdownify>=1.2",
+    "mcp>=2.3,<3",
+    "pydantic>=2.12",
+]
+
+[project.scripts]
+printables-mcp = "printables_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/feodor-ra/printables-mcp"
+Repository = "https://github.com/feodor-ra/printables-mcp"
+Issues = "https://github.com/feodor-ra/printables-mcp/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 120
+preview = true
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "CPY",                    # flake8-copyright: no per-file copyright notices
+    "missing-trailing-comma", # COM812: conflicts with the formatter
+    "relative-imports",       # TID252: relative imports inside the package are welcome
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "assert",                     # S101: pytest is built on assert
+    "implicit-namespace-package", # INP001: the tests directory is not a package
+    "magic-value-comparison",     # PLR2004: comparing to literal counts is normal in tests
+    "import-private-name",        # PLC2701: tests exercise the package's private internals
+]
+
+[tool.ty.rules]
+all = "error"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-config --strict-markers -m 'not live'"
+markers = ["live: hits the real Printables API (run with `-m live`)"]
+
+[tool.coverage.run]
+source = ["printables_mcp"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[dependency-groups]
+dev = [
+    "anyio~=4.15.1",
+    "pytest~=9.2.0",
+    "pytest-cov~=7.1.0",
+    "ruff==0.17.3",
+    "ty==0.0.95",
+]

printables_mcp-0.1.0/src/printables_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for Printables.com."""
+
+from importlib.metadata import version
+
+__version__ = version("printables-mcp")