MCP Servers — Making Pakistani Financial Data LLM-Callable

The docstring is the contract. In FastMCP, the function docstring becomes the tool description the model reads when deciding what to call. So every tool in psx-mcp documents its arguments, its return shape and its caveats inline. get_quote states that PSX data is delayed roughly five minutes; screen_dividend_stocks explicitly says it filters by payout percentage of face value, not by true yield, and tells the model to call get_quote per symbol if real yield is needed. That caveat matters because PSX quotes payouts as a percentage of face value, typically Rs 10, so a headline number like 175 percent is not a yield figure at all.

Buy-deadline math lives in one pure module. dividend_calc.py implements subtract_trading_days and buy_deadline, where the deadline is book-closure start minus two trading days, skipping weekends and a holiday set. classify_dividend returns a structured status object with PASSED, URGENT_TODAY, URGENT_TOMORROW, APPROACHING or UPCOMING plus a plain-English message, so the model receives a decision rather than a date it has to reason about.

The Node.js alerter mirrors that math in src/trading-calendar.js and keeps the classifier a pure function with no I/O. Dates are parsed as UTC midnight via Date.UTC so day-of-week arithmetic stays deterministic regardless of the host timezone, which matters when Karachi is UTC+5 and the deployment target might be anywhere. The classifier takes the current date as a parameter and the alerter tick takes an injected clock, which is what lets the tests pin a specific date and assert which alert kind should fire.

Deduplication is a fingerprint, not a diff. In psx-dividend-alert a payout row is keyed as SYMBOL@bcFrom, and the persisted state records which alert kinds have already been sent for that fingerprint. A row can therefore progress NEW to UPCOMING to URGENT to PASSED across polls without ever firing the same kind twice, even though the scraper re-reads the whole table on every tick.

opportunity-mcp separates adapters from the query engine. An adapter knows one site and yields Pydantic Opportunity objects; the index knows nothing about sites and only searches normalised rows. The SQLite schema uses an FTS5 virtual table with porter unicode61 tokenisation kept in sync by insert, update and delete triggers, so search stays consistent without application-level bookkeeping.

Politeness is enforced in code, not in a policy document. The adapter base class fetches robots.txt with httpx under an identifying User-Agent that carries the project URL, then parses it with urllib.robotparser. It deliberately does not use RobotFileParser.read, because Python's default urllib User-Agent gets 403'd by Cloudflare-protected sites and the parser reads that as disallow-all, a false negative that would silently kill working sources.

Refresh happens in CI, never on user query. A GitHub Actions cron runs every six hours, rebuilds the SQLite index and publishes it as a release artifact tagged index-N. The MCP server itself only reads a local database, which keeps tool calls fast and keeps source sites from being hit once per user question.

Transport is a flag, not a rewrite. psx-mcp's entrypoint accepts --transport stdio, http or sse, mapping http to streamable HTTP with configurable host and port. Claude Desktop and Cursor get stdio; a hosted agent gets an HTTP endpoint from the same code path.