ATLAS Explain

io.github.MISHHF93Published by GitHub account MISHHF93v1.4.0Updated Nov 16, 2026

Market jargon in plain language: terms, official figures, crypto prices and charts, headlines.

The publisher's own server: Red Atlas Api

VerifiedStreamable HTTPWeb executableFinance

Overview

ATLAS Explain's hosted MCP server (atlas-explain-mcp.atlas-explain.workers.dev); no sign-in required; Streamable HTTP; 7 tools.

No AI overview yet: these facts come from the registry entry and the server itself.

Endpoint
atlas-explain-mcp.atlas-explain.workers.dev
Last checked

Installation

In SourceWeft

  1. Open ATLAS Explain in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.MISHHF93%2Fatlas-explain/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "atlas-explain": {
      "type": "http",
      "url": "https://atlas-explain-mcp.atlas-explain.workers.dev/mcp"
    }
  }
}

README

ATLAS Explain

Educational explanations of a market move. After a sharp drop, ATLAS Explain turns a structured move card into a balanced account of why a buyer might see opportunity and why a seller might see further risk. It is free to use, Apache-2.0, and it does not tell anyone to trade.

The model runs through Firebase AI Logic hybrid inference. Chrome uses Gemini Nano on the device when that model is available, and Gemini in the cloud when it is not. The screen names the path that actually ran.

ATLAS Explain comes two ways, from one codebase: an MCP connector that AI assistants (Claude, ChatGPT, Cursor, VS Code) add with one address, and a web app at https://atlas-explain.web.app/app. There is no Chrome extension (removed on 15 Nov 2026).

This is an entry for Google's #BuildHybridAI 2026 hackathon.

Educational explanations only. Not financial advice, not a recommendation, and not an offer to buy or sell any security.

Value proposition

A sharp move can support two careful readings at once. Someone might buy a dip because the drop looks larger than the new information. Someone else might sell because the same information can keep pressuring the price. ATLAS Explain makes both readings explicit from a move card the user supplies: symbol, percent move, volume versus normal, the market and sector that day, peers, volatility, upcoming events, and optional headlines.

Headline text is classified into a fixed taxonomy: AI capex, China / export rules, scandal / governance, earnings / guidance, rates / Fed, macro shock, or other. The answer is always three buyer reasons, three seller reasons, and what would change the picture.

Private notes and a watchlist can ride along only when the on-device model runs. They are omitted from cloud prompts and they are never written to Firestore.

How Firebase AI Logic hybrid inference is used

The web client uses the Firebase JavaScript SDK ([email protected]) and the hybrid API documented here:

Checked against @firebase/ai 3.1.0 typings shipped with that SDK. The calls are:

StepAPIWhere it runs
Gemini Developer API backendgetAI(app, { backend: new GoogleAIBackend() })src/platform/web/explainer.ts line 45
ModeInferenceMode.PREFER_ON_DEVICE, ONLY_ON_DEVICE, PREFER_IN_CLOUD, or ONLY_IN_CLOUDsrc/platform/web/explainer.ts lines 37–41
ModelgetGenerativeModel(ai, { mode, inCloudParams, onDeviceParams })src/platform/web/explainer.ts lines 95–125
On-device init, after the Explain clickmodel.initializeDeviceModel(onDownloadProgress)src/platform/web/explainer.ts lines 127–132
Inferencemodel.generateContent(prompt)src/platform/web/explainer.ts line 144
Which path ranresult.response.inferenceSource (on_device or in_cloud)src/platform/web/explainer.ts lines 148 and 159–167

inCloudParams.generationConfig sets responseMimeType: "application/json" and a responseSchema built with Schema.object / Schema.enumString. The same schema is passed to the on-device model as onDeviceParams.promptOptions.responseConstraint, which is what the hybrid structured-output guide requires so both paths return the same shape.

The cloud model id defaults to gemini-3.5-flash-lite (the SDK 13 default) and can be changed with Remote Config. Temperature is not sent: the SDK marks it unsupported on Gemini 3.x and later.

Path selection before that call lives in src/core/inference-path.ts (selectInferencePath, line 20) and is applied in src/core/run-explanation.ts (lines 52 and 69):

  • Remote Config inference_mode is the preference. The in-app default is prefer_on_device.
  • More than 8 headlines, a prompt over 6,000 characters, or a document over 1,200 characters forces ONLY_IN_CLOUD. On-device Gemini Nano's context is 9,216 tokens.
  • Notes and the watchlist are included only on an ONLY_ON_DEVICE call. If the device model is unavailable and the preference was prefer_on_device, the app retries once in the cloud with those fields removed.

App Check, Remote Config, and Firestore are started in src/platform/web/backend.ts:

  • App Check with ReCaptchaEnterpriseProvider: lines 58–61. A debug token is assigned just above that, and only in npm run dev.
  • Remote Config fetchAndActivate and getValue: lines 65–89. In-app defaults in src/core/settings.ts match remoteconfig.template.json.
  • Firestore addDoc under users/{uid}/explanations: line 117. Anonymous Authentication supplies the uid.

Without a Firebase web config and a reCAPTCHA Enterprise site key, src/main.ts lines 27–28 render a setup screen and do not initialize Firebase.

Architecture

src/core has no Firebase and no DOM, so the MCP connector (src/mcp/) and a future Android shell reuse the glossary, the move card, the prompt, the taxonomy parser and the path decision. The web app (src/web/app.ts) mounts the wallet shell in src/wallet/ over a WebBackend.

mermaid
flowchart TD  user[Move card, question, optional notes] --> desk[Web desk]  desk --> core[src/core validation, prompt, path]  core --> mode{Inference mode}  mode -->|short card, prefer on-device| device[initializeDeviceModel then generateContent]  mode -->|private notes| deviceOnly[ONLY_ON_DEVICE with notes]  deviceOnly -->|Gemini Nano missing| cloudRetry[ONLY_IN_CLOUD without notes]  mode -->|long input or cloud preference| cloud[ONLY_IN_CLOUD or PREFER_IN_CLOUD without notes]  device --> source[response.inferenceSource]  cloud --> source  cloudRetry --> source  source --> parse[Taxonomy parser]  parse --> ui[On-device or cloud badge]  parse --> store[Firestore users/uid/explanations]  rc[Remote Config] --> core  check[App Check reCAPTCHA Enterprise] --> device  check --> cloud

Setup

Requirements: Node.js 22 or newer, a Firebase project on the Spark plan or above, and Chrome when you want the on-device path. npm install may print an engine warning from the firebase package, which declares a newer Node for running the SDK inside Node. This app bundles the SDK for the browser and does not run inference in Node.

bash
npm installnpm run dev

The public web config for project atlas-explain is committed in src/platform/web/firebaseConfig.ts and is used when the VITE_ variables are unset. .env.example lists optional overrides for a different Firebase project. Copy it to .env.local only if you need those overrides. Do not commit service-account keys.

This Firebase project

atlas-explain is on the Spark plan. AI Logic uses the Gemini Developer API with App Check enforced. Anonymous Authentication is on. Firestore is the (default) database in nam5, in production mode. App Check uses a score-based reCAPTCHA Enterprise key limited to atlas-explain.web.app and atlas-explain.firebaseapp.com. Localhost is not on that key.

App Check debug token (localhost)

npm run dev sets self.FIREBASE_APPCHECK_DEBUG_TOKEN = true before initializeAppCheck. A production build does not set it, even if VITE_APPCHECK_DEBUG_TOKEN is present.

  1. Run npm run dev and open the local URL.
  2. Open the browser developer console. The App Check SDK prints a line like AppCheck debug token: "...".
  3. In the Firebase console, go to Security → App Check → Apps, open the web app, and choose Manage debug tokens.
  4. Add the token from the console, then reload the app. Cloud calls stay blocked until that token is registered.
  5. To reuse a token you already registered, set VITE_APPCHECK_DEBUG_TOKEN in .env.local to that token. Set it to false to turn the debug provider off. Do not add localhost to the production reCAPTCHA key.

Firebase console (another project)

  1. Create a project. Analytics is optional.
  2. Register a Web app and copy its config into .env.local using the VITE_FIREBASE_* names in .env.example.
  3. Open AI Services → AI Logic and finish Get started with the Gemini Developer API. Leave App Check enforced.
  4. Create a score-based reCAPTCHA Enterprise key and register the web app in App Check. Put the key in VITE_RECAPTCHA_ENTERPRISE_SITE_KEY.
  5. Enable Authentication → Anonymous.
  6. Create a Firestore database. Rules allow a signed-in user to read and write only users/{their uid}/explanations/*, and they reject documents that contain notes or watchlist.
  7. Remote Config parameters, also compiled into src/core/settings.ts until a template is published: inference_mode, cloud_model, prompt_template, topic_taxonomy, on_device_max_headlines, on_device_max_chars, long_document_chars, max_output_tokens. Prompt placeholders are {{TAXONOMY}}, {{QUESTION}}, {{MOVE_CARD}}, and {{PRIVATE_CONTEXT}}. Taxonomy ids are fixed in code; Remote Config can rename labels or hide an id, and other is always kept.

Deploy

.firebaserc selects project atlas-explain. firebase.json publishes Hosting from dist/ with a single-page rewrite, Firestore rules from firestore.rules, and Remote Config from remoteconfig.template.json.

Sign in once:

bash
npx firebase-tools login

Run the release gate, then deploy hosting, rules, and Remote Config:

bash
npm run release:check   # typecheck, lint, test, both builds, manifest, bundle budget, audit, trade-word scannpx firebase-tools deploy --only hosting,firestore:rules,remoteconfig

Billing is shipped switched off. billing_enabled defaults to false, checkout is not shown, and the badge says "Free during beta". See docs/MONETIZATION.md before changing that.

Deep links, desk hand-off, and concepts

ATLAS Explain can load a public move card from a link or from a message sent by an allowed page. It never auto-runs an explanation. The user still clicks Explain the move. Notes, watchlists, balances, and account fields are stripped on the way in and are not written into the editor.

The context envelope is version 1:

json
{  "v": 1,  "kind": "move_card",  "source": "atlas_desk",  "card": { "symbol": "BTCUSDT", "asOf": "2026-11-12", "movePct": -6.2 },  "question": "Why might some traders buy this dip while others sell?",  "concepts": ["shadow"]}

A bare public move card (the existing JSON shape) is also accepted. Allowed card fields are the public MoveCard keys in src/core/move-card.ts. Forbidden keys include notes, watchlist, balances, positions, account identifiers, and secrets.

Hash links keep the payload out of Hosting query logs:

  • https://atlas-explain.web.app/app/explain#c=<base64url(JSON)> (links made for / still work; they are forwarded here)
  • https://atlas-explain.web.app/app/explain#card=<uri-encoded JSON> for a small card
  • https://atlas-explain.web.app/app/explain#concept=shadow to open a glossary entry without a card

src/core/context-link.ts builds and parses these hashes. Concept ids live in src/core/glossary.ts: shadow, signal15, chart_layers, live_lock, paper_only, drop_study, hybrid_inference, and move_card.

postMessage, for a same-machine ATLAS desk tab:

js
otherWindow.postMessage(  { type: "atlas-explain/v1/load", payload: envelope, concept: "chart_layers" },  "https://atlas-explain.web.app",);

The app accepts that type only from https://atlas-explain.web.app, https://atlas-explain.firebaseapp.com, http://localhost:3000, and http://127.0.0.1:3000. It replies with atlas-explain/v1/loaded or atlas-explain/v1/error. This repository still does not contain ATLAS models, signals, or account data.

Connecting to ATLAS

ATLAS Explain never reads balances, positions, or account ids. When it talks to the private ATLAS desk, it uses this repo's connectors library (src/connectors/, see docs/connectors/README.md):

  1. The hosted web app at https://atlas-explain.web.app never calls localhost. Its header pill says Live prices when the public price feed answers, and shows nothing otherwise. Everything ATLAS-only (the Signal tab, the desk menu item, the ATLAS digest) is hidden.
  2. A local loopback build may probe ATLAS on this computer. They prefer public MCP (POST /api/mcp/public) and fall back to the REST catalog (GET /api/explain/assets).
  3. The header says ATLAS connected only when one of those probes actually answers, and only then do the ATLAS-only parts appear. It says ATLAS desk when this tab is the Markets desk and Offline when the browser is offline. It does not fake a connection, and it never shows a "Not connected" state to people who don't run ATLAS.

The desk can also open this app with a public move card (#c= / #card=) or a glossary concept (#concept=). Loading a card does not run the model until you click Explain the move.

For AI assistants (MCP)

ATLAS Explain also has a free, read-only MCP server hosted online (Cloudflare Workers free plan). Assistants such as Claude add its web address as a connector, and can then look up glossary terms, official figures (with sources) and today's headlines. Nothing is downloaded. Hosting and owner steps: docs/MCP.md.

Screenshots

Stills live in docs/screenshots/. Six were retaken on 15 Nov 2026 from the live site and a local build; local-header.png (ATLAS was not running at the time) and desk-explain-link.png (a crop of the private desk) are older. They show honest header states, the desk hand-off, today's brief, and the grey signal light. An on-device badge is not included: that still needs a recording on a laptop with Gemini Nano (see docs/DEMO.md).

[Hosted app header]

The hosted web app at https://atlas-explain.web.app/app is one page: Explain at the top, then Today, Learn and Assets, reached from the header. The pill shows Live prices; the hosted app never calls localhost.

[ATLAS local header]

A local loopback build shows ATLAS connected only when public MCP or the REST catalog on this computer answers. (This still predates the one-page layout and shows the older "ATLAS local" label.)

[Explain this move on the ATLAS desk]

The private ATLAS desk can open this app with a public move card (#c= / #card=) or a glossary concept (#concept=).

[Today's brief when ATLAS is local]

With ATLAS on this computer, Today adds the brief and the paper signal light. An earlier official note is labelled as not today's, and is not presented as today's brief.

[Hosted app, Today]

On the hosted app, Today shows the biggest crypto moves from the public price feed, with the source and time. The ATLAS digest and the signal light appear only when ATLAS runs on the visitor's own computer.

[Glossary concept question]

A #concept=shadow link opens "Explain a market move" with an educational question filled in. Nothing is sent until you click Explain the move.

[Signal light, grey default]

The paper signal light stays grey unless the desk sends its public signal. This is the honest default when there is not enough evidence, or when this tab is not the desk.

On-device model in Chrome

On-device inference needs Chrome on desktop, version 139 or newer (getting started guide):

  1. Set chrome://flags/#prompt-api-for-gemini-nano-multimodal-input to Enabled and restart Chrome.
  2. Optional, in DevTools: await LanguageModel.availability(), then await LanguageModel.create() if the result is downloadable. The first download can take several minutes.
  3. Click Explain the move. initializeDeviceModel runs from that click, which satisfies Chrome's user-activation rule. The badge then reads On-device or Cloud from inferenceSource.

If Nano is not available and the card has no private notes, PREFER_ON_DEVICE falls through to the cloud model inside the SDK. If the card has notes, the first call is device-only so the notes cannot take the cloud fallback; a failure retries in the cloud without them, and the badge says so.

Demo

The full three-minute script (the connector in Claude → a chart and official figures with their sources → the web app answering on the device with Gemini Nano → Keep going, Recent, Learn and Assets) is in docs/DEMO.md. The submission checklist is in docs/SUBMISSION.md.

StepWhat the judge sees
1The home page leads with the connector; /connect gives the one address to add.
2In Claude, ATLAS Explain explains a term, draws a price chart and returns official figures, each with its source and time.
3In the web app, Explain runs Firebase AI Logic hybrid inference; the badge names the path that ran (on-device Gemini Nano or cloud Gemini).
4Two sides and what would change the picture, never an instruction.
5Recent explanations and Learn path progress stay on the device.

Tests and CI

bash
npm run release:check

That one command runs the Node version check, typecheck, lint, tests, the web and MCP builds, the bundle budget (every chunk ≤ 500 kB, app entry ≤ 150 kB), npm audit (must be 0) and the trade-word scan, and stops at the first failure. Hosting sends a strict CSP and security headers from firebase.json. Node ^22.12 || ^24 (.nvmrc = 24). Audit overrides are explained in docs/DEPENDENCIES.md.

Unit tests cover move-card validation, prompt building, the taxonomy parser, inference-path selection, the explain retry that drops private notes, and the Firebase AI Logic calls with firebase/ai mocked. GitHub Actions (.github/workflows/ci.yml) runs the same steps on Node 22.

npm run remote-config rewrites remoteconfig.template.json from the in-app defaults. A test fails if the two drift.

Limitations

  • On-device inference is Chrome on desktop, version 139 or newer, with the Prompt API flag. Other browsers use the cloud path.
  • On-device context is 9,216 tokens. Long cards are sent to the cloud without private notes. Hybrid mode does not support multi-turn chat, token counting, or the Live API.
  • The on-device model can still return slightly messy JSON. The parser coerces unknown topics to other and rejects an answer that does not contain three reasons on each side.
  • Sample cards are illustrative. January 27, 2025 and April 3–4, 2025 figures are rounded from contemporaneous Reuters, AP, BBC, and CNBC reports linked on the card. They are not a licensed feed, and this repo does not ship Polygon, Yahoo, or Coinbase data. The blank card's −6% is a placeholder.
  • Anonymous history is tied to the browser profile. Clearing site data starts a new user.
  • App Check debug tokens are for localhost only. Production needs the reCAPTCHA Enterprise key and enforcement left on.
  • Explanations can be wrong, incomplete, or too confident. They are not research from the private ATLAS desk and they are not a forecast.

Relationship to ATLAS

ATLAS is a private, paper-only trading-research desk. ATLAS Explain is a separate public companion. This repository does not contain ATLAS models, signals, notebooks, positions, or data. A move card exists only because someone pasted it, picked a labeled sample, or loaded their own saved explanation.

What to build next

Android shell. Port the move card, prompt, taxonomy, and path decision, then call Firebase AI Logic's Android hybrid API so Gemini Nano runs through ML Kit when the device has it and Gemini in the cloud otherwise. Use the current Android getting-started guide rather than a copied web snippet: hybrid inference for Android. Reuse App Check (Play Integrity), the same Firestore rules, and the same Remote Config keys.

License

Apache License 2.0. See LICENSE.

Source: README.md at commit 09b5848

Tools

7

explain_term

Explain a market term

Look up a trading or market term (for example 'stop-limit order', 'bid-ask spread', 'yield curve') in ATLAS Explain's plain-language glossary. Education only.

Parameterstermrequired

browse_glossary

Browse the glossary and learning path

List ATLAS Explain's learning path (topics in order, each with its terms) or every glossary term in one group. Use it to suggest what to learn next, or to find the right term to explain.

Parameterstopic

asset_details

What an asset is

Everything ATLAS Explain shows about one asset: what it is, where and when it trades, its latest official figure or price (with source and time), or why no price is shown. Covers crypto, US stocks and ETFs, currencies, interest rates, energy, indices, futures and options.

Parametersassetrequired

official_figures

Official market figures

Official figures ATLAS Explain publishes from free government and regulator sources: US Treasury yields, ECB and Bank of Canada rates, EIA energy prices, and the latest SEC-filed figures (revenue, net income and more) for large US companies and ETFs. Each has its source and date. Optional search by name or symbol.

Parametersquery

crypto_prices

Crypto prices

Recent prices for the ten major coins ATLAS Explain follows (Bitcoin, Ethereum, Solana, XRP, Cardano, Dogecoin, Litecoin, Polkadot, Chainlink, Avalanche), biggest moves first. Collected hourly by ATLAS Explain's data job from Kraken's public market data (CoinGecko as backup) and served from ATLAS Explain's own data site; each answer says when they were collected.

Parameterscoin

price_history

Crypto price history

How a coin's price moved over the last 24 hours, 7 days or 30 days: start, end, change, high and low with their times, from the hourly closes on ATLAS Explain's own data site (refreshed hourly). Describes the past only; never a forecast.

Parameterscoinrequiredrange

todays_headlines

Today's market headlines

Recent market headlines ATLAS Explain collected from the GDELT Project, each with its publisher, link and time. Headlines older than 36 hours are never returned. Optional filter by company or coin.

Parametersabout

Version history

1
  1. v1.4.0LatestNov 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Atlas integrations