rrk-mcp 0.1.0__tar.gz

rrk_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

rrk_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/rrk-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

rrk_mcp-0.1.0/.gitignore

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

rrk_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.

rrk_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: rrk-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for the Official Gazette of Iran (rrk.ir, روزنامه رسمی): laws, regulations and court rulings.
+Project-URL: Homepage, https://github.com/sepehr071/rrk-mcp
+Project-URL: Issues, https://github.com/sepehr071/rrk-mcp/issues
+Project-URL: Website, https://mcpfarsi.ir/
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,iran-law,laws,legal,mcp,model-context-protocol,official-gazette,persian,regulations,rrk,rrk-ir
+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
+Classifier: Topic :: Text Processing
+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/rrk-mcp -->
+
+<div align="center">
+
+# rrk-mcp: Official Gazette of Iran (روزنامه رسمی) laws and rulings MCP server for AI agents
+
+**rrk-mcp is an unofficial, read-only MCP server for the laws and regulations database of the Official Gazette of Iran (rrk.ir).**<br>
+Its 5 tools list the newest laws, search them by title, full text, group, approver, special issue number or gazette date,<br>
+read the full text of a law, court ruling or regulation, and list the licensed exchange offices. No API key or account is needed.
+
+[![PyPI](https://img.shields.io/pypi/v/rrk-mcp?color=2563eb)](https://pypi.org/project/rrk-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/rrk-mcp)](https://pypi.org/project/rrk-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/rrk-mcp/blob/main/LICENSE)
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [Limits](#limits) · [فارسی](#فارسی)
+
+</div>
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server for rrk.ir, the Official Gazette: laws (قوانین), regulations (آیین‌نامه، مصوبات), Court of Administrative Justice rulings (آرای دیوان عدالت اداری) and other texts published in the gazette since 1285 (2026 = 1405).
+- **Install:** `uvx rrk-mcp` or `claude mcp add rrk -- uvx rrk-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `RRK_MCP_PROXY` (HTTP proxy URL); system proxy settings are ignored.
+- **Access:** read-only; no confirmation is needed before calling any tool.
+- **Tools:** 5, all prefixed `rk_`. Typical sequence: `rk_law_filters` (optional) -> `rk_search_laws` -> `rk_law_text`.
+- **Use when:** the user asks what the gazette published lately, wants a law or ruling by topic or date, or needs the text of one.
+- **Do not use when:** the user wants company registration notices (founding, capital change, board change, liquidation). rrk.ir does not offer those in an open search, so this server cannot look companies up.
+- **Output:** compact JSON, Persian text. Dates are Jalali (`1405/08/09`).
+
+## Quick start
+
+```bash
+claude mcp add rrk -- uvx rrk-mcp
+```
+
+Any other client: run `uvx rrk-mcp` as a stdio MCP server (`{"command": "uvx", "args": ["rrk-mcp"]}`).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `rk_latest_laws` | List the newest laws, rulings and regulations in the Official Gazette, newest first |
+| `rk_search_laws` | Search laws by title words, full-text words, law group, approver, special issue number or Jalali gazette date range |
+| `rk_law_filters` | List the law groups (categories) and approving authorities to filter by |
+| `rk_law_text` | Read one law's approver, gazette number and date, and full text (long texts in parts) |
+| `rk_exchange_offices` | List the licensed currency exchange offices (location, phone, address) by province and city |
+
+All 5 tools are annotated `readOnlyHint: true`.
+
+## Limits
+
+- Laws only. Company notices (آگهی‌های ثبتی) sit behind rrk.ir's paid data service and login, so they are left out.
+- The portal is slow (a full-text search can take 10 seconds) and shares one session; the server keeps one session and reuses it.
+- `rk_law_text` works with any code, but a code the session has not listed is located by paging the list (10-60 s, and codes below about 10,000 may not be found). Majlis debates (group 64) have a title only; the debate text is a PDF behind login.
+- Gazette PDFs and the shop need login or payment, and are left out.
+- Persian ی and ک are converted to the Arabic ي and ك the portal stores; you can type either.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q
+uv run python -m pytest -m live -q
+```
+
+## فارسی
+
+`rrk-mcp` یک سرور MCP غیررسمی و فقط‌خواندنی برای پایگاه قوانین و مقررات روزنامه رسمی (rrk.ir) است: فهرست جدیدترین قوانین، جستجو بر اساس عنوان، متن، شماره ویژه‌نامه و تاریخ روزنامه، فیلتر بر اساس گروه قوانین و مرجع تصویب، خواندن متن کامل قانون یا رأی، و فهرست صرافی‌های مجاز بانک مرکزی. جستجوی آگهی‌های ثبتی شرکت‌ها در سایت به‌صورت باز وجود ندارد و پشتیبانی نمی‌شود.
+
+---
+
+Made by Sepehr Radmard (سپهر رادمرد) · [github.com/sepehr071](https://github.com/sepehr071) · [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard)

rrk_mcp-0.1.0/README.md

@@ -0,0 +1,75 @@
+<!-- mcp-name: io.github.sepehr071/rrk-mcp -->
+
+<div align="center">
+
+# rrk-mcp: Official Gazette of Iran (روزنامه رسمی) laws and rulings MCP server for AI agents
+
+**rrk-mcp is an unofficial, read-only MCP server for the laws and regulations database of the Official Gazette of Iran (rrk.ir).**<br>
+Its 5 tools list the newest laws, search them by title, full text, group, approver, special issue number or gazette date,<br>
+read the full text of a law, court ruling or regulation, and list the licensed exchange offices. No API key or account is needed.
+
+[![PyPI](https://img.shields.io/pypi/v/rrk-mcp?color=2563eb)](https://pypi.org/project/rrk-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/rrk-mcp)](https://pypi.org/project/rrk-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/rrk-mcp/blob/main/LICENSE)
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [Limits](#limits) · [فارسی](#فارسی)
+
+</div>
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server for rrk.ir, the Official Gazette: laws (قوانین), regulations (آیین‌نامه، مصوبات), Court of Administrative Justice rulings (آرای دیوان عدالت اداری) and other texts published in the gazette since 1285 (2026 = 1405).
+- **Install:** `uvx rrk-mcp` or `claude mcp add rrk -- uvx rrk-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `RRK_MCP_PROXY` (HTTP proxy URL); system proxy settings are ignored.
+- **Access:** read-only; no confirmation is needed before calling any tool.
+- **Tools:** 5, all prefixed `rk_`. Typical sequence: `rk_law_filters` (optional) -> `rk_search_laws` -> `rk_law_text`.
+- **Use when:** the user asks what the gazette published lately, wants a law or ruling by topic or date, or needs the text of one.
+- **Do not use when:** the user wants company registration notices (founding, capital change, board change, liquidation). rrk.ir does not offer those in an open search, so this server cannot look companies up.
+- **Output:** compact JSON, Persian text. Dates are Jalali (`1405/08/09`).
+
+## Quick start
+
+```bash
+claude mcp add rrk -- uvx rrk-mcp
+```
+
+Any other client: run `uvx rrk-mcp` as a stdio MCP server (`{"command": "uvx", "args": ["rrk-mcp"]}`).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `rk_latest_laws` | List the newest laws, rulings and regulations in the Official Gazette, newest first |
+| `rk_search_laws` | Search laws by title words, full-text words, law group, approver, special issue number or Jalali gazette date range |
+| `rk_law_filters` | List the law groups (categories) and approving authorities to filter by |
+| `rk_law_text` | Read one law's approver, gazette number and date, and full text (long texts in parts) |
+| `rk_exchange_offices` | List the licensed currency exchange offices (location, phone, address) by province and city |
+
+All 5 tools are annotated `readOnlyHint: true`.
+
+## Limits
+
+- Laws only. Company notices (آگهی‌های ثبتی) sit behind rrk.ir's paid data service and login, so they are left out.
+- The portal is slow (a full-text search can take 10 seconds) and shares one session; the server keeps one session and reuses it.
+- `rk_law_text` works with any code, but a code the session has not listed is located by paging the list (10-60 s, and codes below about 10,000 may not be found). Majlis debates (group 64) have a title only; the debate text is a PDF behind login.
+- Gazette PDFs and the shop need login or payment, and are left out.
+- Persian ی and ک are converted to the Arabic ي and ك the portal stores; you can type either.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q
+uv run python -m pytest -m live -q
+```
+
+## فارسی
+
+`rrk-mcp` یک سرور MCP غیررسمی و فقط‌خواندنی برای پایگاه قوانین و مقررات روزنامه رسمی (rrk.ir) است: فهرست جدیدترین قوانین، جستجو بر اساس عنوان، متن، شماره ویژه‌نامه و تاریخ روزنامه، فیلتر بر اساس گروه قوانین و مرجع تصویب، خواندن متن کامل قانون یا رأی، و فهرست صرافی‌های مجاز بانک مرکزی. جستجوی آگهی‌های ثبتی شرکت‌ها در سایت به‌صورت باز وجود ندارد و پشتیبانی نمی‌شود.
+
+---
+
+Made by Sepehr Radmard (سپهر رادمرد) · [github.com/sepehr071](https://github.com/sepehr071) · [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard)

rrk_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "rrk-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for the Official Gazette of Iran (rrk.ir, روزنامه رسمی): laws, regulations and court rulings."
+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", "rrk", "rrk-ir", "official-gazette", "iran-law", "laws", "regulations", "legal", "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",
+    "Topic :: Text Processing",
+]
+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/rrk-mcp"
+Issues = "https://github.com/sepehr071/rrk-mcp/issues"
+Website = "https://mcpfarsi.ir/"
+
+[project.scripts]
+rrk-mcp = "rrk_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 rrk.ir portal (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

rrk_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/rrk-mcp",
+  "title": "Official Gazette of Iran",
+  "description": "Read-only Official Gazette of Iran (rrk.ir): search laws and rulings, read their text.",
+  "repository": {
+    "url": "https://github.com/sepehr071/rrk-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/rrk-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "rrk-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "RRK_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for the rrk.ir requests; system proxy settings are ignored.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

rrk_mcp-0.1.0/src/rrk_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for the Official Gazette of Iran (rrk.ir): laws, regulations and rulings."""
+
+from importlib.metadata import version
+
+__version__ = version("rrk-mcp")

rrk_mcp-0.1.0/src/rrk_mcp/certs/certum_dv_tls_g2_r39.pem

@@ -0,0 +1,38 @@
+-----BEGIN CERTIFICATE-----
+MIIGnTCCBIWgAwIBAgIRAKgt2eXcr98TIF5wBD5rlagwDQYJKoZIhvcNAQENBQAw
+ejELMAkGA1UEBhMCUEwxITAfBgNVBAoTGEFzc2VjbyBEYXRhIFN5c3RlbXMgUy5B
+LjEnMCUGA1UECxMeQ2VydHVtIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MR8wHQYD
+VQQDExZDZXJ0dW0gVHJ1c3RlZCBSb290IENBMB4XDTI0MDYxODA3NDEyMloXDTM5
+MDYwNTA3NDEyMlowUjELMAkGA1UEBhMCUEwxITAfBgNVBAoMGEFzc2VjbyBEYXRh
+IFN5c3RlbXMgUy5BLjEgMB4GA1UEAwwXQ2VydHVtIERWIFRMUyBHMiBSMzkgQ0Ew
+ggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCo52NXEXWoO2w6zQeBtNer
+d5ahhe8RgM8XVpwGEFoovjHc4K+Cp3auUWVlt7/ARthJoxOttF+jaSrlSve9mWnm
+TJOo1QLuoOTWuZ9XUkMjDG1ztTbFsgRqQyOtZsDqniHD79wqD49DQW4geVslp9/L
+iTQKUpPawtAwpBeoaRXL8RJ8xjNA+2bEr6vesz2MEvvhpWBSWNAIR5O5YbiLztQ9
+KdOuBYS0CW59ptuCjg3AuLcp8aOjk9z/kJc8xKkO48hLTp+HpdHkuI+iFWZn0aCL
+lM/ngpdoBw+NGs6TMC8B6BcK7y/zl8FsNC4gE86Kfd8J9zWhCA7umHnBXCSYCKRx
+H5o7DtoGiWXvcRKYpGtWt9czdUa1edSk5mTrwZGEXLAkX1ECiAq4GS5vEGjrEQ1u
+x8mag2LDh7ZnXdcyzkKZKGsx7uExe3Nx5gWWZMXFrZ5v+uxynKogHUY2vdIMB3dn
+9qRYwpzvn3msfBbkRTAcS9eis1AY0Xxqlt3aXkVyqfKhdJxOPpzATM+Ve4jZSd1n
+LzEj+kFuHnv2jyOY3Vb35n3EmW8yAwG1OWX/QnemMA5s2fZ+ZydHOTG4DkwXnaTr
+R/vUhM+FNywNUlvzYjcM6zt3Ysf9M1hK5PjUEKzsPf5BrIp0fs1zhlVC+cgBN2+J
+PtYwxP1nNpxwBgtIPoTk6wIDAQABo4IBRDCCAUAwcQYIKwYBBQUHAQEEZTBjMDcG
+CCsGAQUFBzAChitodHRwOi8vc3ViY2EucmVwb3NpdG9yeS5jZXJ0dW0ucGwvY3Ry
+Y2EuY2VyMCgGCCsGAQUFBzABhhxodHRwOi8vc3ViY2Eub2NzcC1jZXJ0dW0uY29t
+MB8GA1UdIwQYMBaAFIz7HHW8AtOfTi5I2flgVKrEs0/6MBIGA1UdEwEB/wQIMAYB
+Af8CAQAwNQYDVR0fBC4wLDAqoCigJoYkaHR0cDovL3N1YmNhLmNybC5jZXJ0dW0u
+cGwvY3RyY2EuY3JsMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAOBgNV
+HQ8BAf8EBAMCAQYwEQYDVR0gBAowCDAGBgRVHSAAMB0GA1UdDgQWBBQzqHe3AThv
+Xx8kJKIebBTjbiID3zANBgkqhkiG9w0BAQ0FAAOCAgEACDQ1ggBelZZ/NYs1nFKW
+HnDrA8Y4pv0lvxLzSAC4ejGavMXqPTXHA+DEh9kHNd8tVlo24+6YN96Gspb1kMXR
+uuql23/6R6Fpqg49dkQ1/DobsWvAHoYeZvsaAgaKRD3bvsAcB0JBhyBVT/88S9gu
+DnS5YKMldiLMkVW1Noskd4dHEJ2mkJcVzJIJ0Y4johA1lC1JnZMjkB8ZTNIblkgJ
+K6PqlhYkeMOkx+XbmUuUgh29T0sPne7/V6PHnbEJIxUs40+iLCF0HrdqZypjvWQq
+pSmHRHI3UWVERDeERca0uJ3I+a5ER9vUL9u5ilGG4afyx7QwzitBG+1rU3nRsHyZ
+g6osILL/MWc0AbWJMyKzQ9Guj+uwq47h6BC9BsWF34pJeDC8EuN3HNxPlSWSII9l
+Omwtipvq0EL1iocJhXdlsG+jIUVs/Sl/Um9JiZV+h/MoytnrPrWMIj+0zz6BdaPP
+2sT6wcLzpnwYcE9FWSbQrzNpL283EOUkObjc8AIxICzPHGusF0IqsO+sj9XzvLTh
+TjKfFlzx4NR8gbK7m8sXq6cgP4UAtyvDswebFIRQiuhjqOT9G7+56+4zC0RaEZx/
+LwoFE+ObVXxX674szQvIc+7WPCooVsUbwZIikzJqZb4gJQ1OQx23CgyyYlsPHIDN
+8FpPkganuCwy++7umTkM7+Q=
+-----END CERTIFICATE-----

rrk_mcp-0.1.0/src/rrk_mcp/exchanges.py

@@ -0,0 +1,139 @@
+"""Tool for the list of licensed currency exchange offices that the Official Gazette publishes (rrk.ir, page 176).
+
+Same APEX mechanics as laws.py: load the page once for a session, then post the classic report's refresh call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html
+import json
+import re
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from . import http
+from .http import ApiError
+from .laws import AJAX_URL, _field, _strip
+from .registry import tool
+
+PAGE_URL = f"{http.SITE}/ords/r/rrs/rrs-front/r-exchanges"
+PER_PAGE = 50  # the report's fixed page size
+COLUMNS = ("STATENAME", "CITYNAME", "REGION", "PHONENUMBER", "ZIPCODE", "ADDRESS")
+
+_state: dict[str, Any] = {}
+_lock: asyncio.Lock | None = None
+
+
+class _SessionLost(ApiError):
+    """The portal answered with something other than the report (expired session); retried once with a new one."""
+
+
+def reset() -> None:
+    _state.clear()
+
+
+async def _session(force: bool = False) -> dict[str, Any]:
+    global _lock
+    _lock = _lock or asyncio.Lock()
+    async with _lock:
+        if force or not _state:
+            h = await http.fetch(PAGE_URL, cache=False)
+            sel = re.search(r'<select[^>]*id="P176_PROVINCE".*?</select>', h, re.S)
+            _state.clear()
+            _state.update(
+                instance=_field(h, r'name="p_instance" value="(\d+)"'),
+                salt=_field(h, r'value="(\d+)" id="pSalt"'),
+                protected=_field(h, r'id="pPageItemsProtected" value="([^"]+)"'),
+                region=_field(h, r'apex\.widget\.report\.init\("R(\d+)"'),
+                request=_field(h, r'apex\.widget\.report\.init\("R\d+","([^"]+)"').replace("\\u002F", "/"),
+                provinces=[html.unescape(v) for v in re.findall(r'<option value="([^"]+)"', sel[0])] if sel else [],
+            )
+        return dict(_state)
+
+
+def _parse(out: str, page: int) -> dict[str, Any]:
+    if "t-Report" not in out:
+        raise _SessionLost("rrk.ir returned no exchange list (session problem). Try again in a minute.")
+    m = re.search(r"t-Report-paginationText\">[^<]*?(\d+)\s*-\s*(\d+)\s*\S+\s*([\d,]+)", out)
+    total = int(m[3].replace(",", "")) if m else 0
+    offices = []
+    for row in re.findall(r"<tr>(<td class=\"t-Report-cell\".*?)</tr>", out, re.S):
+        cells = dict(re.findall(r'headers="([A-Z]+)"[^>]*>(.*?)</td>', row, re.S))
+        offices.append(
+            {
+                "province": _strip(cells.get("STATENAME", "")),
+                "city": _strip(cells.get("CITYNAME", "")),
+                "district": _strip(cells.get("REGION", "")),
+                "phone": _strip(cells.get("PHONENUMBER", "")),
+                "postal_code": _strip(cells.get("ZIPCODE", "")),
+                "address": _strip(cells.get("ADDRESS", "")),
+            }
+        )
+    return {"total": total, "page": page, "more": page * PER_PAGE < total, "offices": offices}
+
+
+_PERSIAN = str.maketrans({"ي": "ی", "ك": "ک", "ى": "ی"})  # the province/city lists use Persian ی and ک
+
+
+@tool("Licensed exchange offices")
+async def rk_exchange_offices(
+    province: Annotated[str, Field(description="Province name as on the site, e.g. 'تهران', 'قم'. Empty = all.")] = "",
+    city: Annotated[
+        str, Field(description="City name as on the site, e.g. 'قم', 'سلفچگان'. Empty = whole province.")
+    ] = "",
+    page: Annotated[int, Field(description="Page number, 50 offices per page.", ge=1, le=200)] = 1,
+) -> dict[str, Any]:
+    """List the licensed currency exchange offices (صرافی مجاز) the Central Bank published in the Official Gazette (rrk.ir).
+
+    Use to see where licensed exchange offices are or to find one's address and phone. Filter by `province` and
+    `city` (Persian names; an unknown province is an error that lists the valid ones). Returns `total`, `more`
+    and up to 50 `offices` with province, city, district, phone, postal_code and address. Office names are not
+    published, only the location.
+    """
+    province, city = province.translate(_PERSIAN).strip(), city.translate(_PERSIAN).strip()
+    try:
+        return await _list(province, city, page, False)
+    except _SessionLost:
+        return await _list(province, city, page, True)
+
+
+async def _list(province: str, city: str, page: int, force: bool) -> dict[str, Any]:
+    s = await _session(force)
+    if province and province not in s["provinces"]:
+        raise ApiError(f"Unknown province {province!r}. Valid: " + ", ".join(s["provinces"]))
+    if city and not province:
+        raise ApiError("Give the province together with the city.")
+    form = {
+        "p_flow_id": "200",
+        "p_flow_step_id": "176",
+        "p_instance": s["instance"],
+        "p_debug": "",
+        "p_request": "PLUGIN=" + s["request"],
+        "x01": s["region"],
+        "p_widget_action": "reset",
+        "p_json": json.dumps(
+            {
+                "pageItems": {
+                    "itemsToSubmit": [{"n": "P176_PROVINCE", "v": province}, {"n": "P176_CITY", "v": city}],
+                    "protected": s["protected"],
+                    "rowVersion": "",
+                    "formRegionChecksums": [],
+                },
+                "salt": s["salt"],
+            }
+        ),
+    }
+    if page > 1:
+        form |= {
+            "p_widget_action": "paginate",
+            "p_pg_min_row": str((page - 1) * PER_PAGE + 1),
+            "p_pg_max_rows": str(PER_PAGE),
+            "p_pg_rows_fetched": str(PER_PAGE),
+        }
+    out = await http.fetch(f"{AJAX_URL}?p_context=rrs-front/r-exchanges/{s['instance']}", data=form)
+    r = _parse(out, page)
+    if city and not r["total"]:
+        r["note"] = f"No office in city {city!r}; use the city name exactly as the site writes it."
+    return r