quera-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,42 @@
+name: Bug report
+description: A tool failed or returned wrong data
+labels: [bug]
+body:
+  - type: input
+    id: tool
+    attributes:
+      label: Tool
+      description: Which tool, e.g. bl_search
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Arguments and result
+      description: The arguments the agent sent and the error or wrong output. Remove anything personal.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: e.g. what quera.org shows for the same query
+  - type: input
+    id: client
+    attributes:
+      label: MCP client and OS
+      placeholder: Claude Desktop 1.x on Windows 11
+  - type: dropdown
+    id: network
+    attributes:
+      label: Network
+      options:
+        - Direct connection
+        - VPN or proxy
+        - QUERA_MCP_PROXY set
+  - type: input
+    id: version
+    attributes:
+      label: quera-mcp version
+      placeholder: "0.1.0"

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/sepehr071/quera-mcp/discussions
+    about: Ask how to use it or suggest a new tool

quera_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly

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

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

quera_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/quera-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

quera_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/

quera_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr Radmard
+
+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.

quera_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: quera-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Quera (quera.org): Iranian tech jobs, companies, contests, problems and courses.
+Project-URL: Homepage, https://github.com/sepehr071/quera-mcp
+Project-URL: Issues, https://github.com/sepehr071/quera-mcp/issues
+Project-URL: Website, https://mcpfarsi.ir/
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,coding-problems,courses,iran,jobs,magnet,mcp,model-context-protocol,persian,programming-contests,quera,quera-org,tech-jobs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.16.3
+Requires-Dist: httpx-curl-cffi>=0.1.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/quera-mcp -->
+
+# quera-mcp: Quera (کوئرا) jobs, contests, problems and courses MCP server for AI agents
+
+**quera-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Quera (quera.org), the Iranian developer platform.**
+Its 9 tools search tech jobs and companies (Magnet), list programming contests, search and read problems from the public problemset, and browse the College course catalog.
+No API key or Quera account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[![PyPI](https://img.shields.io/pypi/v/quera-mcp?color=2563eb)](https://pypi.org/project/quera-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/quera-mcp)](https://pypi.org/project/quera-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/quera-mcp/blob/main/LICENSE)
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for quera.org: tech job search with filters (keyword, level, remote, city, tech stack, job type, company, sort), full job postings, company search and profiles, running/upcoming/past programming contests, problem search and statements, and the College course catalog with prices.
+- **Install:** `uvx quera-mcp` or `claude mcp add quera -- uvx quera-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none, no API key or account. Optional `QUERA_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot log in, apply to jobs, submit solutions or register for anything, so no confirmation is needed before calling any tool.
+- **Tools:** 14, all prefixed `qr_`. Typical sequences: `qr_jobs` -> `qr_job` -> `qr_company`; `qr_companies` -> `qr_company`; `qr_problem_filters` -> `qr_problems` -> `qr_problem`; `qr_contests` -> `qr_event`; `qr_courses`; `qr_bootcamps`; `qr_blog`; `qr_salaries`.
+- **Use when:** the user asks about developer jobs in Iran (Tehran, remote, junior, Python...), which companies hire, programming contests, practice problems, or Quera course options and prices.
+- **Do not use when:** the user wants other job boards, personal Quera data (profiles, submissions, rankings) or to apply or submit anything.
+- **Output:** compact JSON. Salaries are Toman per month when the employer published them; contest times are UTC. Text is Persian or English as the author wrote it.
+
+## What it can do
+
+- **Search jobs** on Quera Magnet with the site's own filters: keyword, seniority (intern to lead), remote, city, tech stack, full/part-time/project, company, industry, sorting by newest, trending or salary
+- **Read a job** in full: description, requirements, benefits, skills, salary, deadline and related jobs
+- **Search companies** (3,000+) by name, city, size, industry and tech stack, and read a profile with its open jobs
+- **List contests**: what is running or upcoming, the latest finished ones, and an archive per topic and organizer
+- **Search problems** among about 2,000 public problems by name, topic, difficulty and source, and read the statement
+- **Browse College courses** by learning path, level and keyword, with list prices
+
+Example prompts:
+
+- "Remote junior Python jobs on Quera, newest first."
+- "Which companies in Isfahan are hiring backend developers?"
+- "Show the open jobs and tech stack of Kaya."
+- "Is there a Quera contest coming up? Which ones did Digikala organize?"
+- "Easy practice problems about data structures."
+- "Which Quera course teaches Django and how much is it?"
+- <span dir="rtl">آگهی‌های استخدام دورکاری برنامه‌نویس پایتون در کوئرا را نشان بده.</span>
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
+
+```bash
+claude mcp add quera -- uvx quera-mcp
+```
+
+Claude Desktop, Cursor and other clients:
+
+```json
+{
+  "mcpServers": {
+    "quera": { "command": "uvx", "args": ["quera-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `qr_jobs` | Search open tech jobs (15 per page) with filters |
+| `qr_job` | One posting in full |
+| `qr_job_filters` | Cities, industries, company sizes and popular tech codes the filters accept |
+| `qr_companies` | Search company profiles |
+| `qr_company` | A company profile and its open jobs |
+| `qr_contests` | Running, upcoming and finished contests, or the archive of one topic |
+| `qr_problems` | Search the public problemset |
+| `qr_problem` | One problem statement with stats |
+| `qr_courses` | College course catalog with prices |
+| `qr_salaries` | Published salaries in open jobs, summarized by seniority level |
+| `qr_problem_filters` | Topic slugs and contest ids `qr_problems` accepts |
+| `qr_event` | An event page (CodeCup, hackathon): schedule, prizes, sub-events |
+| `qr_bootcamps` | Bootcamps open for registration with price and seats, or one in full (syllabus, instructors) |
+| `qr_blog` | Search or read the Quera blog |
+
+## FAQ
+
+**Does it need a Quera account?** No. It reads the same public pages anyone sees.
+
+**Is it official?** No. It is an independent project and is not affiliated with Quera.
+
+**Where does it work?** Quera answers both inside and outside Iran. Set `QUERA_MCP_PROXY` if your network blocks it.
+
+**Why are there so few jobs?** Quera Magnet is a small curated board (tens of open postings); the site's own filters decide what is listed.
+
+## فارسی
+
+`quera-mcp` یک سرور MCP غیررسمی و فقط‌خواندنی برای کوئرا (quera.org) است: جستجوی آگهی‌های استخدام و شرکت‌ها، مسابقات برنامه‌نویسی، مسئله‌های بانک سؤال و دوره‌های کالج کوئرا. نیازی به حساب یا کلید API نیست.
+
+نصب: `claude mcp add quera -- uvx quera-mcp`
+
+## License
+
+MIT. Author: Sepehr Radmard (سپهر رادمرد), [github.com/sepehr071](https://github.com/sepehr071), [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard).

quera_mcp-0.1.0/README.md

@@ -0,0 +1,102 @@
+<!-- mcp-name: io.github.sepehr071/quera-mcp -->
+
+# quera-mcp: Quera (کوئرا) jobs, contests, problems and courses MCP server for AI agents
+
+**quera-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Quera (quera.org), the Iranian developer platform.**
+Its 9 tools search tech jobs and companies (Magnet), list programming contests, search and read problems from the public problemset, and browse the College course catalog.
+No API key or Quera account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[![PyPI](https://img.shields.io/pypi/v/quera-mcp?color=2563eb)](https://pypi.org/project/quera-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/quera-mcp)](https://pypi.org/project/quera-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/quera-mcp/blob/main/LICENSE)
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for quera.org: tech job search with filters (keyword, level, remote, city, tech stack, job type, company, sort), full job postings, company search and profiles, running/upcoming/past programming contests, problem search and statements, and the College course catalog with prices.
+- **Install:** `uvx quera-mcp` or `claude mcp add quera -- uvx quera-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none, no API key or account. Optional `QUERA_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot log in, apply to jobs, submit solutions or register for anything, so no confirmation is needed before calling any tool.
+- **Tools:** 14, all prefixed `qr_`. Typical sequences: `qr_jobs` -> `qr_job` -> `qr_company`; `qr_companies` -> `qr_company`; `qr_problem_filters` -> `qr_problems` -> `qr_problem`; `qr_contests` -> `qr_event`; `qr_courses`; `qr_bootcamps`; `qr_blog`; `qr_salaries`.
+- **Use when:** the user asks about developer jobs in Iran (Tehran, remote, junior, Python...), which companies hire, programming contests, practice problems, or Quera course options and prices.
+- **Do not use when:** the user wants other job boards, personal Quera data (profiles, submissions, rankings) or to apply or submit anything.
+- **Output:** compact JSON. Salaries are Toman per month when the employer published them; contest times are UTC. Text is Persian or English as the author wrote it.
+
+## What it can do
+
+- **Search jobs** on Quera Magnet with the site's own filters: keyword, seniority (intern to lead), remote, city, tech stack, full/part-time/project, company, industry, sorting by newest, trending or salary
+- **Read a job** in full: description, requirements, benefits, skills, salary, deadline and related jobs
+- **Search companies** (3,000+) by name, city, size, industry and tech stack, and read a profile with its open jobs
+- **List contests**: what is running or upcoming, the latest finished ones, and an archive per topic and organizer
+- **Search problems** among about 2,000 public problems by name, topic, difficulty and source, and read the statement
+- **Browse College courses** by learning path, level and keyword, with list prices
+
+Example prompts:
+
+- "Remote junior Python jobs on Quera, newest first."
+- "Which companies in Isfahan are hiring backend developers?"
+- "Show the open jobs and tech stack of Kaya."
+- "Is there a Quera contest coming up? Which ones did Digikala organize?"
+- "Easy practice problems about data structures."
+- "Which Quera course teaches Django and how much is it?"
+- <span dir="rtl">آگهی‌های استخدام دورکاری برنامه‌نویس پایتون در کوئرا را نشان بده.</span>
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
+
+```bash
+claude mcp add quera -- uvx quera-mcp
+```
+
+Claude Desktop, Cursor and other clients:
+
+```json
+{
+  "mcpServers": {
+    "quera": { "command": "uvx", "args": ["quera-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `qr_jobs` | Search open tech jobs (15 per page) with filters |
+| `qr_job` | One posting in full |
+| `qr_job_filters` | Cities, industries, company sizes and popular tech codes the filters accept |
+| `qr_companies` | Search company profiles |
+| `qr_company` | A company profile and its open jobs |
+| `qr_contests` | Running, upcoming and finished contests, or the archive of one topic |
+| `qr_problems` | Search the public problemset |
+| `qr_problem` | One problem statement with stats |
+| `qr_courses` | College course catalog with prices |
+| `qr_salaries` | Published salaries in open jobs, summarized by seniority level |
+| `qr_problem_filters` | Topic slugs and contest ids `qr_problems` accepts |
+| `qr_event` | An event page (CodeCup, hackathon): schedule, prizes, sub-events |
+| `qr_bootcamps` | Bootcamps open for registration with price and seats, or one in full (syllabus, instructors) |
+| `qr_blog` | Search or read the Quera blog |
+
+## FAQ
+
+**Does it need a Quera account?** No. It reads the same public pages anyone sees.
+
+**Is it official?** No. It is an independent project and is not affiliated with Quera.
+
+**Where does it work?** Quera answers both inside and outside Iran. Set `QUERA_MCP_PROXY` if your network blocks it.
+
+**Why are there so few jobs?** Quera Magnet is a small curated board (tens of open postings); the site's own filters decide what is listed.
+
+## فارسی
+
+`quera-mcp` یک سرور MCP غیررسمی و فقط‌خواندنی برای کوئرا (quera.org) است: جستجوی آگهی‌های استخدام و شرکت‌ها، مسابقات برنامه‌نویسی، مسئله‌های بانک سؤال و دوره‌های کالج کوئرا. نیازی به حساب یا کلید API نیست.
+
+نصب: `claude mcp add quera -- uvx quera-mcp`
+
+## License
+
+MIT. Author: Sepehr Radmard (سپهر رادمرد), [github.com/sepehr071](https://github.com/sepehr071), [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard).

quera_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "quera-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Quera (quera.org): Iranian tech jobs, companies, contests, problems and courses."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "quera", "quera-org", "iran", "jobs", "tech-jobs", "magnet", "programming-contests", "coding-problems", "courses", "claude", "persian"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=2.2,<3",
+    "httpx>=0.27",
+    "httpx-curl-cffi>=0.1.5",
+    "curl-cffi>=0.16.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/sepehr071/quera-mcp"
+Issues = "https://github.com/sepehr071/quera-mcp/issues"
+Website = "https://mcpfarsi.ir/"
+
+[project.scripts]
+quera-mcp = "quera_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: calls the real Quera site (run with -m live)"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]  # long Field(description=...) strings read better on one line

quera_mcp-0.1.0/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.sepehr071/quera-mcp",
+  "title": "Quera",
+  "description": "Read-only Quera (quera.org): Iranian tech jobs, companies, contests, problems, courses and blog.",
+  "repository": {
+    "url": "https://github.com/sepehr071/quera-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/quera-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "quera-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "QUERA_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for the Quera requests; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

quera_mcp-0.1.0/src/quera_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Quera (quera.org): developer jobs, companies, contests, problems and courses."""
+
+from importlib.metadata import version
+
+__version__ = version("quera-mcp")