faradars-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. faradars_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  2. faradars_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  3. faradars_mcp-0.1.0/.gitignore +6 -0
  4. faradars_mcp-0.1.0/LICENSE +21 -0
  5. faradars_mcp-0.1.0/PKG-INFO +177 -0
  6. faradars_mcp-0.1.0/README.md +149 -0
  7. faradars_mcp-0.1.0/pyproject.toml +56 -0
  8. faradars_mcp-0.1.0/server.json +32 -0
  9. faradars_mcp-0.1.0/src/faradars_mcp/__init__.py +5 -0
  10. faradars_mcp-0.1.0/src/faradars_mcp/courses.py +508 -0
  11. faradars_mcp-0.1.0/src/faradars_mcp/http.py +248 -0
  12. faradars_mcp-0.1.0/src/faradars_mcp/learn.py +214 -0
  13. faradars_mcp-0.1.0/src/faradars_mcp/magazine.py +213 -0
  14. faradars_mcp-0.1.0/src/faradars_mcp/registry.py +16 -0
  15. faradars_mcp-0.1.0/src/faradars_mcp/server.py +97 -0
  16. faradars_mcp-0.1.0/tests/conftest.py +78 -0
  17. faradars_mcp-0.1.0/tests/fixtures/blog_categories.json +44 -0
  18. faradars_mcp-0.1.0/tests/fixtures/cards.json +202 -0
  19. faradars_mcp-0.1.0/tests/fixtures/categories.json +1 -0
  20. faradars_mcp-0.1.0/tests/fixtures/comments.json +1 -0
  21. faradars_mcp-0.1.0/tests/fixtures/faq.json +29 -0
  22. faradars_mcp-0.1.0/tests/fixtures/instructor.json +50 -0
  23. faradars_mcp-0.1.0/tests/fixtures/instructors.json +1 -0
  24. faradars_mcp-0.1.0/tests/fixtures/landing.json +13 -0
  25. faradars_mcp-0.1.0/tests/fixtures/landing_products.json +105 -0
  26. faradars_mcp-0.1.0/tests/fixtures/landing_related.json +23 -0
  27. faradars_mcp-0.1.0/tests/fixtures/landings.json +1 -0
  28. faradars_mcp-0.1.0/tests/fixtures/offers.json +31 -0
  29. faradars_mcp-0.1.0/tests/fixtures/plans.json +32 -0
  30. faradars_mcp-0.1.0/tests/fixtures/post.json +111 -0
  31. faradars_mcp-0.1.0/tests/fixtures/posts.json +44 -0
  32. faradars_mcp-0.1.0/tests/fixtures/search.json +216 -0
  33. faradars_mcp-0.1.0/tests/fixtures/show.json +1 -0
  34. faradars_mcp-0.1.0/tests/fixtures/suggest.json +16 -0
  35. faradars_mcp-0.1.0/tests/test_faradars.py +161 -0
  36. faradars_mcp-0.1.0/tests/test_live_faradars.py +98 -0
  37. faradars_mcp-0.1.0/tests/test_round2.py +192 -0
  38. faradars_mcp-0.1.0/uv.lock +1362 -0
faradars_mcp-0.1.0/.github/workflows/ci.yml ADDED
@@ -0,0 +1,22 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python: ["3.10", "3.11", "3.12", "3.13"]
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: astral-sh/setup-uv@v10.2.0
17
+ with:
18
+ python-version: ${{ matrix.python }}
19
+ - run: uv sync --locked
20
+ - run: uv run ruff check .
21
+ - run: uv run ruff format --check .
22
+ - run: uv run pytest -q
faradars_mcp-0.1.0/.github/workflows/publish.yml ADDED
@@ -0,0 +1,51 @@
1
+ name: Publish
2
+
3
+ # Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
4
+ # pyproject.toml and server.json.
5
+ on:
6
+ push:
7
+ tags: ["v*"]
8
+
9
+ jobs:
10
+ pypi:
11
+ runs-on: ubuntu-latest
12
+ environment: pypi
13
+ permissions:
14
+ id-token: write # PyPI trusted publishing
15
+ contents: write # GitHub Release
16
+ steps:
17
+ - uses: actions/checkout@v7
18
+ - uses: astral-sh/setup-uv@v10.2.0
19
+ - name: Check versions match the tag
20
+ run: |
21
+ TAG=${GITHUB_REF_NAME#v}
22
+ grep -q "^version = \"$TAG\"" pyproject.toml
23
+ test "$(jq -r .version server.json)" = "$TAG"
24
+ test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
25
+ - run: uv sync --locked && uv run pytest -q
26
+ - run: uv build
27
+ - uses: pypa/gh-action-pypi-publish@release/v1
28
+ - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
29
+ env:
30
+ GH_TOKEN: ${{ github.token }}
31
+
32
+ mcp-registry:
33
+ needs: pypi
34
+ runs-on: ubuntu-latest
35
+ permissions:
36
+ id-token: write # MCP Registry login via GitHub OIDC
37
+ contents: read
38
+ steps:
39
+ - uses: actions/checkout@v7
40
+ - name: Wait for PyPI to serve the new version
41
+ run: |
42
+ for i in $(seq 1 30); do
43
+ curl -sf "https://pypi.org/pypi/faradars-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
44
+ sleep 10
45
+ done
46
+ exit 1
47
+ - name: Install mcp-publisher
48
+ run: |
49
+ 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
50
+ - run: ./mcp-publisher login github-oidc
51
+ - run: ./mcp-publisher publish
faradars_mcp-0.1.0/.gitignore ADDED
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
faradars_mcp-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sepehr Radmard
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
faradars_mcp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,177 @@
1
+ Metadata-Version: 2.5
2
+ Name: faradars-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for Faradars (faradars.org), the Persian online course platform: course search, prices, syllabus, instructors, magazine.
5
+ Project-URL: Homepage, https://github.com/sepehr071/faradars-mcp
6
+ Project-URL: Issues, https://github.com/sepehr071/faradars-mcp/issues
7
+ Project-URL: Website, https://mcpfarsi.ir/
8
+ Author-email: Sepehr Radmard <sepehrr80@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,courses,e-learning,education,faradars,faradars-org,farsi,instructors,iran,mcp,model-context-protocol,online-courses,persian
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Education
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: curl-cffi>=0.16.3
24
+ Requires-Dist: httpx-curl-cffi>=0.1.5
25
+ Requires-Dist: httpx>=0.27
26
+ Requires-Dist: mcp<3,>=2.2
27
+ Description-Content-Type: text/markdown
28
+
29
+ <!-- mcp-name: io.github.sepehr071/faradars-mcp -->
30
+
31
+ <div align="center">
32
+
33
+ # faradars-mcp: Faradars (فرادرس) course search MCP server for AI agents
34
+
35
+ **faradars-mcp is an unofficial, read-only MCP server that gives AI agents the public course catalog of Faradars (فرادرس), the large Persian online learning platform.**<br>
36
+ Its 16 tools search courses and videos, read prices, discounts and syllabi, compare courses, list student reviews, browse categories and instructors,<br>
37
+ walk learning paths, list offers and coupons, and search and read the Faradars Magazine (مجله فرادرس). No API key or Faradars account is needed.
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/faradars-mcp?color=2563eb)](https://pypi.org/project/faradars-mcp/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/faradars-mcp)](https://pypi.org/project/faradars-mcp/)
41
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/faradars-mcp/blob/main/LICENSE)
42
+
43
+ [For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [فارسی](#فارسی)
44
+
45
+ </div>
46
+
47
+ ---
48
+
49
+ ## For AI agents
50
+
51
+ - **What:** unofficial MCP server (model context protocol) for faradars.org: course and video search with filters, course details (price, current sale, duration, rating, students, instructors, objectives, syllabus), student reviews, category tree, instructor profiles, learning paths, related courses and comparison, discount campaigns and subscription plans, help answers, and Faradars Magazine article search and full text.
52
+ - **Install:** `uvx faradars-mcp` or `claude mcp add faradars -- uvx faradars-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
53
+ - **Auth:** none. Optional `FARADARS_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
54
+ - **Access:** read-only. It cannot log in, buy, enrol or comment, so no confirmation is needed before calling any tool.
55
+ - **Tools:** 16, all prefixed `fr_`. Typical sequences: `fr_search_courses` -> `fr_course` -> `fr_course_reviews`; `fr_course` -> `fr_related_courses` -> `fr_compare_courses`; `fr_instructors` -> `fr_instructor`; `fr_learning_paths` -> `fr_learning_path`; `fr_articles` -> `fr_article`.
56
+ - **Use when:** the user asks which Faradars courses exist on a topic, how much a course costs, whether it has a discount or certificate, what its syllabus is, who teaches it, which courses are free, or wants a tutorial from the Faradars Magazine.
57
+ - **Do not use when:** the user wants to watch lessons, buy, or see their own account (not supported).
58
+ - **Output:** compact JSON. Prices are Toman, durations hours, text is Persian as on the site.
59
+ - **Machine-readable:** [`server.json`](https://github.com/sepehr071/faradars-mcp/blob/main/server.json).
60
+
61
+ ## What it can do
62
+
63
+ - **Search courses and videos** by text, category, free or paid, length, certificate or instructor, sorted by sales, views, relevance or date
64
+ - **Read a course**: price, active sale and its end time, hours, lesson count, rating, student count, objectives, prerequisites, description and the full syllabus
65
+ - **Read student reviews**, 10 at a time
66
+ - **Browse** the category tree, instructors and learning paths (مسیر یادگیری)
67
+ - **Search the magazine** (blog.faradars.org) for tutorials and comparisons
68
+
69
+ Example prompts:
70
+
71
+ - "Find the best-selling Python courses on Faradars and show me the syllabus of the first one."
72
+ - "Which free Excel courses does Faradars have?"
73
+ - "What else does the instructor of this course teach?"
74
+ - <span dir="rtl">بهترین دوره‌های آموزش پایتون در فرادرس کدام‌اند و قیمتشان چند است؟</span>
75
+ - <span dir="rtl">دوره‌های رایگان اکسل با گواهینامه را پیدا کن.</span>
76
+
77
+ ## Quick start
78
+
79
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
80
+
81
+ <details open>
82
+ <summary><b>Claude Code</b></summary>
83
+
84
+ ```bash
85
+ claude mcp add faradars -- uvx faradars-mcp
86
+ ```
87
+ </details>
88
+
89
+ <details>
90
+ <summary><b>Claude Desktop, Cursor, Windsurf, Gemini CLI</b></summary>
91
+
92
+ Add to the client's MCP config:
93
+
94
+ ```json
95
+ {
96
+ "mcpServers": {
97
+ "faradars": { "command": "uvx", "args": ["faradars-mcp"] }
98
+ }
99
+ }
100
+ ```
101
+ </details>
102
+
103
+ <details>
104
+ <summary><b>VS Code (Copilot agent mode)</b></summary>
105
+
106
+ ```json
107
+ {
108
+ "servers": {
109
+ "faradars": { "type": "stdio", "command": "uvx", "args": ["faradars-mcp"] }
110
+ }
111
+ }
112
+ ```
113
+ </details>
114
+
115
+ <details>
116
+ <summary><b>Anything else</b></summary>
117
+
118
+ It is a standard stdio MCP server: run `uvx faradars-mcp`, or `pip install faradars-mcp` and run `faradars-mcp`.
119
+ </details>
120
+
121
+ ## Tools
122
+
123
+ | Tool | What it does |
124
+ |---|---|
125
+ | `fr_search_courses` | Search courses, videos, exams, podcasts and webinars by text, category, price, length, certificate, instructor or trend |
126
+ | `fr_course` | Get one course: price and sale, duration, rating, students, instructors, prerequisites, objectives, syllabus, included extras |
127
+ | `fr_course_reviews` | Get student reviews (stars and comment) of a course, newest first |
128
+ | `fr_related_courses` | Get a course's related courses: same instructor, recommended next steps, similar topics |
129
+ | `fr_compare_courses` | Compare 2-4 courses side by side (price, sale, length, rating, students, certificate) |
130
+ | `fr_categories` | List course categories as a tree of slugs and names |
131
+ | `fr_suggest` | Get the site's search-box suggestions for the start of a phrase |
132
+ | `fr_instructors` | Find instructors by name, or the top instructors of a category |
133
+ | `fr_instructor` | Get an instructor's profile, rating statistics and courses |
134
+ | `fr_learning_paths` | List or search curated learning paths (course collections) |
135
+ | `fr_learning_path` | Get one learning path: its ordered courses, totals and related paths |
136
+ | `fr_offers` | List current discount campaigns, public coupon codes and subscription plans |
137
+ | `fr_faq` | Get Faradars' general help answers (buying, access, certificates, support) |
138
+ | `fr_articles` | Search Faradars Magazine articles by text, category or tag, or list the newest |
139
+ | `fr_article` | Read one Magazine article: key points, outline, text, views and rating |
140
+ | `fr_article_topics` | List Magazine categories or tags with article counts |
141
+
142
+ All 16 tools are annotated `readOnlyHint: true`.
143
+
144
+ ## How it works
145
+
146
+ ```text
147
+ AI agent ──MCP over stdio──▶ faradars-mcp ──HTTPS──▶ faradars.org/api/client courses, categories, instructors
148
+ └──────▶ blog.faradars.org/wp-json magazine
149
+ ```
150
+
151
+ Requests look like Faradars' own web app (Chrome TLS fingerprint and headers), at most two at a time, with a 5 minute
152
+ cache. Set `FARADARS_MCP_PROXY=http://host:port` to route through a proxy.
153
+
154
+ ## Notes
155
+
156
+ - Unofficial. Not affiliated with or endorsed by Faradars. It reads the same public data the website shows to anyone.
157
+ - Course content (videos) is not exposed; only catalog data.
158
+ - Prices change with Faradars sales (`sale_price` is time-limited).
159
+
160
+ ## Development
161
+
162
+ ```bash
163
+ uv sync
164
+ uv run ruff check . && uv run ruff format --check .
165
+ uv run python -m pytest -q # offline
166
+ uv run python -m pytest -m live -q # real faradars.org
167
+ ```
168
+
169
+ ## فارسی
170
+
171
+ **faradars-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای فرادرس است. با آن، دستیار هوش مصنوعی می‌تواند دوره‌ها را جست‌وجو کند، قیمت و تخفیف و سرفصل‌ها را بخواند، نظر دانشجویان را ببیند، مدرس‌ها و مسیرهای یادگیری را پیدا کند و در مجله فرادرس بگردد. نیازی به کلید API یا حساب کاربری نیست.
172
+
173
+ نصب: `claude mcp add faradars -- uvx faradars-mcp`
174
+
175
+ ## License
176
+
177
+ MIT. Built by [Sepehr Radmard](https://github.com/sepehr071) (سپهر رادمرد).
faradars_mcp-0.1.0/README.md ADDED
@@ -0,0 +1,149 @@
1
+ <!-- mcp-name: io.github.sepehr071/faradars-mcp -->
2
+
3
+ <div align="center">
4
+
5
+ # faradars-mcp: Faradars (فرادرس) course search MCP server for AI agents
6
+
7
+ **faradars-mcp is an unofficial, read-only MCP server that gives AI agents the public course catalog of Faradars (فرادرس), the large Persian online learning platform.**<br>
8
+ Its 16 tools search courses and videos, read prices, discounts and syllabi, compare courses, list student reviews, browse categories and instructors,<br>
9
+ walk learning paths, list offers and coupons, and search and read the Faradars Magazine (مجله فرادرس). No API key or Faradars account is needed.
10
+
11
+ [![PyPI](https://img.shields.io/pypi/v/faradars-mcp?color=2563eb)](https://pypi.org/project/faradars-mcp/)
12
+ [![Python](https://img.shields.io/pypi/pyversions/faradars-mcp)](https://pypi.org/project/faradars-mcp/)
13
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/faradars-mcp/blob/main/LICENSE)
14
+
15
+ [For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [فارسی](#فارسی)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ ## For AI agents
22
+
23
+ - **What:** unofficial MCP server (model context protocol) for faradars.org: course and video search with filters, course details (price, current sale, duration, rating, students, instructors, objectives, syllabus), student reviews, category tree, instructor profiles, learning paths, related courses and comparison, discount campaigns and subscription plans, help answers, and Faradars Magazine article search and full text.
24
+ - **Install:** `uvx faradars-mcp` or `claude mcp add faradars -- uvx faradars-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
25
+ - **Auth:** none. Optional `FARADARS_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
26
+ - **Access:** read-only. It cannot log in, buy, enrol or comment, so no confirmation is needed before calling any tool.
27
+ - **Tools:** 16, all prefixed `fr_`. Typical sequences: `fr_search_courses` -> `fr_course` -> `fr_course_reviews`; `fr_course` -> `fr_related_courses` -> `fr_compare_courses`; `fr_instructors` -> `fr_instructor`; `fr_learning_paths` -> `fr_learning_path`; `fr_articles` -> `fr_article`.
28
+ - **Use when:** the user asks which Faradars courses exist on a topic, how much a course costs, whether it has a discount or certificate, what its syllabus is, who teaches it, which courses are free, or wants a tutorial from the Faradars Magazine.
29
+ - **Do not use when:** the user wants to watch lessons, buy, or see their own account (not supported).
30
+ - **Output:** compact JSON. Prices are Toman, durations hours, text is Persian as on the site.
31
+ - **Machine-readable:** [`server.json`](https://github.com/sepehr071/faradars-mcp/blob/main/server.json).
32
+
33
+ ## What it can do
34
+
35
+ - **Search courses and videos** by text, category, free or paid, length, certificate or instructor, sorted by sales, views, relevance or date
36
+ - **Read a course**: price, active sale and its end time, hours, lesson count, rating, student count, objectives, prerequisites, description and the full syllabus
37
+ - **Read student reviews**, 10 at a time
38
+ - **Browse** the category tree, instructors and learning paths (مسیر یادگیری)
39
+ - **Search the magazine** (blog.faradars.org) for tutorials and comparisons
40
+
41
+ Example prompts:
42
+
43
+ - "Find the best-selling Python courses on Faradars and show me the syllabus of the first one."
44
+ - "Which free Excel courses does Faradars have?"
45
+ - "What else does the instructor of this course teach?"
46
+ - <span dir="rtl">بهترین دوره‌های آموزش پایتون در فرادرس کدام‌اند و قیمتشان چند است؟</span>
47
+ - <span dir="rtl">دوره‌های رایگان اکسل با گواهینامه را پیدا کن.</span>
48
+
49
+ ## Quick start
50
+
51
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
52
+
53
+ <details open>
54
+ <summary><b>Claude Code</b></summary>
55
+
56
+ ```bash
57
+ claude mcp add faradars -- uvx faradars-mcp
58
+ ```
59
+ </details>
60
+
61
+ <details>
62
+ <summary><b>Claude Desktop, Cursor, Windsurf, Gemini CLI</b></summary>
63
+
64
+ Add to the client's MCP config:
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "faradars": { "command": "uvx", "args": ["faradars-mcp"] }
70
+ }
71
+ }
72
+ ```
73
+ </details>
74
+
75
+ <details>
76
+ <summary><b>VS Code (Copilot agent mode)</b></summary>
77
+
78
+ ```json
79
+ {
80
+ "servers": {
81
+ "faradars": { "type": "stdio", "command": "uvx", "args": ["faradars-mcp"] }
82
+ }
83
+ }
84
+ ```
85
+ </details>
86
+
87
+ <details>
88
+ <summary><b>Anything else</b></summary>
89
+
90
+ It is a standard stdio MCP server: run `uvx faradars-mcp`, or `pip install faradars-mcp` and run `faradars-mcp`.
91
+ </details>
92
+
93
+ ## Tools
94
+
95
+ | Tool | What it does |
96
+ |---|---|
97
+ | `fr_search_courses` | Search courses, videos, exams, podcasts and webinars by text, category, price, length, certificate, instructor or trend |
98
+ | `fr_course` | Get one course: price and sale, duration, rating, students, instructors, prerequisites, objectives, syllabus, included extras |
99
+ | `fr_course_reviews` | Get student reviews (stars and comment) of a course, newest first |
100
+ | `fr_related_courses` | Get a course's related courses: same instructor, recommended next steps, similar topics |
101
+ | `fr_compare_courses` | Compare 2-4 courses side by side (price, sale, length, rating, students, certificate) |
102
+ | `fr_categories` | List course categories as a tree of slugs and names |
103
+ | `fr_suggest` | Get the site's search-box suggestions for the start of a phrase |
104
+ | `fr_instructors` | Find instructors by name, or the top instructors of a category |
105
+ | `fr_instructor` | Get an instructor's profile, rating statistics and courses |
106
+ | `fr_learning_paths` | List or search curated learning paths (course collections) |
107
+ | `fr_learning_path` | Get one learning path: its ordered courses, totals and related paths |
108
+ | `fr_offers` | List current discount campaigns, public coupon codes and subscription plans |
109
+ | `fr_faq` | Get Faradars' general help answers (buying, access, certificates, support) |
110
+ | `fr_articles` | Search Faradars Magazine articles by text, category or tag, or list the newest |
111
+ | `fr_article` | Read one Magazine article: key points, outline, text, views and rating |
112
+ | `fr_article_topics` | List Magazine categories or tags with article counts |
113
+
114
+ All 16 tools are annotated `readOnlyHint: true`.
115
+
116
+ ## How it works
117
+
118
+ ```text
119
+ AI agent ──MCP over stdio──▶ faradars-mcp ──HTTPS──▶ faradars.org/api/client courses, categories, instructors
120
+ └──────▶ blog.faradars.org/wp-json magazine
121
+ ```
122
+
123
+ Requests look like Faradars' own web app (Chrome TLS fingerprint and headers), at most two at a time, with a 5 minute
124
+ cache. Set `FARADARS_MCP_PROXY=http://host:port` to route through a proxy.
125
+
126
+ ## Notes
127
+
128
+ - Unofficial. Not affiliated with or endorsed by Faradars. It reads the same public data the website shows to anyone.
129
+ - Course content (videos) is not exposed; only catalog data.
130
+ - Prices change with Faradars sales (`sale_price` is time-limited).
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ uv sync
136
+ uv run ruff check . && uv run ruff format --check .
137
+ uv run python -m pytest -q # offline
138
+ uv run python -m pytest -m live -q # real faradars.org
139
+ ```
140
+
141
+ ## فارسی
142
+
143
+ **faradars-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای فرادرس است. با آن، دستیار هوش مصنوعی می‌تواند دوره‌ها را جست‌وجو کند، قیمت و تخفیف و سرفصل‌ها را بخواند، نظر دانشجویان را ببیند، مدرس‌ها و مسیرهای یادگیری را پیدا کند و در مجله فرادرس بگردد. نیازی به کلید API یا حساب کاربری نیست.
144
+
145
+ نصب: `claude mcp add faradars -- uvx faradars-mcp`
146
+
147
+ ## License
148
+
149
+ MIT. Built by [Sepehr Radmard](https://github.com/sepehr071) (سپهر رادمرد).
faradars_mcp-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,56 @@
1
+ [project]
2
+ name = "faradars-mcp"
3
+ version = "0.1.0"
4
+ description = "Unofficial read-only MCP server for Faradars (faradars.org), the Persian online course platform: course search, prices, syllabus, instructors, magazine."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
9
+ requires-python = ">=3.10"
10
+ keywords = ["mcp", "model-context-protocol", "faradars", "faradars-org", "online-courses", "e-learning", "iran", "persian", "farsi", "education", "courses", "instructors", "claude"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Intended Audience :: Developers",
14
+ "Operating System :: OS Independent",
15
+ "Programming Language :: Python :: 3",
16
+ "Programming Language :: Python :: 3.10",
17
+ "Programming Language :: Python :: 3.11",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
21
+ "Topic :: Education",
22
+ ]
23
+ dependencies = [
24
+ "mcp>=2.2,<3",
25
+ "httpx>=0.27",
26
+ "httpx-curl-cffi>=0.1.5",
27
+ "curl-cffi>=0.16.3",
28
+ ]
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/sepehr071/faradars-mcp"
32
+ Issues = "https://github.com/sepehr071/faradars-mcp/issues"
33
+ Website = "https://mcpfarsi.ir/"
34
+
35
+ [project.scripts]
36
+ faradars-mcp = "faradars_mcp.server:main"
37
+
38
+ [dependency-groups]
39
+ dev = ["pytest>=8", "ruff>=0.6"]
40
+
41
+ [build-system]
42
+ requires = ["hatchling"]
43
+ build-backend = "hatchling.build"
44
+
45
+ [tool.pytest.ini_options]
46
+ testpaths = ["tests"]
47
+ addopts = "-m 'not live'"
48
+ markers = ["live: calls the real Faradars APIs (run with -m live)"]
49
+
50
+ [tool.ruff]
51
+ line-length = 120
52
+ target-version = "py310"
53
+
54
+ [tool.ruff.lint]
55
+ select = ["E", "F", "I", "B", "UP"]
56
+ ignore = ["E501"] # long Field(description=...) strings read better on one line
faradars_mcp-0.1.0/server.json ADDED
@@ -0,0 +1,32 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.sepehr071/faradars-mcp",
4
+ "title": "Faradars Courses",
5
+ "description": "Read-only Faradars (faradars.org) courses: search, prices, syllabus, reviews, instructors, magazine.",
6
+ "repository": {
7
+ "url": "https://github.com/sepehr071/faradars-mcp",
8
+ "source": "github"
9
+ },
10
+ "websiteUrl": "https://github.com/sepehr071/faradars-mcp",
11
+ "version": "0.1.0",
12
+ "packages": [
13
+ {
14
+ "registryType": "pypi",
15
+ "registryBaseUrl": "https://pypi.org",
16
+ "identifier": "faradars-mcp",
17
+ "version": "0.1.0",
18
+ "runtimeHint": "uvx",
19
+ "transport": {
20
+ "type": "stdio"
21
+ },
22
+ "environmentVariables": [
23
+ {
24
+ "name": "FARADARS_MCP_PROXY",
25
+ "description": "Optional HTTP proxy URL for the Faradars 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.",
26
+ "isRequired": false,
27
+ "isSecret": false
28
+ }
29
+ ]
30
+ }
31
+ ]
32
+ }
faradars_mcp-0.1.0/src/faradars_mcp/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Unofficial MCP server for Faradars (faradars.org), the Persian online course platform: courses, instructors, magazine."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("faradars-mcp")