pse-edge-mcp

An MCP server exposing Philippine Stock Exchange data from the PSE Edge portal — quotes, price history, disclosures, financial reports, and market data — to Claude and any other MCP client.

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

Contents

• Features
• Quick start
• Design: end-of-day prices, fetch-once everything else
• Tools, resources, prompts
• Architecture
• Golden path: one request traced
• Connecting to a hosted server
• Run with Docker Compose
• Configuration
• Container image
• Production
• Development
• Contributing
• License

Features

• 13 read tools + 1 action tool covering quotes, price history, disclosures (metadata, full-text, and detail), company profiles, financials, dividends, indices, and market summary — 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.

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

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

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.

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.

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()

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

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}