ifb-mcp 0.1.0__tar.gz

ifb_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

ifb_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/ifb-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

ifb_mcp-0.1.0/.gitignore

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

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

ifb_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: ifb-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Iran Fara Bourse (ifb.ir): bond and sukuk yields, treasury bills, IPOs, announcements, market stats.
+Project-URL: Homepage, https://github.com/sepehr071/ifb-mcp
+Project-URL: Issues, https://github.com/sepehr071/ifb-mcp/issues
+Project-URL: Website, https://mcpfarsi.ir/
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bonds,bourse,claude,fara-bourse,farabourse,ifb,ipo,iran,iran-fara-bourse,mcp,model-context-protocol,otc,persian,sukuk,treasury-bills,ytm
+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 :: Office/Business :: Financial :: Investment
+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/ifb-mcp -->
+
+<div align="center">
+
+# ifb-mcp: Iran Fara Bourse (فرابورس ایران) bonds, sukuk and IPO MCP server for AI agents
+
+**ifb-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Iran Fara Bourse (ifb.ir), Iran's over-the-counter exchange.**<br>
+Its 16 tools rank bonds, sukuk and treasury bills (اخزا) by yield to maturity, explain a paper's coupons and issuer,<br>
+quote prices and order books, list IPOs and new offerings, search exchange notices and news, and summarise the market.<br>
+No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[![PyPI](https://img.shields.io/pypi/v/ifb-mcp?color=2563eb)](https://pypi.org/project/ifb-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/ifb-mcp)](https://pypi.org/project/ifb-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/ifb-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) · [فارسی](#فارسی)
+
+</div>
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for ifb.ir: yield to maturity of every treasury bill, sukuk and bond, instrument details with coupon schedules, live quotes and order books, price and yield history, IPOs (finished and upcoming), underwritings, exchange announcements, news and market messages, market summary, the live market watch with top movers and most traded, index history, halted symbols, capital increases and board transfers, yield curves and who trades Islamic securities.
+- **Install:** `uvx ifb-mcp` or `claude mcp add ifb -- uvx ifb-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `IFB_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot trade, log in or change anything, so no confirmation is needed before calling any tool.
+- **Tools:** 16, all prefixed `ifb_`. Typical sequences: `ifb_yields` -> `ifb_instrument` / `ifb_quote`; `ifb_search` -> `ifb_history`; `ifb_ipos(stage="pipeline")`; `ifb_announcements` -> `ifb_article`.
+- **Use when:** the user asks which bond, sukuk or treasury bill yields most or matures when, what a paper pays and when, a Fara Bourse price or order book, what IPOs are coming or happened, why a symbol is halted, or how the market did.
+- **Do not use when:** the question is about the Tehran Stock Exchange (tse.ir), cryptocurrencies or gold; or the user wants to place an order.
+- **Output:** compact JSON. Prices in rial, yields in percent a year, dates Jalali (`1405/08/09`). Texts are the exchange's own (Persian). The site is reachable from Iranian networks only.
+- **Machine-readable:** [`server.json`](https://github.com/sepehr071/ifb-mcp/blob/main/server.json).
+
+## Why
+
+On ifb.ir, "which treasury bill maturing before next spring pays the best yield?" means opening the yield page,
+scrolling 1,000 rows and sorting by hand. With `ifb-mcp` an agent answers it in one call:
+
+> **You:** Best yield among treasury bills maturing before 1405/12/01?
+>
+> **Agent:** *calls* `ifb_yields(kind="treasury", matures_before="1405/12/01", limit=3)`
+
+<sub>Data is the exchange's, as shown on its website; yields are computed by Fara Bourse from the last trade. This is information, not investment advice.</sub>
+
+## What it can do
+
+- **Rank fixed income by yield**: treasury bills, sukuk, participation papers and other bonds with last price, maturity and YTM, filtered by yield, maturity and symbol
+- **Explain a paper**: coupon rate, maturity, issuer, guarantor, underwriter, market maker, full coupon schedule and the next payment
+- **Quote and chart**: live price, change, volume, order book with the yield of each bid and offer, and daily history with YTM
+- **Follow offerings**: finished IPOs with price and volume (filter by market and pricing method), companies being introduced, underwritings
+- **Read the exchange**: search official notices, news and market messages (halts, openings) by keyword and date, and read an article
+- **Watch the live market**: every symbol's price, change and best bid/ask ranked by change or value, per board; halted symbols with reasons; index history since 2009; capital increases and board transfers
+- **See the market**: index, turnover, bond indices, each board's value and top movers, the fitted yield curves and who buys and sells Islamic securities
+- **Read-only by design**: no login, no orders
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account. ifb.ir answers Iranian
+networks; from abroad set `IFB_MCP_PROXY` to an Iranian proxy.
+
+```bash
+claude mcp add ifb -- uvx ifb-mcp
+```
+
+Claude Desktop, Cursor and others:
+
+```json
+{
+  "mcpServers": {
+    "ifb": { "command": "uvx", "args": ["ifb-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | Use it to |
+|---|---|
+| `ifb_search` | turn a symbol or name into an instrument id |
+| `ifb_yields` | rank bonds, sukuk and treasury bills by YTM with maturity and price filters |
+| `ifb_instrument` | read coupon rate, maturity, issuer, guarantor and the coupon schedule |
+| `ifb_quote` | get the live price, volume, order book and yields |
+| `ifb_history` | get daily prices and YTM |
+| `ifb_ipos` | list finished IPOs or those upcoming and under way |
+| `ifb_underwritings` | list securities offered by underwriting |
+| `ifb_announcements` | search notices, news and market messages |
+| `ifb_article` | read one news article |
+| `ifb_market_summary` | index, turnover, bond indices, boards and top movers |
+| `ifb_yield_curve` | fitted yield curves for government, non-government and treasury bills |
+| `ifb_sukuk_flows` | daily value of Islamic securities bought and sold by investor type |
+| `ifb_market_watch` | live market watch: top gainers, losers and most traded per board, halted symbols |
+| `ifb_index_history` | daily history of the total, equal-weight, price and sukuk indices with 1d/5d/21d/250d changes |
+| `ifb_corporate_actions` | capital increases with rights windows, board transfers, new listings, moves to Tehran Stock Exchange |
+| `ifb_halted` | symbols halted now with date and reason, and issuers flagged for weak disclosure |
+
+## FAQ
+
+**Is it official?** No. It reads the public pages and web service of ifb.ir and is not affiliated with Iran Fara Bourse.
+
+**Why do symbols end in a digit?** The exchange lists each paper on several boards (`کارون0731`, `0732`). Take the `id` from `ifb_yields` or `ifb_search`.
+
+**Is the market watch included?** Not the live ranking grid, which the site fills through a push connection. Quotes come from the site's JSON service.
+
+## فارسی
+
+<div dir="rtl">
+
+**ifb-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای فرابورس ایران (ifb.ir) است. با آن می‌توان اوراق بدهی، صکوک و اسناد خزانه (اخزا) را بر پایهٔ بازده تا سررسید (YTM) مرتب کرد، جزئیات و برنامهٔ پرداخت سود هر ورقه را دید، قیمت و صف خرید و فروش را گرفت، عرضه‌های اولیه و پذیره‌نویسی‌ها را دید، اطلاعیه‌ها و اخبار را جستجو کرد و خلاصهٔ بازار را خواند. کلید API یا حساب لازم نیست. سایت فقط از شبکه‌های ایران پاسخ می‌دهد.
+
+نصب: `claude mcp add ifb -- uvx ifb-mcp`
+
+</div>
+
+## License
+
+MIT

ifb_mcp-0.1.0/README.md

@@ -0,0 +1,116 @@
+<!-- mcp-name: io.github.sepehr071/ifb-mcp -->
+
+<div align="center">
+
+# ifb-mcp: Iran Fara Bourse (فرابورس ایران) bonds, sukuk and IPO MCP server for AI agents
+
+**ifb-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Iran Fara Bourse (ifb.ir), Iran's over-the-counter exchange.**<br>
+Its 16 tools rank bonds, sukuk and treasury bills (اخزا) by yield to maturity, explain a paper's coupons and issuer,<br>
+quote prices and order books, list IPOs and new offerings, search exchange notices and news, and summarise the market.<br>
+No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[![PyPI](https://img.shields.io/pypi/v/ifb-mcp?color=2563eb)](https://pypi.org/project/ifb-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/ifb-mcp)](https://pypi.org/project/ifb-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/ifb-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) · [فارسی](#فارسی)
+
+</div>
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for ifb.ir: yield to maturity of every treasury bill, sukuk and bond, instrument details with coupon schedules, live quotes and order books, price and yield history, IPOs (finished and upcoming), underwritings, exchange announcements, news and market messages, market summary, the live market watch with top movers and most traded, index history, halted symbols, capital increases and board transfers, yield curves and who trades Islamic securities.
+- **Install:** `uvx ifb-mcp` or `claude mcp add ifb -- uvx ifb-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `IFB_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot trade, log in or change anything, so no confirmation is needed before calling any tool.
+- **Tools:** 16, all prefixed `ifb_`. Typical sequences: `ifb_yields` -> `ifb_instrument` / `ifb_quote`; `ifb_search` -> `ifb_history`; `ifb_ipos(stage="pipeline")`; `ifb_announcements` -> `ifb_article`.
+- **Use when:** the user asks which bond, sukuk or treasury bill yields most or matures when, what a paper pays and when, a Fara Bourse price or order book, what IPOs are coming or happened, why a symbol is halted, or how the market did.
+- **Do not use when:** the question is about the Tehran Stock Exchange (tse.ir), cryptocurrencies or gold; or the user wants to place an order.
+- **Output:** compact JSON. Prices in rial, yields in percent a year, dates Jalali (`1405/08/09`). Texts are the exchange's own (Persian). The site is reachable from Iranian networks only.
+- **Machine-readable:** [`server.json`](https://github.com/sepehr071/ifb-mcp/blob/main/server.json).
+
+## Why
+
+On ifb.ir, "which treasury bill maturing before next spring pays the best yield?" means opening the yield page,
+scrolling 1,000 rows and sorting by hand. With `ifb-mcp` an agent answers it in one call:
+
+> **You:** Best yield among treasury bills maturing before 1405/12/01?
+>
+> **Agent:** *calls* `ifb_yields(kind="treasury", matures_before="1405/12/01", limit=3)`
+
+<sub>Data is the exchange's, as shown on its website; yields are computed by Fara Bourse from the last trade. This is information, not investment advice.</sub>
+
+## What it can do
+
+- **Rank fixed income by yield**: treasury bills, sukuk, participation papers and other bonds with last price, maturity and YTM, filtered by yield, maturity and symbol
+- **Explain a paper**: coupon rate, maturity, issuer, guarantor, underwriter, market maker, full coupon schedule and the next payment
+- **Quote and chart**: live price, change, volume, order book with the yield of each bid and offer, and daily history with YTM
+- **Follow offerings**: finished IPOs with price and volume (filter by market and pricing method), companies being introduced, underwritings
+- **Read the exchange**: search official notices, news and market messages (halts, openings) by keyword and date, and read an article
+- **Watch the live market**: every symbol's price, change and best bid/ask ranked by change or value, per board; halted symbols with reasons; index history since 2009; capital increases and board transfers
+- **See the market**: index, turnover, bond indices, each board's value and top movers, the fitted yield curves and who buys and sells Islamic securities
+- **Read-only by design**: no login, no orders
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account. ifb.ir answers Iranian
+networks; from abroad set `IFB_MCP_PROXY` to an Iranian proxy.
+
+```bash
+claude mcp add ifb -- uvx ifb-mcp
+```
+
+Claude Desktop, Cursor and others:
+
+```json
+{
+  "mcpServers": {
+    "ifb": { "command": "uvx", "args": ["ifb-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | Use it to |
+|---|---|
+| `ifb_search` | turn a symbol or name into an instrument id |
+| `ifb_yields` | rank bonds, sukuk and treasury bills by YTM with maturity and price filters |
+| `ifb_instrument` | read coupon rate, maturity, issuer, guarantor and the coupon schedule |
+| `ifb_quote` | get the live price, volume, order book and yields |
+| `ifb_history` | get daily prices and YTM |
+| `ifb_ipos` | list finished IPOs or those upcoming and under way |
+| `ifb_underwritings` | list securities offered by underwriting |
+| `ifb_announcements` | search notices, news and market messages |
+| `ifb_article` | read one news article |
+| `ifb_market_summary` | index, turnover, bond indices, boards and top movers |
+| `ifb_yield_curve` | fitted yield curves for government, non-government and treasury bills |
+| `ifb_sukuk_flows` | daily value of Islamic securities bought and sold by investor type |
+| `ifb_market_watch` | live market watch: top gainers, losers and most traded per board, halted symbols |
+| `ifb_index_history` | daily history of the total, equal-weight, price and sukuk indices with 1d/5d/21d/250d changes |
+| `ifb_corporate_actions` | capital increases with rights windows, board transfers, new listings, moves to Tehran Stock Exchange |
+| `ifb_halted` | symbols halted now with date and reason, and issuers flagged for weak disclosure |
+
+## FAQ
+
+**Is it official?** No. It reads the public pages and web service of ifb.ir and is not affiliated with Iran Fara Bourse.
+
+**Why do symbols end in a digit?** The exchange lists each paper on several boards (`کارون0731`, `0732`). Take the `id` from `ifb_yields` or `ifb_search`.
+
+**Is the market watch included?** Not the live ranking grid, which the site fills through a push connection. Quotes come from the site's JSON service.
+
+## فارسی
+
+<div dir="rtl">
+
+**ifb-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای فرابورس ایران (ifb.ir) است. با آن می‌توان اوراق بدهی، صکوک و اسناد خزانه (اخزا) را بر پایهٔ بازده تا سررسید (YTM) مرتب کرد، جزئیات و برنامهٔ پرداخت سود هر ورقه را دید، قیمت و صف خرید و فروش را گرفت، عرضه‌های اولیه و پذیره‌نویسی‌ها را دید، اطلاعیه‌ها و اخبار را جستجو کرد و خلاصهٔ بازار را خواند. کلید API یا حساب لازم نیست. سایت فقط از شبکه‌های ایران پاسخ می‌دهد.
+
+نصب: `claude mcp add ifb -- uvx ifb-mcp`
+
+</div>
+
+## License
+
+MIT

ifb_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "ifb-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Iran Fara Bourse (ifb.ir): bond and sukuk yields, treasury bills, IPOs, announcements, market stats."
+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", "ifb", "fara-bourse", "farabourse", "iran-fara-bourse", "otc", "bonds", "sukuk", "treasury-bills", "ytm", "ipo", "iran", "bourse", "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 :: Office/Business :: Financial :: Investment",
+]
+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/ifb-mcp"
+Issues = "https://github.com/sepehr071/ifb-mcp/issues"
+Website = "https://mcpfarsi.ir/"
+
+[project.scripts]
+ifb-mcp = "ifb_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 ifb.ir 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

ifb_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/ifb-mcp",
+  "title": "Iran Fara Bourse",
+  "description": "Read-only Iran Fara Bourse (ifb.ir): bond, sukuk and treasury yields, IPOs, notices, market stats.",
+  "repository": {
+    "url": "https://github.com/sepehr071/ifb-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/ifb-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "ifb-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "IFB_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for the ifb.ir 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
+        }
+      ]
+    }
+  ]
+}

ifb_mcp-0.1.0/src/ifb_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Iran Fara Bourse (ifb.ir): bond and sukuk yields, IPOs, announcements, market stats."""
+
+from importlib.metadata import version
+
+__version__ = version("ifb-mcp")

ifb_mcp-0.1.0/src/ifb_mcp/grid.py

@@ -0,0 +1,113 @@
+"""Reads ifb.ir's server-rendered tables and pages through its WebForms grids."""
+
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+
+from . import http
+
+CP = "ctl00$ContentPlaceHolder1$"  # prefix of every control name on the pages
+
+
+class Row(list):
+    """The text of each cell; `hrefs` holds the first link of each cell (or None)."""
+
+    hrefs: list[str | None]
+
+
+class Table:
+    def __init__(self, tid: str | None, cls: str | None = None):
+        self.id = tid
+        self.cls = cls or ""
+        self.rows: list[Row] = []
+
+
+class _Parser(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.tables: list[Table] = []
+        self._stack: list[dict] = []
+
+    def handle_starttag(self, tag, attrs):
+        a = dict(attrs)
+        if tag == "table":
+            t = Table(a.get("id"), a.get("class"))
+            self.tables.append(t)
+            self._stack.append({"t": t, "row": None, "cell": None})
+        elif not self._stack:
+            return
+        elif tag == "tr":
+            row = Row()
+            row.hrefs = []
+            self._stack[-1]["row"] = row
+        elif tag in ("td", "th") and self._stack[-1]["row"] is not None:
+            self._stack[-1]["cell"] = {"text": "", "href": None}
+        elif tag == "a" and (c := self._stack[-1]["cell"]) is not None and c["href"] is None and a.get("href"):
+            c["href"] = a["href"]
+        elif tag == "br" and (c := self._stack[-1]["cell"]) is not None:
+            c["text"] += " "
+
+    def handle_endtag(self, tag):
+        if not self._stack:
+            return
+        top = self._stack[-1]
+        if tag in ("td", "th") and top["cell"] is not None and top["row"] is not None:
+            top["row"].append(re.sub(r"\s+", " ", top["cell"]["text"]).strip())
+            top["row"].hrefs.append(top["cell"]["href"])
+            top["cell"] = None
+        elif tag == "tr" and top["row"] is not None:
+            if top["row"]:
+                top["t"].rows.append(top["row"])
+            top["row"] = None
+        elif tag == "table":
+            self._stack.pop()
+
+    def handle_data(self, data):
+        if self._stack and (c := self._stack[-1]["cell"]) is not None:
+            c["text"] += data
+
+
+def tables(html: str) -> list[Table]:
+    p = _Parser()
+    p.feed(html)
+    return p.tables
+
+
+def table(html: str, suffix: str) -> Table | None:
+    """The table whose id ends with `suffix` (e.g. "grdIPOs")."""
+    return next((t for t in tables(html) if t.id and t.id.endswith(suffix)), None)
+
+
+def pairs(html: str) -> dict[str, str]:
+    """Label/value rows of the `insTable` blocks on an instrument page (first value wins)."""
+    out: dict[str, str] = {}
+    for t in tables(html):
+        if t.cls.startswith("insTable"):
+            for r in t.rows:
+                if len(r) == 2 and r[0] and r[0] not in out:
+                    out[r[0]] = r[1]
+    return out
+
+
+def hrefid(href: str | None) -> int | None:
+    """The instrument id in a link like Instruments.aspx?id=123."""
+    m = re.search(r"id=(\d+)", href or "")
+    return int(m.group(1)) if m else None
+
+
+async def grid(path: str, name: str, page: int = 1, form: dict[str, str] | None = None) -> tuple[Table | None, str]:
+    """One page of the WebForms grid control `name` on `path`, after an optional search `form` (control -> value).
+
+    Searches and pager clicks are postbacks that need the page's hidden state, so this is 1 to 3 requests.
+    Returns the table and the final HTML.
+    """
+    html = await http.get_page(path)
+    fields = {k: v for k, v in (form or {}).items()}
+    if fields:
+        html = await http.post_page(path, {**http.hidden_fields(html), **fields})
+    if page > 1:
+        target = {"__EVENTTARGET": f"{CP}{name}", "__EVENTARGUMENT": f"Page${page}"}
+        keep = {k: v for k, v in fields.items() if not k.endswith("BtnSearch")}  # the button would re-run the search
+        html = await http.post_page(path, {**http.hidden_fields(html), **keep, **target})
+    return table(html, name), html