Skip to main content
Glama
pse-edge-mcp
by phdwight

pse-edge-mcp

CI Release PyPI Python 3.14 License: MIT

An MCP server exposing Philippine Stock Exchange data from the PSE Edge portal — quotes, price history, disclosures, financial reports, and market data — plus Bangko Sentral ng Pilipinas (central bank) key rates, to Claude and any other MCP client.

Unofficial. PSE Edge and BSP have no public API; this project speaks to the same endpoints their own pages use. It is not affiliated with or endorsed by the PSE or the BSP. Data is provided as-is for personal/research use, with no warranty.

Contents

Related MCP server: stockbit-mcp

Features

  • 15 read tools + 1 action tool covering quotes, price history, disclosures (metadata, full-text, and detail), company profiles, financials, dividends, indices, market summary, and BSP (central bank) key rates — plus an attachment resource, two prompts with symbol completion, and tool annotations.

  • Deliberately gentle on PSE Edge: every unique query hits it at most once per day, and prices follow a strict market-boundary freeze.

  • OAuth 2.1 + passkeys for humans (no passwords anywhere), client_credentials for headless agents — both opt-in; stdio needs nothing.

  • Postgres optional: zero-config in-memory for local stdio, or a shared cache + an ever-deepening EOD archive when DATABASE_URL is set.

  • Loud on drift: a nightly canary validates live pages against the real models and alerts only on failure; a restyled page raises an error, never partial data.

  • Multi-arch container image (amd64 + arm64), gated on necessity — the image contains exactly the runtime dependency closure and nothing else.

Quick start

Claude Desktop / Claude Code (stdio):

uvx pse-edge-mcp
{
  "mcpServers": {
    "pse-edge": { "command": "uvx", "args": ["pse-edge-mcp"] }
  }
}

A hosted deployment (auth on) is a normal OAuth 2.1 protected resource — modern clients need only the URL and drive the whole flow themselves (details below):

{
  "mcpServers": {
    "pse-edge": { "url": "https://your-host.example.com/mcp" }
  }
}

Docker (HTTP + Postgres):

cp .env.example .env   # set POSTGRES_PASSWORD
docker compose up --build

Design: end-of-day prices, fetch-once everything else

Four layers, one direction of dependency. Every read goes through FreezeService.get() with an explicit per-domain policy — no tool ever touches the HTTP client directly. ★ marks the invariant the whole design exists to protect, and it guards prices only.

flowchart TD
    C["MCP client"] -- "tool call" --> S["<b>server.py</b> · MCP boundary<br/>validate args · delegate · shape reply"]
    S --> R["<b>repositories.py</b> · one per domain<br/>cache key · freeze read · parse · endpoint routing"]
    R --> F["<b>service.py</b> · FreezeService ★<br/>3 policies · miss → fetch once"]
    F --> P["<b>client.py</b> · PseEdgeClient<br/>throttled HTTPS · single-flight · 2 dialects"]
    P --> E["PSE Edge<br/>edge.pse.com.ph"]

★ Market-boundary freeze — prices only. A cached stock price is never refetched while the market is open (09:30–15:00 Asia/Manila, trading days) — the last close answers, flagged stale. A price nobody has ever asked for is the one exception: fetched once mid-session and served as identity + previous_close only (every session-moving field withheld), with stale: true plus a meta.note saying it is not a realtime value; the settled figures replace it after the close.

Policy

Applies to

Behaviour

EOD-frozen ★

get_stock_quote, get_price_history

A cached price is never refetched during a session; a never-cached key is fetched once and surfaces only previous_close, labelled not-realtime for the whole session. Also the default policy, so an unlabelled read can only over-protect PSE Edge.

daily-refresh

Companies, disclosures, profiles, financials, dividends, indices, summary, BSP rates

First ask fetches at any hour — once, deduplicated across concurrent callers; every repeat of the same query answers from storage until the next 15:00 close.

immutable

Disclosure detail by edge_no, attachment bytes

The object never changes upstream. Fetched once ever; valid_until: null.

If PSE Edge is unreachable and an expired entry exists, tools serve it flagged meta.stale: true rather than discarding real data for an error. EDGE_UNAVAILABLE means unreachable and nothing cached.

Every data tool returns the same envelope — meta is the freshness contract:

{
  "data": { /* …StockQuote… */ },
  "meta": {
    "as_of":       "2026-08-06T15:00:00+08:00",  // ISO-8601, Asia/Manila
    "valid_until": "2026-08-07T15:00:00+08:00",  // null when immutable
    "from_cache":  false,
    "stale":       false,                        // true = not a settled EOD value
    "data_policy": "EOD-frozen",                 // "daily-refresh" / "immutable" elsewhere
    "note":        null                          // freshness caveat, e.g. "not a realtime value"
  }
}

Tools, resources, prompts

Tool

Description

search_companies(query)

Find PSE-listed companies by name or ticker

validate_symbol(symbol)

Cheap yes/no check that a ticker exists, with its company name and id

get_stock_quote(symbol)

Latest EOD quote: price, change, 52-wk range, market cap, full field set

get_price_history(symbol, start_date?, end_date?)

Daily OHLC series from Edge's chart endpoint

search_disclosures(symbol?, start_date?, end_date?, template?, page?)

Disclosure metadata, market-wide or per company; 50/page with exact totals

search_disclosure_fulltext(keyword, ...)

Search the text inside disclosure attachments, with snippets

get_disclosure(edge_no, max_files?)

One disclosure's details plus attachment and body-HTML links; attachments capped at max_files (default 20) with an honest truncation flag. Each attachment carries a resource_uri — read the file's bytes via MCP resources/read (pse-edge://attachment/<file_id>, cached immutably, 10 MB cap)

get_company_profile(symbol)

Sector, incorporation, auditor, transfer agent, contacts

get_financial_highlights(symbol)

Annual + quarterly balance sheet and income statement

get_dividends_and_rights(symbol)

Declared dividends and stock rights, linked to their disclosures

get_indices()

PSEi and the 7 sector indices, with signed daily change

get_market_summary()

Index levels plus PSE Edge's homepage disclosure feeds

get_bsp_key_rates()

The Bangko Sentral ng Pilipinas (central bank) Key Rates dashboard: policy, facility and auction rates, headline inflation, and the USD peso reference

get_bsp_policy_rate()

The BSP policy rate (Target RRP) and the overnight lending/deposit corridor around it

get_server_version()

The deployed version of this MCP server itself (matches /health)

send_email(subject, body)

Email yourself a note (auth-enabled deployments only)

Beyond tools, the server exposes the attachment resource above, two prompts (market_recap, company_briefing(symbol) — the symbol argument autocompletes from PSE Edge's own lookup), and MCP tool annotations so hosts can auto-approve the read-only tools. It is described for the MCP Registry in server.json.

send_email is the only tool that acts rather than reads. It has no recipient argument: the message always goes to the account that authenticated the session, so it cannot be used as a relay and there is nothing for prompt injection to redirect — which matters because this server returns disclosure text the operator does not control. It appears only on deployments with auth enabled (there is no verified address otherwise), the body is escaped rather than rendered as HTML, and it is capped at 20 messages per user per day.

Disclosure tools return metadata and links only — this server never downloads or parses attachments (beyond the explicit resource read), so your MCP client can fetch the returned URLs itself if it needs the files. Note that Edge's own full-text index is partial (roughly 2023–2025 at last check), so search_disclosure_fulltext is not a substitute for search_disclosures; it reports this limit in its results.

Financial figures are returned exactly as PSE Edge prints them and are never rescaled — Edge's own units labels are inconsistent between its annual and quarterly sections, so each period reports its currency_units for you to check. Index changes are signed here even though Edge prints them unsigned (it shows direction only as a colour and an arrow).

Architecture

The layers

Layer

Owns

Never

server.py — MCP boundary

Argument validation, delegation, reply shaping. Error mapping happens once in reply(); action tools go through act() (no freshness meta).

Domain logic, cache keys, parsing, endpoint choices

repositories.py — domain layer

One repository per data domain: the cache key, the freeze read, the parse, the Pydantic model. Endpoint routing lives here.

Depending on the concrete client — only on the protocols below

service.py / sources.py — policy & seams

FreezeService enforces the per-read policy and wraps every result in Served[T] (value + as_of, valid_until, from_cache, stale). sources.py declares the five narrow per-domain source protocols; FrozenCache is the cache seam.

—

client.py / parsers.py — edge of the world

Pure HTTP, MCP-agnostic: token-bucket throttle, single-flight, retries; two request dialects (JSON-body POST for chart .ax endpoints, form-encoded POST returning HTML fragments for search.ax). Parsers turn HTML/JSON into dicts; any shape drift raises EndpointChangedError — loud, never partial.

—

Core class map

Five repositories cover the whole tool surface. Each consumes a narrow source protocol — the concrete client satisfies all five, but no repository knows that, so each is testable with a few-line fake and no HTTP mocking.

Repository

Methods → models

Consumes

Policy / note

CompanyRepository

search, resolve, try_resolve → CompanyHit

CompanySource

daily-refresh · resolves symbol → company_id for every other repo

QuoteRepository

quote → StockQuote · history → PriceHistory

QuoteSource

EOD-frozen ★ — the only market-gated domain · bars archived

DisclosureRepository

search, fulltext, detail, attachment

DisclosureSource

searches daily-refresh; detail/attachment immutable

CompanyInfoRepository

profile, financials, dividends_and_rights

CompanyInfoSource

daily-refresh · financial units passed through verbatim

MarketRepository

indices, summary

MarketSource

daily-refresh · index signs derived from Edge's ▲/▼ glyph

NotificationService (action)

send(user, subject, body) → SentEmail

—

recipient comes from the bearer token, never an argument

Protocols and swappable implementations

One switch picks the column: DATABASE_URL unset → in-memory / Null; set → Postgres. Postgres modules import lazily, so a lean install never pays for them.

Protocol

DATABASE_URL unset

DATABASE_URL set

Storage

InMemoryStorage

PostgresStorage

Archive

NullArchive

PostgresArchive

UsageSink

NullUsageRecorder

PostgresUsageSink

AuthStore

—

PostgresAuthStore

EmailSender

ConsoleEmailSender

ZeptoMailSender (when ZEPTOMAIL_API_KEY is set)

HTTP composition — built once, in asgi.py

flowchart LR
    H["HealthApp<br/>/health · /health/ready"] --> A["AuthApp<br/>/oauth/* · signup · /account · /privacy"]
    A --> M["AuthMiddleware<br/>bearer validation · quotas · usage"]
    M --> MCP["MCP app<br/>the tool surface"]

/health is liveness and never touches the database; /health/ready is readiness. Behind AuthApp: OAuthService (DCR · PKCE-only · refresh families), PasskeyService (WebAuthn + web sessions), TokenService (opaque pse_ tokens, SHA-256 at rest).

Error family — one root, mapped once in reply()

Error

Meaning

SymbolNotFoundError

SYMBOL_NOT_FOUND

InvalidArgumentError

INVALID_ARGUMENT — bad input, caught at the boundary

EndpointChangedError

Edge redesigned a page — loud, never partial

EdgeUnavailableError

Upstream unreachable and nothing cached

MarketOpenNoCacheError

Retained for client compatibility; no longer raised

ActionUnavailableError

Action tool needs auth enabled

ActionRateLimitedError

20 emails / user / day

Watchdog

A nightly canary (pse-edge-canary, plus a compose service) fetches live pages bypassing the cache and validates the same Pydantic models the repositories build — a 200 with a restyled table is exactly the failure it exists to catch. It still refuses to run while the market is open (the ★ invariant outranks it), emails PSE_OPERATOR_EMAIL only on failure, and exits non-zero so cron notices.

Golden path: one request traced

get_stock_quote("SM") after market close, cold cache:

  1. server.py — validation.py checks the symbol shape (bad input → INVALID_ARGUMENT), then reply() wraps the repository call — the only place errors become MCP error payloads.

  2. QuoteRepository.quote("SM") — resolves SM → company_id through CompanyRepository, picks the endpoint, builds the cache key. Tools never see any of this.

  3. FreezeService.get(key, fetch, policy="EOD-frozen") ★ — fresh cache entry → serve it. Market open + cached → serve the last close flagged stale, never refetch. Market open + never cached → fetch once, label stale: true + note for the whole session. Market closed + miss → fetch. Fetch fails but an expired entry exists → serve it flagged stale.

  4. PseEdgeClient.fetch_stock_data_page(company_id) — token bucket (1 req/s), single-flight dedupe, retries. Wire dates are MM-dd-yyyy; the JSON-vs-form dialect is chosen per endpoint.

  5. parsers.py → StockQuote — HTML → dict → validated Pydantic model. Any drift in Edge's markup raises EndpointChangedError.

  6. cache.py / archive.py — the entry freezes until the next 15:00 close; daily bars archive opportunistically (a dead database never fails a read).

Connecting to a hosted server

A deployment with auth on is a normal OAuth 2.1 protected resource, so a modern MCP client needs only the URL — it discovers everything else and drives the whole flow itself.

What happens on first connect

Nothing here is manual except the two browser steps in bold.

  1. The client POSTs to /mcp with no token and gets 401 carrying WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource". That header is the entire bootstrap: it tells the client where to look next.

  2. It fetches that document, learns which authorization server guards this resource, then reads /.well-known/oauth-authorization-server for the endpoints.

  3. It registers itself at /oauth/register (RFC 7591) — no client secret, no operator involvement, no pre-shared credentials. It gets back a client_id.

  4. It opens /oauth/authorize in a browser with a PKCE challenge (S256 required).

  5. The user signs up or signs in. New users land on /signup, agree to the (deliberately tiny) data policy, give an email, and receive a link; the link shows a confirm page whose button enrolls a passkey at /enroll — the confirm step exists so a mail scanner's prefetch cannot spend the link. Returning users hit /login and use the passkey they already have. No password exists anywhere in the system.

  6. The user approves the client on a consent screen naming it.

  7. The browser returns to the client with a single-use code; the client exchanges it at /oauth/token with its PKCE verifier and receives an access token (15 min) and a single-use refresh token (24 h).

  8. The client calls /mcp with Authorization: Bearer … and refreshes silently from then on. The user is not asked again.

client ──POST /mcp──────────────▶ 401 + WWW-Authenticate
       ──GET  /.well-known/… ───▶ metadata
       ──POST /oauth/register ──▶ client_id
       ──GET  /oauth/authorize ─▶ browser: signup/login → passkey → consent
       ◀─────────────────────────  ?code=…
       ──POST /oauth/token ─────▶ access (15 min) + refresh (24 h)
       ──POST /mcp + Bearer ────▶ tools

Refresh tokens rotate on every use, and replaying a rotated one revokes that whole session family (RFC 9700 §4.14) — a stolen refresh token gets one use before the theft is detected and the session dies.

Headless agents (client_credentials)

For a LangGraph app, the Anthropic Messages API MCP connector, or any agent that cannot open a browser. No redirect, no passkey, no consent screen — a client id and secret.

1. Provision. Two routes, same result:

  • From the web (needs no shell — the practical choice on a NAS): set PSE_ADMIN_EMAILS to your account's email, sign in, and a Machine clients panel appears on /account with create and revoke controls. Access is gated to that allowlist — a normal signup never sees it.

  • From the CLI: pse-edge-admin create-machine-client --name langgraph-app.

Either way client_id and client_secret are shown once. Only the secret's SHA-256 is stored, so it cannot be recovered — only revoked and reissued (from the same account page, or pse-edge-admin revoke-machine-client <client_id>).

2. Mint a token:

curl -s -X POST https://pse.sakayandgo.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET \
  -d scope=mcp -d resource=https://pse.sakayandgo.com/mcp
{"access_token": "pse_…", "token_type": "Bearer", "expires_in": 3600, "scope": "mcp"}

HTTP Basic works too (curl -u "$CLIENT_ID:$CLIENT_SECRET"), which is what most SDKs send. No refresh token is issued — the client already holds a long-lived secret and simply re-requests when the hour is up.

3. Use it:

curl -s -X POST https://pse.sakayandgo.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Revoke with pse-edge-admin revoke-machine-client <client_id>, which kills the secret, every token it minted, and the backing service account in one step.

Registering does not grant this. /oauth/register is open to the internet, so a client that registers itself — even declaring grant_types: ["client_credentials"] and sending a secret — is refused with unauthorized_client. Authorization comes from a client_type column only the admin CLI writes, never from anything a registrant says about itself.

Give each agent its own machine client: quotas are per client, so a runaway job throttles itself, and revoking one does not touch the others.

Building an app on top of this? examples/langgraph_client.py is a working client for the multi-tenant case — your app authenticates as itself with one machine client, your users never see this server. It carries an httpx.Auth that mints and refreshes the 1-hour token (verified: concurrent calls mint once; a stale token recovers on 401), plus the agent instructions worth pasting into a system prompt. Note it needs mcp<2 — langchain-mcp-adapters does not yet import against the 2.x SDK.

If your client does not do OAuth yet

The operator issues a token directly, and the user pastes it into a header. Same server, no browser:

pse-edge-admin create-user you@example.com
pse-edge-admin issue-token you@example.com --note laptop   # plaintext shown once
curl -X POST https://your-host.example.com/mcp \
  -H "Authorization: Bearer pse_..." \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

This is also the only route on a LAN-only deployment: passkeys need a secure context, so plain http cannot enroll one.

What a user can see and remove

/account shows everything held about them — email, passkeys, active tokens, hourly usage counts. POST /account/delete erases it immediately and completely, with no approval step. /privacy states what is collected and for how long. Usage counts are deleted after 90 days.

Run with Docker Compose (HTTP + Postgres)

cp .env.example .env   # set POSTGRES_PASSWORD
docker compose up --build

Serves streamable HTTP on :8000, with Postgres 18 as shared cache and archive. A one-shot migrate service applies the Alembic schema before the app starts.

HTTP mode is stateless with plain JSON responses by default. This server is read-only tools over data the freeze policy holds still, and it uses none of the features MCP sessions exist to enable — no notifications, no resource subscriptions, no sampling, no elicitation, no progress — so every request is self-contained. That means any replica can serve any request behind plain round-robin: no sticky routing, no per-session memory, no event store. Without SSE, idle clients hold no connection either. Use --stateful if you need MCP sessions and --sse for event-stream framing; they are independent flags.

Bearer auth and quotas (opt-in)

Set PSE_AUTH_REQUIRED=1 (needs DATABASE_URL) and every HTTP request must carry Authorization: Bearer <token>. Users arrive either way described in Connecting to a hosted server — self-service through OAuth 2.1 and passkeys, or an operator-issued token. PKCE is mandatory (S256 only) and no password exists anywhere in the system.

Tokens are opaque and stored only as SHA-256 hashes. Revocation (pse-edge-admin revoke-token … / disable-user …) takes effect within the validation cache's TTL — 60 s by default, which is precisely the revocation-latency budget. Per-user quotas (default 60/min, 2,000/day, overridable per user) are counted in-process and answer HTTP 429 with Retry-After; with N replicas the effective ceiling is up to N× nominal, which is fine for abuse prevention. stdio mode never authenticates — it runs on your own machine.

Operators get pse-edge-admin delete-user and purge-usage (cron the latter daily), and delete-user uses the same erasure code path as the user's own delete button, so the two cannot drift apart.

Postgres is optional. Without DATABASE_URL the server uses an in-memory cache and keeps no archive — the zero-config path for local stdio use. With it set, replicas share one cache (the freeze still means one upstream fetch per boundary however many processes run), and every read accumulates into an EOD archive (daily bars and disclosures) that deepens over time at zero extra cost to PSE Edge. Nothing crawls — the archive fills solely from fetches you already made.

# applying the schema by hand, outside compose
DATABASE_URL=postgresql+asyncpg://user:pass@host/db uv run alembic upgrade head

Configuration

Everything is environment-sourced into one frozen Settings object. Two variables change the shape of the system: DATABASE_URL picks the storage column, and PSE_AUTH_REQUIRED turns on the whole auth stack (and the send_email tool with it).

Variable

Default

What it governs

Upstream — protect PSE Edge

PSE_EDGE_BASE_URL

https://edge.pse.com.ph

Upstream portal root

PSE_THROTTLE_RPS / PSE_THROTTLE_BURST

1.0 / 2

Token-bucket rate toward Edge

PSE_TIMEOUT_SEC / PSE_RETRY_ATTEMPTS

20 / 3

Per-request timeout and retries

Storage — the one switch

DATABASE_URL

unset

Unset → in-memory cache + NullArchive. Set → shared Postgres cache + archive + auth tables (schema via Alembic only)

PSE_DB_POOL_SIZE / PSE_DB_MAX_OVERFLOW

5 / 10

Connection pool

Auth — opt-in, needs DATABASE_URL

PSE_AUTH_REQUIRED

0

Bearer auth + quotas + OAuth/passkeys; stdio never authenticates

PSE_TOKEN_CACHE_TTL

60

The revocation-latency budget — nothing else

PSE_QUOTA_PER_MIN / PSE_QUOTA_PER_DAY

60 / 2000

Per-user quotas, counted in-process (per worker)

PSE_PUBLIC_URL

http://localhost:8000

Real external https URL — drives WebAuthn rp_id, email links, OAuth issuer; a wrong value breaks passkeys

PSE_ACCESS_TTL_MIN / PSE_REFRESH_TTL_HOURS

15 / 24

Token lifetimes; the refresh token is single-use and reuse revokes the family. PSE_REFRESH_UNUSED_TTL_HOURS (24) caps a family that never rotated

PSE_ADMIN_EMAILS

empty

Operator allowlist for the /account machine-client panel; never derived from user input

Email & operations

ZEPTOMAIL_API_KEY

unset

Unset → ConsoleEmailSender; set → ZeptoMail

PSE_EMAIL_FROM

no-reply@localhost

Sender address (ZeptoMail verifies exact domains)

PSE_OPERATOR_EMAIL

unset

Canary failure alerts — failures only, never "all fine"

PSE_USAGE_RETENTION_DAYS

90

Usage log retention (aggregated per user-hour, never per request)

Server

PSE_STATEFUL / PSE_SSE

0 / 0

MCP session & response mode

PSE_LOG_JSON / PSE_LOG_LEVEL

0 / INFO

Both formatters timestamp and redact; INFO logs refusals only

Container image

Every merge to main publishes an image:

docker pull ghcr.io/phdwight/pse-edge-mcp:latest      # or :<version>, :sha-<sha>
# multi-arch: linux/amd64 and linux/arm64
docker run --rm -p 8000:8000 ghcr.io/phdwight/pse-edge-mcp:latest   # streamable HTTP
docker run --rm -i --entrypoint pse-edge-mcp ghcr.io/phdwight/pse-edge-mcp:latest  # stdio

Both architectures are gated before publishing, on native runners. The rule is necessity, not size: the image must contain exactly the resolved runtime dependency closure and nothing else — no build toolchain, no package manager, no dev dependencies, no bytecode caches, no source tree — plus a secret scan and a smoke test that the server starts and registers its tools. A stray dependency fails the build; a large but genuinely required one does not. Image size is reported for information and never gated.

Production

One file, compose.nas.yaml, for a NAS or any single Docker host, in two stages. It pulls the published image rather than building, so production runs the artifact CI gated. Stage 1 is LAN-only and needs nothing from Cloudflare:

docker compose -f compose.nas.yaml up -d                     # http://<nas-ip>:8200
docker compose -f compose.nas.yaml --profile tunnel up -d    # + public hostname

The tunnel profile starts cloudflared, which dials out — so there is no port forwarding, no ACME, and nothing for CGNAT to break; Cloudflare terminates TLS at its edge. Set CLOUDFLARE_TUNNEL_TOKEN, PSE_PUBLIC_URL and PSE_LAN_BIND=127.0.0.1 in .env alongside it — the last moves the stage 1 LAN port onto loopback, which is the only way to unpublish it, because Compose merges ports additively.

Both stages give auth on by default, daily backups, a daily retention purge, and no published database port. Health probes are /health (liveness) and /health/ready (readiness). The app is importable for other servers: uvicorn pse_edge_mcp.asgi:app --workers 4.

See docs/deploy.md for the full guide, including the two settings most worth getting right: pin PSE_IMAGE_TAG rather than tracking :latest, and make PSE_PUBLIC_URL the real external https URL, because WebAuthn binds every passkey to the origin it was enrolled under.

Development

uv sync --all-extras
uv run pytest
uv run ruff check .

Tests run entirely against recorded fixtures — CI never touches PSE Edge.

New to the codebase? docs/walkthrough.md is the developer and architect walkthrough: the request lifecycle, the freeze policy, the layering, how to add a tool or a whole data domain, and a symptom-to-cause debugging table. Also available as a PDF. For the one-page visual version of the Architecture section — classes, protocols, the data path, the config matrix — open docs/reference-card.html in any browser; it is fully self-contained and works offline. Every design decision is recorded in docs/plan.md, and the verified endpoint map lives in docs/endpoints.md.

Contributing

Issues and pull requests are welcome. The ground rules:

  • Work lands on develop and reaches main by pull request; main is protected and requires all three CI checks (test, image (amd64), image (arm64)).

  • Tests never touch PSE Edge — new endpoints need new recorded fixtures in tests/fixtures/.

  • New tools follow the layering above: a new data domain is a new repository plus thin tools, never fetch/parse logic in server.py.

  • Bumping version in pyproject.toml makes the next merge cut a GitHub Release with a matching immutable image tag; roll CHANGELOG.md in the same PR.

License

MIT


MCP Registry identity: mcp-name: io.github.phdwight/pse-edge-mcp

Available Tools

15 tools
get_bsp_key_ratesBSP key ratesA
Read-only
Inspect

Get the Bangko Sentral ng Pilipinas (BSP) Key Rates dashboard.

Returns every rate BSP publishes on its Key Rates page: the Target RRP (policy) rate, the overnight lending and deposit facility rates, BSP-securities and term-deposit (TDF) weighted-average interest rates, headline inflation, and the USD peso reference level. Each rate carries its own BSP published_date (which varies by row and is NOT when we fetched — see meta.as_of) and a source_url to BSP's detail page. rate_percent is the numeric value for percentage rates; it is null for the peso FX level and for the discontinued ON Reference Rate ('****').

BSP rates change infrequently, so this is fetched at most once per day and served from cache otherwise (meta.as_of says when). For just the monetary-policy stance, use get_bsp_policy_rate instead.

Inputs: no named parameters. Returns: object

get_bsp_policy_rateBSP policy rateA
Read-only
Inspect

Get the BSP policy rate and the interest-rate corridor around it.

A focused view for "what is the BSP policy rate?": policy_rate_percent is the Target RRP rate, bounded by lending_rate_percent (the corridor ceiling, the overnight lending rate) and deposit_rate_percent (the floor, the overnight deposit rate). published_date is BSP's date for the policy figure, and corridor holds the three underlying rates with their source links. Cached daily like get_bsp_key_rates — check meta.as_of for when it was fetched.

Inputs: no named parameters. Returns: object

get_company_profileCompany profileA
Read-only
Inspect

Get a PSE-listed company's profile: sector, incorporation, auditor, contacts.

Includes sector and subsector, incorporation date, corporate life, number of directors, fiscal year end, stockholders' meeting schedule, external auditor, transfer agent, business address, phone, fax, email and website. Every label on the page is also returned verbatim in raw_fields.

Inputs: symbol (required). Returns: object

get_disclosureDisclosure detailA
Read-only
Inspect

Get one disclosure's details and attachment links by its edge_no.

edge_no is the 32-character hex id returned by search_disclosures. Returns the company, template, date, related documents, and URLs for each attachment plus the rendered body HTML. To read a file's contents, use the attachment's resource_uri (pse-edge://attachment/<file_id>) via resources/read — the tools themselves stay metadata-only; download_url remains for callers that can fetch URLs directly.

At most max_files attachments are returned (default 20, max 100). attachments_total always reports how many exist; if attachments_truncated is true, call again with a higher max_files — the disclosure is cached, so the repeat costs nothing upstream.

A published disclosure never changes, so these results are cached permanently (meta.data_policy is "immutable").

Inputs: edge_no (required), max_files. Returns: object

get_dividends_and_rightsDividends & rightsA
Read-only
Inspect

Get a company's declared dividends and stock rights offers.

Dividends carry the security and dividend type, the rate as printed, and the ex-dividend, record and payment dates. Rights carry the entitlement ratio, offer price, ex-rights date and offer period. Each record includes the edge_no of the disclosure that announced it, so you can pass it to get_disclosure for the notice itself. Empty lists mean Edge lists none for this company.

Inputs: symbol (required). Returns: object

get_financial_highlightsFinancial highlightsA
Read-only
Inspect

Get the financial highlights PSE Edge publishes for a company.

Returns an annual and a quarterly section, each with a balance sheet and an income statement, using Edge's own line-item labels and column headings (annual compares Current/Previous Year; quarterly compares Period Ended against the audited fiscal year, and its income statement has four columns including year-to-date).

IMPORTANT — units: figures are returned exactly as Edge prints them and are never rescaled. Each period carries its own currency_units label, and the two sections disagree in practice (observed: annual "Php (in thousands)" while quarterly said "Php (in Millions)" for the same company, with the same figure appearing in both). Read currency_units before quoting any number, and say the scale is uncertain rather than presenting these as exact peso amounts. Only the highlights Edge serves as data are here — this server does not parse filed PDF statements.

Inputs: symbol (required). Returns: object

get_indicesMarket indicesA
Read-only
Inspect

Get PSEi and the PSE sector index levels with their daily change.

Covers PSEi, All Shares, Financials, Industrial, Holding Firms, Property, Services and Mining and Oil. change and change_percent are signed, and direction is "up"/"down"/"flat" — PSE Edge prints these unsigned and shows direction only as a colour and an arrow, so the signs here are derived from that. Fetched at most once per boundary window and served from storage until the next 15:00 Manila close — meta.as_of says when the snapshot was taken.

Inputs: no named parameters. Returns: object

get_market_summaryMarket summaryA
Read-only
Inspect

Get a market-wide snapshot: index levels plus PSE Edge's homepage feeds.

feeds is keyed by Edge's own group labels — Company Announcements, Financial Reports, Other Reports, Listing Notices, Disclosure Notices, and the most-viewed disclosures for Today and This Week. Each entry carries its symbol, timestamp, circular number and edge_no for get_disclosure.

Note: PSE Edge publishes no gainers/losers/most-active data anywhere, so this cannot include them — say so rather than implying the data is missing or stale.

Inputs: no named parameters. Returns: object

get_price_historyPrice history (OHLC)A
Read-only
Inspect

Get daily OHLC price history for a PSE stock symbol.

Dates are ISO format (YYYY-MM-DD). Defaults to the last ~6 months. Data comes from PSE Edge's own chart endpoint and is EOD-frozen. If the market is open and this exact range has never been cached, a one-time fetch may include today's still-moving bar, flagged stale=true with an explanatory meta.note.

Inputs: symbol (required), end_date, start_date. Returns: object

get_server_versionServer versionA
Read-only
Inspect

Get the deployed version of this MCP server (pse-edge-mcp).

Reports the running server's own release version — the same value the /health endpoint and serverInfo carry — not PSE Edge data. There is no meta block: meta is a data-freshness contract, and a version has no as_of or valid_until.

Inputs: no named parameters. Returns: object

get_stock_quoteStock quote (EOD)A
Read-only
Inspect

Get the latest end-of-day quote for a PSE stock symbol (e.g. SM, AREIT, BDO).

Includes price, change, 52-week range, market cap, shares, and the full set of fields PSE Edge publishes. Data is EOD-frozen (see meta). If the market is open and this symbol has never been cached, a one-time fetch serves identity plus previous_close ONLY (the last settled price before the session — every other field is null), flagged stale=true with a meta.note saying the value is not realtime — relay that caveat when presenting the price.

Inputs: symbol (required). Returns: object

search_companiesSearch companiesA
Read-only
Inspect

Search PSE-listed companies by name or ticker symbol.

Returns matches with company_id, name, symbol. Use the symbol with the other tools.

Inputs: query (required). Returns: object

search_disclosure_fulltextFull-text disclosure searchA
Read-only
Inspect

Full-text search inside disclosure attachments, returning matching snippets.

Use this to find wording within filings ("share buyback", "force majeure"). For "what did company X disclose recently", use search_disclosures instead.

IMPORTANT: PSE Edge's own full-text index is partial and lags behind — at last verification it covered roughly 2023-2025 and held nothing from 2026. Results are relevance-ordered (not chronological), 10 per page. The result includes a coverage_note; relay that limitation rather than reporting "no disclosures exist".

Inputs: keyword (required), page, symbol, end_date, +2 more. Returns: object

search_disclosuresSearch disclosuresA
Read-only
Inspect

Search PSE company disclosures (announcements, material information, notices).

Returns disclosure metadata — pass a hit's edge_no to get_disclosure for attachment links. 50 results per page; the result reports total/pages/has_more so you can request the next page directly.

  • symbol only: that company's full disclosure history, newest first.

  • date range (ISO YYYY-MM-DD): all companies' disclosures in that window, or one company's if symbol is also given. Defaults to the last 30 days when neither symbol nor dates are supplied.

  • template: filter by disclosure type as free text, e.g. "Press Release", "Cash Dividend", "Material Information".

A given search hits PSE Edge once and is then served from storage until the next 15:00 Manila close, so a disclosure filed today appears when its query is first asked — or after the close if that query was already cached (see meta).

Inputs: page, symbol, end_date, template, +1 more. Returns: object

validate_symbolValidate ticker symbolA
Read-only
Inspect

Check whether a ticker symbol is a real PSE-listed company. Cheap.

Use this — NOT search_companies — when you only need to know whether a symbol is valid before calling another tool, or to confirm a symbol a user typed. Returns valid true/false plus the company name and id when it exists, instead of the ranked list of near-matches search_companies returns.

Matching is exact and case-insensitive: "areit" and "AREIT" both resolve, while "ARE" does not match "AREIT". An unknown symbol is valid: false with null fields, not an error.

Cached after the first lookup and refreshed daily (see meta).

Inputs: symbol (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (quotes vs. history vs. profile vs. financials), and the descriptions explicitly disambiguate the tricky pairs: key_rates vs. policy_rate, search_companies vs. validate_symbol, and search_disclosures vs. search_disclosure_fulltext. Minor residual overlap exists between get_indices and get_market_summary (both return index levels), but descriptions steer usage.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun pattern (get_*, search_*, validate_*), e.g. get_stock_quote, get_price_history, search_disclosures, validate_symbol. No camelCase mixing or erratic verb styles; the convention is predictable throughout.

    Tool Count5/5

    15 tools is well within the ideal 3-15 range and each tool covers a distinct slice of the PSE data domain (rates, quotes, history, dividends, indices, disclosures, profiles, financials). Nothing appears redundant or padding.

    Completeness4/5

    The surface covers a strong breadth of the domain: identity/search, quotes, OHLC history, dividends/rights, indices, market snapshot, disclosures (metadata + full-text + detail), profiles, financials, and BSP rates. Gaps like level-2 data, historical index series, or gainers/losers exist but some are unavailable at source, so agents can work around them.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Read-only MCP server for Stockbit (IDX market data) providing broker summary/bandarmology, quotes, top movers, orderbook, fundamentals, and sentiment using your own session. Unofficial and does not place orders.
      41
      109 npm
      60
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides tools to scrape and access Pakistan Stock Exchange (PSX) market data, including market data, intraday, historical, sector, gainers/losers, OHLCV, and volume analysis. Supports both local stdio and remote HTTP deployments with API key authentication.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides remote access to Pakistan Stock Exchange data through MCP tools for quotes, market snapshots, symbols, historical and intraday data, announcements, and payouts.
      -