npm - salesforce-reports-mcp - Versions diffs - 0.3.0 → 0.4.0 - Mend

salesforce-reports-mcp 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/.claude-plugin/plugin.json +1 -1
package/README.md +88 -120
package/dist/dashboard-files.js +136 -0
package/dist/http-auth.js +310 -0
package/dist/http.js +94 -0
package/dist/index.js +59 -3
package/package.json +3 -1
package/skills/report-runner/SKILL.md +9 -0
package/skills/report-runner/dashboard-loader.js +76 -0
package/skills/report-runner/reference.md +36 -0

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-reports",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Explore, design and deploy Salesforce reports with Claude: three skills and an MCP server over the Reports and Dashboards REST API.",
   "author": { "name": "nelsben" },
   "homepage": "https://github.com/nelsben/salesforce-reports-mcp",

package/README.md CHANGED Viewed

@@ -1,52 +1,30 @@
 # salesforce-reports-mcp
-Claude finds, builds, runs and saves Salesforce reports, and reads your dashboards, from an MCP server on your own machine. Nothing is installed in Salesforce, no Salesforce MCP licence is needed, and no admin has to approve anything. You sign in with the Salesforce CLI you already use.
+[![ci](https://github.com/nelsben/salesforce-reports-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nelsben/salesforce-reports-mcp/actions/workflows/ci.yml)
-This repo is working software, and a demonstration of how to put MCP in front of Salesforce without Salesforce's own MCP. The same tools are also packaged as a feature inside the org, for people who cannot run a local server, and every design choice is written down with what it costs. Built by [Ben Nelsen](https://github.com/nelsben).
+**Ask Salesforce a question in plain words. Get the answer, the chart and the caveats.**
+Claude finds, builds, runs and saves Salesforce reports, and reads your dashboards, from a server on your own machine. Nothing is installed in Salesforce and no Salesforce MCP licence is needed. It works with the Salesforce login, API access and report permissions you already have, through the Salesforce CLI.
 > **You:** I'm a seller. How is our pipeline looking this fiscal year? Is there anything I should worry about, and can you show it to me by owner too?
 >
 > **Claude:** $3.09M across 8 open opportunities, here by stage and by owner. Worries: one owner holds 91% of the dollars, one deal alone is 29% of the pipeline, nothing is closed won this fiscal year, and one deal has no amount. Salesforce applied its default probability filter. Nothing was saved; say the word and I will save it as a report.
 >
-> *Claude Desktop, through the local MCP server, signed in with the sf CLI ([rehearsal](docs/rehearsals/runner.md)).*
+> *A recorded Claude Code run through the local MCP server, on a small Developer Edition org ([rehearsal](docs/rehearsals/runner.md)).*
 ![The report card for an unsaved opportunity report grouped by stage, drawn in light, then dark, then at phone width](docs/assets/report-view.gif)
-In Claude Desktop the run also draws as a card: the headline numbers, the filters Salesforce applied, the groups with a bar beside each amount, and a button that asks Claude to save it. Dashboards draw the same way, every component as its own chart.
-![The dashboard card for a pipeline dashboard: a metric, a gauge, a donut, bar, line, table, funnel and column charts](docs/assets/dashboard-card.png)
-*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
+## The answers are in Salesforce. Most people cannot get them out.
-## Run it on your own org
+**Reports are how a company answers questions about its customers and its pipeline, and most of the people who need those answers cannot build one.**
-Two commands in Claude Code, with Node 20 and the Salesforce CLI signed in:
-```
-claude plugin marketplace add nelsben/salesforce-reports-mcp
-claude plugin install salesforce-reports@salesforce-reports
-```
+A seller wants a number, not Report Builder. An analyst wants to try three versions of a report before saving one. An admin wants a report in another org or in git. Today each of those is a ticket, a wait, or a spreadsheet export. Here each is a sentence typed to Claude.
-That installs the three skills and the MCP server. For Claude Desktop, [docs/claude-desktop.md](docs/claude-desktop.md) is the full recipe: the config entry with the two paths that trip people up, how to check it works, the safety flags, and what each Claude surface, including mobile, can do with a local server. [docs/install.md](docs/install.md#the-local-mcp-server) has every option.
+## Three jobs, done by asking
-## Why I built this
+**The person with the question gets the answer. No one waits on the one colleague who knows Report Builder.**
-Most of what a company knows about its customers and its pipeline sits in Salesforce reports, and most of the people who need those answers cannot build a report. Assistants like Claude are becoming the way people ask, and the hard part is not the model: it is where the code runs, whose identity each call uses, and what it is allowed to change. I built this to work through those questions end to end for one real job, in the open, with every decision written down. The first answer is the local server, which needs nothing from Salesforce but an API session. The in-org packages show what it takes when that is not enough.
-## What this repo shows
-| Claim | Where to look | Evidence you can check |
-| --- | --- | --- |
-| **1. MCP on Salesforce without Salesforce MCP**, plus two in-org doors for when a local server is not an option | [Three ways to connect](#three-ways-to-connect) | One tool contract and result shape on every door (16 tools locally, 15 in the org); a [parity check](docs/decisions/0010-verification-by-parity.md) runs the same calls through two doors against a real org and compares them |
-| **2. A useful feature added to Salesforce itself**, packaged the way an admin expects | [A feature inside Salesforce](#a-feature-inside-salesforce) | Three package directories; layered Apex with a CI test that fails if the layers leak; 90 Apex tests at 99% coverage |
-| **3. Security, authentication and integration** done deliberately, per door | [Security and identity](#security-and-identity) | A different identity per door, a per-user JWT named credential with no stored secret, writes behind a custom permission, and a test that keeps org values out of the repo |
-| **4. Product and architecture judgment**, shown in the work | [How it was built](#how-it-was-built) | Personas and [experiences](docs/experiences.md), [7 probes](docs/probes/) before building, [19 decision records](docs/decisions/README.md), [live findings](docs/design.md), [7 rehearsals](docs/rehearsals/README.md) |
-## The product
-**The problem.** Reports are how a Salesforce org answers questions, and they are hard to use. A seller wants a number, not Report Builder. An analyst wants to try three versions of a report before saving one. An admin wants a report in another org or in git. As of October 2026, Salesforce's own Claude skills and its standard hosted MCP servers had no report tools, and the closest open-source servers could run or create a report, but none could change, clone or combine one, or run one that was never saved.
-**Three experiences.** Each is a Claude skill, and Claude picks the right one from what you say.
+Each is a Claude skill, and Claude picks the right one from what you say.
 | Skill | For | What Claude does |
 | --- | --- | --- |
@@ -58,120 +36,110 @@ Most of what a company knows about its customers and its pipeline sits in Salesf
 >
 > **Claude:** Preview, with 8 deals under two owners. Saved as a new report in your Private Reports; the original is untouched. Link.
-**Answers you can trust.** Every run returns the same compact shape: the filters that were applied, including the ones Salesforce adds on its own, the groups and totals, and notes that say when rows were cut or Salesforce ignored part of the request. The [experiences page](docs/experiences.md) has the personas and the facts that shaped them.
-**A report card in the chat.** The card at the top is an MCP App the local server carries with each run: the headline numbers, the filters, the groups with a bar beside each amount (or, for a matrix, a heat grid), the totals, a link to open it in Salesforce and, for an unsaved report, a button that asks Claude to save it. Claude's reply then leads with what the card cannot show instead of repeating it. The card loads nothing from the network, is styled with the Lightning Design System's own tokens so it reads as Salesforce ([decision 0018](docs/decisions/0018-cards-follow-the-lightning-design-system.md)), and every heat cell passes WCAG AA contrast in light and dark. Clients that show only text, such as Claude Code, get the same result as text ([decision 0013](docs/decisions/0013-report-view-as-an-mcp-app.md), [decision 0015](docs/decisions/0015-report-card-visuals.md)).
-**Dashboards, read and refreshed.** Claude can find a dashboard, describe its components and filters, read the numbers Salesforce last cached, and refresh it when the data is missing or old. A refresh counts as a write, so read-only mode leaves it out, and no tool saves a dashboard ([decision 0016](docs/decisions/0016-dashboards-read-and-refresh-only.md)). In Claude Desktop the result draws as the dashboard card above, with every component as its own chart in the dashboard's layout ([decision 0017](docs/decisions/0017-dashboard-card.md)).
-## Three ways to connect
-The local server is the lead: it is the whole product for anyone on Claude Code or Claude Desktop, and it needs nothing from Salesforce beyond an API session. The same tools also reach Claude two more ways, for people who cannot run a local process: a seller on claude.ai, a Flow, an Agentforce agent. Those doors live inside the org as Apex. They differ in where the code runs, who hosts it and how the user signs in.
-```mermaid
-flowchart LR
-  subgraph Laptop["Your machine"]
-    CC["Claude Code / Desktop"]
-    LS["Local MCP server<br/>(Node)"]
-    CLI["sf CLI"]
-  end
-  subgraph Cloud["claude.ai"]
-    CAI["Claude"]
-  end
-  subgraph SF["Salesforce org"]
-    GW["Hosted MCP<br/>(Salesforce gateway)"]
-    REST["ReportsApi<br/>(Apex REST)"]
-    CORE["Reports service<br/>(Apex)"]
-    API["Reports REST API"]
-  end
-  CC -- "1. stdio" --> LS -- "REST" --> API
-  CC -- "2. skills + CLI" --> CLI -- "Apex REST" --> REST
-  CAI -- "3. MCP over OAuth" --> GW --> REST
-  REST --> CORE --> API
-```
+## Numbers you can repeat in a meeting
-| | 1. Local MCP server | 2. In-org REST door with skills | 3. Hosted MCP door |
-| --- | --- | --- | --- |
-| **Direction** | Claude reaches into Salesforce | Salesforce offers a feature; Claude calls it | Salesforce serves Claude directly |
-| **Runs** | Node on your machine | Apex in the org | Salesforce's MCP gateway, then the same Apex |
-| **Installed in the org** | Nothing | `force-app` | `force-app`, `mcp-app`, optionally `callout-app` |
-| **Signs in with** | Your `sf` CLI session or a token | Your own Salesforce session | OAuth with PKCE through an External Client App |
-| **Clients** | Claude Code, Claude Desktop, any MCP client | Claude Code and any agent with a shell; Flow, Agentforce, any HTTP client | claude.ai and any remote MCP client, with nothing to host |
-| **Tools** | All 16, including dashboards; delete only with a flag | 11, no delete | 11, no delete |
-| **Choose it when** | You can run a process on your machine. No org change, no Salesforce MCP | An admin wants the feature in the org, used from scripts and agents | A team wants Claude in the browser, governed by the org |
+**Every answer says what was counted, what was filtered and what was left out, so nobody presents a number they cannot explain.**
-Each door gets the same tool names, the same input and the same result ([decision 0001](docs/decisions/0001-one-contract-three-doors.md)). The skills bind to tool names, not to a door, so one skill works over all three. [docs/architecture.md](docs/architecture.md) has a numbered sequence diagram for each door, with every step explained.
+Every run returns the same compact shape: the filters that were applied, including the ones Salesforce adds on its own, the groups and totals, and notes that say when rows were cut or Salesforce ignored part of the request. The [experiences page](docs/experiences.md) has the personas and the facts that shaped them. Nothing is saved or changed unless you ask, and a read-only mode removes every write.
-## A feature inside Salesforce
+## The answer arrives as a picture
-The in-org doors are the same tools, rebuilt in Apex so they run where a local server cannot. They are a Salesforce feature an admin installs, not a script. They ship as three package directories in [salesforce/](salesforce/README.md) ([decision 0009](docs/decisions/0009-two-shipping-units.md)):
+**In Claude Desktop the result draws as a card in the chat: the headline, the filters, the groups and a button to save it.**
-| Package | Holds | Needs |
-| --- | --- | --- |
-| `force-app` | The Apex service, its tests, two permission sets and a custom permission | Nothing else; complete on its own |
-| `mcp-app` | The API Catalog entry, the MCP server definition and the External Client App Claude signs in through. No code. | `force-app` |
-| `callout-app` | The per-user named credential that lets the hosted door call the org's own API as the user. No code. | `force-app`; used by the hosted door |
+Salesforce dashboards draw the same way, every component as its own chart.
-The Apex is layered as ports and adapters ([decision 0003](docs/decisions/0003-one-apex-class-behind-both-in-org-doors.md)). One service does the work; the REST class is only an adapter, and [a test](test/apex-layers.test.ts) fails CI if the core ever names it or sets an HTTP status. Reads use `Reports.ReportManager` inside the org; only what Apex cannot do (list report types, run an unsaved report, save) calls the org's own REST API ([decision 0004](docs/decisions/0004-reportmanager-first-callout-for-the-rest.md)). There is no delete in the org ([decision 0006](docs/decisions/0006-no-delete-in-the-org.md)).
+![The dashboard card for a pipeline dashboard: a metric, a gauge, a donut, bar, line, table, funnel and column charts](docs/assets/dashboard-card.png)
-## Security and identity
+*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
-Each door signs in differently, and each is least privilege by default.
+Claude can find a Salesforce dashboard, read the numbers Salesforce last cached and refresh it when the data is old.
-| Door | Identity | What it can do |
-| --- | --- | --- |
-| Local | The user's `sf` CLI session, refetched on expiry; never written anywhere | Whatever the user can do. `--read-only` removes every write tool; `delete_report` exists only with `--allow-delete`. |
-| REST | The caller's own Salesforce session | Reads with `Salesforce_Reports`. Saves only with `Salesforce_Reports_Write`, checked in the service, not by hiding tools ([decision 0005](docs/decisions/0005-saves-behind-a-custom-permission.md)). |
-| Hosted MCP | OAuth with PKCE through the External Client App `SalesforceReportsMcp`, scopes `mcp_api` and `refresh_token` only | The same permission sets. For the calls that need the org's REST API, a per-user JWT named credential mints a token for the signed-in user. |
+## Then keep it as a Claude dashboard
-Sharing, folder access and field-level security apply on every door, because every call runs as the user.
+**Ask for a dashboard, and Claude turns the report it just ran into a page you can keep and share.**
-**The hard part, and how it was solved.** Under a hosted MCP sign-in, Apex has no session, and asking for one throws an exception no `catch` block can stop. The first version leaked a raw platform error to claude.ai. The fix came in two steps, each with a decision record:
+In one test on Claude Desktop for Windows in November 2026, a single request ran a pipeline report and built a page with four headline tiles, a chart by stage, the detail table and a note on what was counted, in under three minutes. The page is made with [Claude Data](https://support.claude.com/en/articles/17454700-get-started-with-claude-dashboards), Claude's own dashboard feature, so your Claude plan has to include it.
-1. The hosted door got its own route, so the code knows which door called before it asks for a session, and answers a clear `CALLOUT_SESSION` instead ([decision 0007](docs/decisions/0007-callout-identity-under-hosted-mcp.md)).
-2. A probe showed that a [per-user JWT named credential](docs/probes/v0.2-phase3c.md) lets the org mint a token for the running user from a certificate it made itself. No secret is stored, no user clicks anything, and the connector's own app keeps its narrow scopes ([decision 0012](docs/decisions/0012-per-user-jwt-named-credential.md)). `npm run callout:renew` renews the certificate.
+The page is a copy of the numbers as of the run, not a live view. Check it against the answer in the chat before you share it.
-No token, consumer key, org address or certificate reaches the repo, logs or error messages. The tracked metadata holds placeholders that setup scripts fill at deploy time, and a test enforces it.
+## What you need, and what you do not
-## How it was built
+**No new licence and no install in Salesforce. A person who can already run reports and use the Salesforce CLI can start asking.**
-The method was the same for every feature: probe the platform, decide in writing, build, then check against a real org.
+You need:
-| Step | What it produced |
-| --- | --- |
-| **Probe** before building | [7 probe write-ups](docs/probes/): can a hosted MCP server wrap Apex, can Apex call its own org's API, how big a result fits in the heap, which identity works under a hosted sign-in, how dashboards refresh and filter |
-| **Decide** in writing | [19 decision records](docs/decisions/README.md), each with what it costs and what was turned down |
-| **Build** to one contract | [design.md](docs/design.md): the input and output shapes, and the live findings where Salesforce did not behave as documented |
-| **Verify** against a real org | 256 unit and server tests, 24 render tests that draw the report and dashboard cards in a browser, 90 Apex tests, a live end-to-end check that leaves no report behind, and a parity check across doors; `npm run verify` runs all of it against one org and ends with one table of counts |
-| **Rehearse** the experience | [7 rehearsals](docs/rehearsals/README.md): real Claude runs of each skill on each door, with what went wrong and what changed |
+- Claude Code or Claude Desktop. The dashboard step also needs a Claude plan that includes [Claude Data](https://support.claude.com/en/articles/17454700-get-started-with-claude-dashboards).
+- Node.js 20 or later.
+- The [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli), signed in to your org.
+- A Salesforce user with API access and the Run Reports permission, plus Create and Customize Reports to save a report.
-## Get started
+If your company restricts API access or the Salesforce CLI, that is the question to take to your admin.
-| You want | Start here |
+| It does not need | Because |
 | --- | --- |
-| Claude Desktop on your own org, nothing installed in Salesforce | [Claude Desktop guide](docs/claude-desktop.md) |
-| Claude Code or another MCP client, the same way | [Local MCP server](docs/install.md#the-local-mcp-server) |
-| The feature inside your org, called from the CLI, scripts or agents | [The REST door](docs/install.md#the-rest-door) |
-| Claude in the browser, signed in through Salesforce | [The MCP door](docs/install.md#the-mcp-door), then [the callout tools](docs/install.md#the-callout-tools-on-the-mcp-door) |
+| A Salesforce MCP licence | The server talks to the Reports REST API that every org already has |
+| Anything installed in the org | It runs on your machine |
+| A separate integration user | It signs in as you, with the Salesforce CLI session you already have |
+| New access rules | Every call runs as you, so sharing, folder access and field-level security apply as they do in Salesforce |
+| A stored password or key | The session is read from the CLI when needed and never written anywhere |
-The tools, the result shape, the safety rails and the limits are in [docs/reference.md](docs/reference.md).
+## Run it on your own org
-## Develop
+**Two commands, and Claude is working on your own data.**
+Run them in Claude Code, with Node 20 and the Salesforce CLI signed in:
 ```
-npm install
-npm run build
-npm test
-npm run test:render                            # draw the report card in Chromium and compare screenshots
-npm run live -- --org <alias> --allow-delete   # end-to-end run against an org you can write to
-npm run capture -- --org <alias>               # refresh the test fixtures (anonymised)
+claude plugin marketplace add nelsben/salesforce-reports-mcp
+claude plugin install salesforce-reports@salesforce-reports
 ```
-`npm run live` creates several private reports named `zz-live-check-*`, deletes them, and fails if any remain. Use a sandbox or scratch org.
+That installs the three skills and the MCP server. Claude uses your Salesforce CLI default org. To pick another org, start Claude Code with `SF_ORG=<alias> claude`. To remove every tool that can save or change something, add `SF_REPORTS_READ_ONLY=1` the same way.
+Then ask:
+- "How is our open pipeline looking by stage, and what should I worry about?"
+- "Start from my pipeline report, group it by owner and save it as a new report."
+- "Build me a dashboard of that to share with my team."
+For Claude Desktop, [docs/claude-desktop.md](docs/claude-desktop.md) is the full recipe: the config entry with the two paths that trip people up, how to check it works, the safety flags, and what each Claude surface, including mobile, can do with a local server. For claude.ai and your phone, [From claude.ai and your phone](docs/install.md#from-claudeai-and-your-phone) runs the same server over HTTP behind a tunnel. [docs/install.md](docs/install.md#the-local-mcp-server) has every option.
+## Where your data goes
+**Report data goes from your Salesforce org to your machine and into your Claude conversation. The server sends it nowhere else.**
+- The server runs on your machine and calls only your own Salesforce org, as you. It has no analytics.
+- What a report returns goes into your Claude conversation, under the terms of your Claude plan.
+- Nothing is saved or changed in Salesforce unless you ask.
+- A Claude dashboard is a copy of the numbers in your Claude account, private until you share it. Anyone you share it with sees those numbers, whatever their Salesforce access.
+[Security and identity](docs/security.md#where-your-data-goes) has the detail.
+## Limits
+**Know these before a number goes on a slide.**
+- A Claude dashboard is a copy as of the run, not a live view.
+- The report card draws amounts with a dollar sign in every org, whatever the org's currency.
+- Salesforce returns at most 2,000 detail rows per run and 100 columns per report. Every answer says when rows were cut.
+- Joined reports are not supported.
+- Salesforce allows 500 report runs per org per hour.
+- Salesforce adds default filters to some report types. They are listed in every answer, so check them against your question.
+[The reference](docs/reference.md#limits) has the full list.
+## Go deeper
+| Page | What it holds |
+| --- | --- |
+| [Field notes](docs/field-notes.md) | What else was built and tried: the four ways to connect, the feature inside Salesforce, how it was built and checked, and why |
+| [Security and identity](docs/security.md) | Who each call runs as, what it can change, where your data goes, and how secrets are kept out |
+| [Reference](docs/reference.md) | The tools, the result shape, the safety rails and the limits |
+| [Decision records](docs/decisions/README.md) | Every design choice, with what it costs and what was turned down |
-## Roadmap
+## Help
-- Joined reports, report charts, and subscriptions.
+Questions and problems go to [GitHub Issues](https://github.com/nelsben/salesforce-reports-mcp/issues).
 ## License

package/dist/dashboard-files.js ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ * The dashboard-files command: runs report definitions over the local door, read-only, and writes one ReportResult
+ * JSON file per report, ready to attach to a Claude Dashboard. It is the `dashboard-files` subcommand of the server
+ * binary: `salesforce-reports-mcp dashboard-files --org <alias> --defs <file.json> --out <dir>`.
+ *
+ * The defs file is a JSON object mapping a short id to query_report arguments (the definition fields at the top
+ * level). The command never uses a default org and never prints a row value, a token or the instance URL. The last
+ * line is `dashboard-files: written=<n> failed=<m>`.
+ *
+ * Importing this module has no side effects. The command runs the reports through a child server: this package's own
+ * dist/index.js, read-only, on the local door.
+ */
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+export const USAGE = "Usage: salesforce-reports-mcp dashboard-files --org <alias> --defs <file.json> --out <dir>";
+const ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** Checks the defs object. Returns the entries in file order, or the first problem, naming the id. */
+export function validateDefs(defs) {
+    if (typeof defs !== "object" || defs === null || Array.isArray(defs)) {
+        return { error: "The defs file must be a JSON object mapping an id to query_report arguments." };
+    }
+    const entries = [];
+    for (const [id, value] of Object.entries(defs)) {
+        if (!ID_PATTERN.test(id))
+            return { error: `Bad id "${id}": use letters, digits, dash and underscore only.` };
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return { error: `The value for id "${id}" must be an object of query_report arguments.` };
+        }
+        entries.push([id, value]);
+    }
+    return { entries };
+}
+/** The last line of the command. */
+export const summaryLine = (written, failed) => `dashboard-files: written=${written} failed=${failed}`;
+function rowCount(result) {
+    const detail = result.detail;
+    if (detail && typeof detail.rowCount === "number")
+        return detail.rowCount;
+    const groups = result.groups;
+    return Array.isArray(groups?.rows) ? groups.rows.length : 0;
+}
+/** Runs each definition in order, writes one file per success and always closes the client. */
+export async function runDashboardFiles(options) {
+    const { client, defs, outDir, writer, print } = options;
+    let written = 0;
+    let failed = 0;
+    try {
+        await writer.mkdir(outDir);
+        for (const [id, args] of defs) {
+            let answer;
+            try {
+                answer = (await client.callTool({ name: "query_report", arguments: args }));
+            }
+            catch {
+                answer = undefined;
+            }
+            const result = answer?.structuredContent;
+            if (!answer || answer.isError || typeof result !== "object" || result === null) {
+                failed++;
+                print(`${id}: failed`);
+                continue;
+            }
+            await writer.writeFile(join(outDir, `${id}.json`), JSON.stringify(result, null, 2) + "\n");
+            written++;
+            const truncated = result.detail?.truncated === true;
+            print(`${id}: rows=${rowCount(result)} truncated=${truncated}`);
+        }
+    }
+    finally {
+        await client.close();
+    }
+    print(summaryLine(written, failed));
+    return { written, failed };
+}
+/**
+ * Runs the dashboard-files command on its arguments (everything after the subcommand name). Returns the exit code:
+ * 0 when every report was written, 1 when any failed or the server could not be reached, 2 on a usage error.
+ */
+export async function dashboardFilesCommand(argv) {
+    let values;
+    try {
+        values = parseArgs({
+            args: argv,
+            options: { org: { type: "string" }, defs: { type: "string" }, out: { type: "string" } },
+            strict: true,
+        }).values;
+    }
+    catch {
+        console.error(USAGE);
+        return 2;
+    }
+    if (!values.org || !values.defs || !values.out) {
+        console.error(USAGE);
+        return 2;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(values.defs, "utf8"));
+    }
+    catch {
+        console.error("The defs file could not be read as JSON.");
+        return 2;
+    }
+    const checked = validateDefs(raw);
+    if ("error" in checked) {
+        console.error(checked.error);
+        return 2;
+    }
+    const client = new Client({ name: "dashboard-files", version: "1.0.0" });
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [fileURLToPath(new URL("./index.js", import.meta.url)), "--org", values.org, "--read-only"],
+        stderr: "ignore",
+    });
+    let failed = 1;
+    try {
+        await client.connect(transport);
+        ({ failed } = await runDashboardFiles({
+            client,
+            defs: checked.entries,
+            outDir: resolve(values.out),
+            writer: { mkdir: async (dir) => void (await mkdir(dir, { recursive: true })), writeFile: (path, text) => writeFile(path, text) },
+            print: (line) => console.log(line),
+        }));
+    }
+    catch {
+        console.error("dashboard-files: the server could not be started or reached.");
+        await client.close().catch(() => undefined);
+    }
+    return failed > 0 ? 1 : 0;
+}

package/dist/http-auth.js ADDED Viewed

@@ -0,0 +1,310 @@
+// The HTTP door's own OAuth 2.1 server, for one owner. It issues tokens only for this server's /mcp,
+// and only after the owner types the passcode from SF_REPORTS_HTTP_PASSCODE on the /authorize page.
+// Everything lives in memory: a restart signs every client out. Importing this module does nothing.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { InvalidClientMetadataError, InvalidGrantError, InvalidScopeError, InvalidTargetError, InvalidTokenError, } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+export const PASSCODE_ENV = "SF_REPORTS_HTTP_PASSCODE";
+export const MIN_PASSCODE_LENGTH = 16;
+const ACCESS_TTL_S = 60 * 60;
+const REFRESH_TTL_S = 30 * 24 * 60 * 60;
+const CODE_TTL_MS = 5 * 60 * 1000;
+const MAX_WRONG_PASSCODES = 10;
+const WRONG_PASSCODE_WINDOW_MS = 15 * 60 * 1000;
+// Hosts that may use plain http, for a public URL and for a registered redirect URI.
+const LOOPBACK_HTTP_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** The issuer URL: https, or http on localhost or 127.0.0.1, with no path, query or fragment. */
+export function resolvePublicUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("--public-url must be an absolute URL, such as https://reports.example.com.");
+    }
+    // The SDK allows a plain http issuer only on these two hosts.
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error("--public-url must use https, unless its host is localhost or 127.0.0.1.");
+    }
+    if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
+        throw new Error("--public-url must be an origin only, with no path, query or fragment, such as https://reports.example.com.");
+    }
+    return url;
+}
+/** Checks the passcode without ever putting it in the message. */
+export function checkPasscode(passcode) {
+    if (!passcode)
+        throw new Error(`${PASSCODE_ENV} must be set when --public-url turns the OAuth layer on.`);
+    if (passcode.length < MIN_PASSCODE_LENGTH)
+        throw new Error(`${PASSCODE_ENV} must be at least ${MIN_PASSCODE_LENGTH} characters.`);
+    return passcode;
+}
+/** Validates the options before anything starts, so a bad start fails before Salesforce is touched. */
+export function checkOAuthOptions(options) {
+    checkPasscode(options.passcode);
+    const publicUrl = resolvePublicUrl(options.publicUrl);
+    return { publicUrl, resource: new URL("/mcp", publicUrl) };
+}
+const sha256 = (value) => createHash("sha256").update(value, "utf8").digest();
+const hashKey = (value) => sha256(value).toString("base64url");
+const newSecret = () => randomBytes(32).toString("base64url");
+// A resource compared as a string, without its fragment and one trailing slash, as the SDK's bearer check does.
+function comparable(value) {
+    const text = String(value);
+    const hash = text.indexOf("#");
+    return (hash === -1 ? text : text.slice(0, hash)).replace(/\/$/, "");
+}
+function allowedRedirect(uri) {
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    if (url.hash)
+        return false;
+    return url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HTTP_HOSTS.includes(url.hostname));
+}
+const escapeHtml = (value) => value.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+/** An in-memory OAuth server for one owner. Codes and tokens are kept only as SHA-256 hashes. */
+export class OwnerOAuthProvider {
+    resource;
+    now;
+    passcodeHash;
+    clients = new Map();
+    codes = new Map();
+    grants = new Map();
+    wrongPasscodes = [];
+    constructor(options) {
+        this.resource = checkOAuthOptions(options).resource;
+        this.passcodeHash = sha256(options.passcode);
+        this.now = options.now ?? Date.now;
+    }
+    clientsStore = {
+        getClient: (clientId) => this.clients.get(clientId),
+        registerClient: (client) => {
+            const full = client;
+            if (full.redirect_uris.length === 0 || !full.redirect_uris.every(allowedRedirect)) {
+                throw new InvalidClientMetadataError("Each redirect URI must use https, or http on a loopback host.");
+            }
+            this.clients.set(full.client_id, full);
+            return full;
+        },
+    };
+    async authorize(client, params, res) {
+        if (params.resource && comparable(params.resource) !== comparable(this.resource)) {
+            throw new InvalidTargetError(`This server issues tokens only for ${this.resource.href}.`);
+        }
+        const req = res.req;
+        if (req.method !== "POST") {
+            this.page(res, 200, client, params);
+            return;
+        }
+        const now = this.now();
+        this.wrongPasscodes = this.wrongPasscodes.filter((t) => now - t < WRONG_PASSCODE_WINDOW_MS);
+        if (this.wrongPasscodes.length >= MAX_WRONG_PASSCODES) {
+            this.page(res, 429, client, params, "Too many wrong passcodes. Wait 15 minutes, then try again.");
+            return;
+        }
+        const given = typeof req.body?.passcode === "string" ? req.body.passcode : "";
+        if (!timingSafeEqual(sha256(given), this.passcodeHash)) {
+            this.wrongPasscodes.push(now);
+            this.page(res, 403, client, params, "That passcode is not right.");
+            return;
+        }
+        this.prune(now);
+        const code = newSecret();
+        this.codes.set(hashKey(code), {
+            clientId: client.client_id,
+            redirectUri: params.redirectUri,
+            challenge: params.codeChallenge,
+            resource: this.resource.href,
+            scopes: params.scopes ?? [],
+            expiresAt: now + CODE_TTL_MS,
+            challenged: false,
+        });
+        const target = new URL(params.redirectUri);
+        target.searchParams.set("code", code);
+        if (params.state !== undefined)
+            target.searchParams.set("state", params.state);
+        res.redirect(302, target.href);
+    }
+    // The token handler asks for the challenge, checks the verifier, then exchanges. Asking spends the code,
+    // so a wrong verifier burns it and a second try with the same code fails.
+    async challengeForAuthorizationCode(client, authorizationCode) {
+        const key = hashKey(authorizationCode);
+        const entry = this.codes.get(key);
+        if (!entry || entry.challenged || entry.clientId !== client.client_id || entry.expiresAt <= this.now()) {
+            this.codes.delete(key);
+            throw new InvalidGrantError("The authorization code is invalid, used or expired.");
+        }
+        entry.challenged = true;
+        return entry.challenge;
+    }
+    async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri, resource) {
+        const key = hashKey(authorizationCode);
+        const entry = this.codes.get(key);
+        this.codes.delete(key);
+        if (!entry || !entry.challenged || entry.clientId !== client.client_id || entry.expiresAt <= this.now()) {
+            throw new InvalidGrantError("The authorization code is invalid, used or expired.");
+        }
+        if (redirectUri !== undefined && redirectUri !== entry.redirectUri) {
+            throw new InvalidGrantError("redirect_uri does not match the authorization request.");
+        }
+        if (resource && comparable(resource) !== comparable(entry.resource)) {
+            throw new InvalidTargetError("resource does not match the authorization request.");
+        }
+        return this.issueTokens(client.client_id, new URL(entry.resource), entry.scopes);
+    }
+    async exchangeRefreshToken(client, refreshToken, scopes, resource) {
+        const key = hashKey(refreshToken);
+        const grant = this.grants.get(key);
+        if (!grant || grant.kind !== "refresh" || grant.clientId !== client.client_id || grant.expiresAt <= this.now()) {
+            if (grant && grant.expiresAt <= this.now())
+                this.grants.delete(key);
+            throw new InvalidGrantError("The refresh token is invalid, used or expired.");
+        }
+        if (resource && comparable(resource) !== comparable(grant.resource)) {
+            throw new InvalidTargetError("resource does not match the refresh token.");
+        }
+        if (scopes && !scopes.every((s) => grant.scopes.includes(s))) {
+            throw new InvalidScopeError("A refresh cannot widen the scopes.");
+        }
+        // Rotate: the old refresh token stops working.
+        this.grants.delete(key);
+        return this.issueTokens(client.client_id, new URL(grant.resource), scopes ?? grant.scopes);
+    }
+    async verifyAccessToken(token) {
+        const key = hashKey(token);
+        const grant = this.grants.get(key);
+        if (!grant || grant.kind !== "access")
+            throw new InvalidTokenError("The access token is not valid.");
+        if (grant.expiresAt <= this.now()) {
+            this.grants.delete(key);
+            throw new InvalidTokenError("The access token has expired.");
+        }
+        if (comparable(grant.resource) !== comparable(this.resource)) {
+            throw new InvalidTokenError("The access token was not issued for this resource.");
+        }
+        return {
+            token,
+            clientId: grant.clientId,
+            scopes: grant.scopes,
+            expiresAt: Math.floor(grant.expiresAt / 1000),
+            resource: new URL(grant.resource),
+        };
+    }
+    async revokeToken(client, request) {
+        const key = hashKey(request.token);
+        if (this.grants.get(key)?.clientId === client.client_id)
+            this.grants.delete(key);
+    }
+    /** Issues an access and refresh token pair. Only the hashes are kept. */
+    issueTokens(clientId, resource, scopes) {
+        const now = this.now();
+        this.prune(now);
+        const accessToken = newSecret();
+        const refreshToken = newSecret();
+        this.grants.set(hashKey(accessToken), { kind: "access", clientId, resource: resource.href, scopes, expiresAt: now + ACCESS_TTL_S * 1000 });
+        this.grants.set(hashKey(refreshToken), { kind: "refresh", clientId, resource: resource.href, scopes, expiresAt: now + REFRESH_TTL_S * 1000 });
+        return {
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: ACCESS_TTL_S,
+            refresh_token: refreshToken,
+            ...(scopes.length ? { scope: scopes.join(" ") } : {}),
+        };
+    }
+    prune(now) {
+        for (const [key, code] of this.codes)
+            if (code.expiresAt <= now)
+                this.codes.delete(key);
+        for (const [key, grant] of this.grants)
+            if (grant.expiresAt <= now)
+                this.grants.delete(key);
+    }
+    // One self-contained page: no script, no external asset. The passcode is never written back into it.
+    page(res, status, client, params, error) {
+        const name = escapeHtml(client.client_name || client.client_id);
+        const returnHost = escapeHtml(new URL(params.redirectUri).host);
+        const hidden = {
+            response_type: "code",
+            client_id: client.client_id,
+            redirect_uri: params.redirectUri,
+            code_challenge: params.codeChallenge,
+            code_challenge_method: "S256",
+            state: params.state,
+            scope: params.scopes?.length ? params.scopes.join(" ") : undefined,
+            resource: params.resource?.href,
+        };
+        const fields = Object.entries(hidden)
+            .filter((entry) => entry[1] !== undefined)
+            .map(([k, v]) => `<input type="hidden" name="${k}" value="${escapeHtml(v)}">`)
+            .join("\n      ");
+        const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sign in to Salesforce reports</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; font: 16px/1.5 system-ui, sans-serif; background: Canvas; color: CanvasText; }
+  main { max-width: 28rem; margin: 3rem auto; padding: 0 1rem; }
+  h1 { font-size: 1.4rem; }
+  .error { color: #b3261e; font-weight: 600; }
+  label { display: block; margin: 1.25rem 0 .25rem; font-weight: 600; }
+  input[type=password] { box-sizing: border-box; width: 100%; padding: .6rem; font: inherit; }
+  button { margin-top: 1rem; padding: .6rem 1.2rem; font: inherit; cursor: pointer; }
+  .small { font-size: .875rem; opacity: .8; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Allow ${name} to use Salesforce reports?</h1>
+  <p><strong>${name}</strong> asks to connect to this server. Approving lets it run this server's tools as the Salesforce user this server is signed in as.</p>
+  <p class="small">After you approve, you go back to ${returnHost}. Only approve a client you just added yourself.</p>
+  ${error ? `<p class="error" role="alert">${escapeHtml(error)}</p>` : ""}
+  <form method="post" action="/authorize">
+      ${fields}
+    <label for="passcode">Passcode</label>
+    <input id="passcode" name="passcode" type="password" autocomplete="current-password" required autofocus>
+    <button type="submit">Approve</button>
+  </form>
+</main>
+</body>
+</html>
+`;
+        res.setHeader("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'");
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.status(status).type("html").send(html);
+    }
+}
+export function createOwnerAuth(options) {
+    const { publicUrl, resource } = checkOAuthOptions(options);
+    const provider = new OwnerOAuthProvider(options);
+    // Behind a tunnel every request arrives from loopback with an X-Forwarded-For header. The SDK's limits then
+    // count all callers together, which suits one owner; skip the check that would print a stack trace for it.
+    const rateLimit = { validate: { xForwardedForHeader: false } };
+    const router = mcpAuthRouter({
+        provider,
+        issuerUrl: publicUrl,
+        resourceServerUrl: resource,
+        resourceName: "Salesforce reports",
+        authorizationOptions: { rateLimit },
+        clientRegistrationOptions: { rateLimit },
+        tokenOptions: { rateLimit },
+        revocationOptions: { rateLimit },
+    });
+    const bearer = requireBearerAuth({
+        verifier: provider,
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resource),
+        expectedResource: resource,
+    });
+    const allowedHosts = [...new Set([publicUrl.hostname, ...LOOPBACK_HTTP_HOSTS])];
+    return { provider, router, bearer, allowedHosts };
+}

package/dist/http.js ADDED Viewed

@@ -0,0 +1,94 @@
+import { randomUUID } from "node:crypto";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createOwnerAuth } from "./http-auth.js";
+export const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "localhost"];
+export function assertLoopbackHost(host) {
+    if (!LOOPBACK_HOSTS.includes(host)) {
+        throw new Error(`--host ${host} is not loopback. A non-loopback host needs the OAuth layer: set --public-url and SF_REPORTS_HTTP_PASSCODE.`);
+    }
+}
+// Express request and response types are not imported here; the SDK's own types are enough.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export async function startHttpServer(options) {
+    const auth = options.oauth ? createOwnerAuth(options.oauth) : undefined;
+    if (!auth)
+        assertLoopbackHost(options.host);
+    const app = createMcpExpressApp(auth ? { host: options.host, allowedHosts: auth.allowedHosts } : { host: options.host });
+    if (auth)
+        app.use(auth.router);
+    const guard = auth ? [auth.bearer] : [];
+    const sessions = new Map();
+    const reject = (res, status, message) => {
+        res.status(status).json({ jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+    };
+    app.post("/mcp", ...guard, async (req, res) => {
+        try {
+            const sessionId = req.headers["mcp-session-id"];
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                await existing.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            if (sessionId || !isInitializeRequest(req.body)) {
+                reject(res, 400, "Bad Request: no valid session. Send an initialize request first.");
+                return;
+            }
+            const server = options.createServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                    sessions.set(id, { transport, server });
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    sessions.delete(transport.sessionId);
+            };
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch {
+            if (!res.headersSent)
+                reject(res, 500, "Internal server error");
+        }
+    });
+    const bySession = async (req, res) => {
+        try {
+            const sessionId = req.headers["mcp-session-id"];
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (!existing) {
+                reject(res, 400, "Bad Request: unknown or missing session id.");
+                return;
+            }
+            await existing.transport.handleRequest(req, res);
+        }
+        catch {
+            if (!res.headersSent)
+                reject(res, 500, "Internal server error");
+        }
+    };
+    app.get("/mcp", ...guard, bySession);
+    app.delete("/mcp", ...guard, bySession);
+    const httpServer = await new Promise((resolve, reject2) => {
+        const s = app.listen(options.port, options.host, () => resolve(s));
+        s.on("error", reject2);
+    });
+    const port = httpServer.address().port;
+    let closing;
+    const close = () => {
+        closing ??= (async () => {
+            const open = [...sessions.values()];
+            sessions.clear();
+            await Promise.all(open.map(async ({ transport, server }) => {
+                await transport.close().catch(() => undefined);
+                await server.close().catch(() => undefined);
+            }));
+            httpServer.closeAllConnections();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        })();
+        return closing;
+    };
+    return { port, host: options.host, close, oauth: auth?.provider };
+}

package/dist/index.js CHANGED Viewed

@@ -4,10 +4,19 @@ import { parseArgs } from "node:util";
 import { ReportsApi } from "./reports/api.js";
 import { createClient, DEFAULT_API_VERSION } from "./salesforce/client.js";
 import { resolveConnection } from "./salesforce/connection.js";
+import { checkOAuthOptions, PASSCODE_ENV } from "./http-auth.js";
+import { assertLoopbackHost, startHttpServer } from "./http.js";
 import { buildServer } from "./server.js";
-const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio)
+import { dashboardFilesCommand } from "./dashboard-files.js";
+const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio, or Streamable HTTP with --http)
 Usage: salesforce-reports-mcp [--org <alias>] [options]
+       salesforce-reports-mcp dashboard-files --org <alias> --defs <file.json> --out <dir>
+  dashboard-files      Run report definitions read-only and write one result file per definition, for a Claude
+                       Dashboard. Flags: --org <alias> (required), --defs <file.json> (a JSON object mapping an id
+                       to query_report arguments), --out <dir> (required). Exit 0 when all reports were written,
+                       1 when any failed, 2 on a usage error. It starts no server.
   --org <alias>        Authenticate through the Salesforce CLI (env SF_ORG). Default: the sf default org.
                        Or set SF_INSTANCE_URL and SF_ACCESS_TOKEN to use a token you already hold.
@@ -15,12 +24,22 @@ Usage: salesforce-reports-mcp [--org <alias>] [options]
   --read-only          Register no write tools (env SF_REPORTS_READ_ONLY=1).
   --allow-delete       Register delete_report (env SF_REPORTS_ALLOW_DELETE=1).
   --max-rows <n>       Default cap on detail rows per result (env SF_REPORTS_MAX_ROWS). Default 200, ceiling 2000.
+  --http <port>        Serve Streamable HTTP at /mcp instead of stdio (env SF_REPORTS_HTTP_PORT). Port 0 picks a free port.
+  --host <host>        Host for --http (env SF_REPORTS_HTTP_HOST). Default 127.0.0.1. Loopback only, unless --public-url is set.
+  --public-url <url>   Turn on the OAuth layer for --http (env SF_REPORTS_PUBLIC_URL), for use behind a tunnel.
+                       The URL clients reach this server at, https unless its host is loopback; /mcp then needs
+                       a token this server issued. Needs ${PASSCODE_ENV} (env only, at least 16 characters):
+                       the owner types it on the sign-in page to approve a client.
   -h, --help           Show this help.
 `;
 function flag(value, envName) {
     return value ?? ["1", "true"].includes((process.env[envName] ?? "").toLowerCase());
 }
 async function main() {
+    if (process.argv[2] === "dashboard-files") {
+        process.exitCode = await dashboardFilesCommand(process.argv.slice(3));
+        return;
+    }
     const { values } = parseArgs({
         options: {
             org: { type: "string" },
@@ -28,6 +47,9 @@ async function main() {
             "read-only": { type: "boolean" },
             "allow-delete": { type: "boolean" },
             "max-rows": { type: "string" },
+            http: { type: "string" },
+            host: { type: "string" },
+            "public-url": { type: "string" },
             help: { type: "boolean", short: "h" },
         },
         strict: true,
@@ -41,14 +63,48 @@ async function main() {
     if (!Number.isInteger(maxRows) || maxRows < 1 || maxRows > 2000) {
         throw new Error("--max-rows must be a whole number from 1 to 2000.");
     }
+    const httpRaw = values.http ?? process.env.SF_REPORTS_HTTP_PORT;
+    const host = values.host ?? process.env.SF_REPORTS_HTTP_HOST ?? "127.0.0.1";
+    const publicUrl = values["public-url"] ?? process.env.SF_REPORTS_PUBLIC_URL;
+    let port;
+    let oauth;
+    if (httpRaw !== undefined && httpRaw !== "") {
+        port = Number(httpRaw);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error("--http must be a port from 0 to 65535.");
+        if (publicUrl) {
+            // The passcode comes from the environment only, never a flag.
+            oauth = { publicUrl, passcode: process.env[PASSCODE_ENV] ?? "" };
+            checkOAuthOptions(oauth);
+        }
+        else {
+            assertLoopbackHost(host);
+        }
+    }
+    else if (values["public-url"] !== undefined) {
+        throw new Error("--public-url needs --http.");
+    }
     const connection = resolveConnection({ org: values.org });
     const client = createClient(connection, { apiVersion: values["api-version"] ?? process.env.SF_API_VERSION });
-    const server = buildServer(new ReportsApi(client), {
+    const reports = new ReportsApi(client);
+    const make = () => buildServer(reports, {
         readOnly: flag(values["read-only"], "SF_REPORTS_READ_ONLY"),
         allowDelete: flag(values["allow-delete"], "SF_REPORTS_ALLOW_DELETE"),
         maxRows,
     });
-    await server.connect(new StdioServerTransport());
+    if (port === undefined) {
+        await make().connect(new StdioServerTransport());
+        return;
+    }
+    const handle = await startHttpServer({ port, host, createServer: make, oauth });
+    const shutdown = () => {
+        void handle.close().then(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    const local = `http://${host.includes(":") ? `[${host}]` : host}:${handle.port}/mcp`;
+    const signIn = handle.oauth ? ` (public at ${handle.oauth.resource.href}, OAuth sign-in on)` : "";
+    process.stderr.write(`salesforce-reports-mcp: listening on ${local}${signIn}\n`);
 }
 main().catch((error) => {
     process.stderr.write(`salesforce-reports-mcp: ${error instanceof Error ? error.message : String(error)}\n`);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-reports-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server to find, define, run, save and combine Salesforce reports through the Reports and Dashboards REST API",
   "keywords": [
     "salesforce",
@@ -40,6 +40,8 @@
     "parity": "tsx scripts/parity-check.ts",
     "capture": "tsx scripts/capture-fixtures.ts",
     "prepare": "npm run build",
+    "door4-check": "tsx scripts/door4-check.ts",
+    "dashboard-files": "node dist/index.js dashboard-files",
     "mcp-login": "tsx scripts/mcp-login.ts",
     "mcp-check": "tsx scripts/mcp-check.ts",
     "mcp:generate": "tsx salesforce/scripts/generate-metadata.ts",

package/skills/report-runner/SKILL.md CHANGED Viewed

@@ -34,6 +34,15 @@ Reach for a dashboard tool instead of a report run when the user names a dashboa
 3. **Read it** with `run_dashboard`. Lead with the two or three components that answer the question, each by its header, and say when the data was refreshed and whose data it shows (`runningUser`). Read `notes`.
 4. **No data or old data.** When a note says a component has no data, or the numbers are more than a day old, say so and offer `refresh_dashboard` with the same filters. Do not refresh without the user's yes: a refresh reruns every source report and changes what other viewers see. If it answers that the dashboard was refreshed less than a minute ago, give the cached numbers and the time to try again; do not retry at once.
+## A dashboard to keep or share
+Where the host draws the report card, the card in chat comes first. When the person wants a view to keep, share or open again ("make this a dashboard", "can the team see this"), offer a Claude Dashboard, and build it only after their yes. Do not offer it unasked, and do not use it for a one-off answer.
+- **On the local server**, build it from attached result files: run the reports, attach each `ReportResult` file as a dataset, and use the tested loader in `reference.md`. It is a copy as of the run, so the page must say it is a copy and give the run date. To update it, run the reports again. Design changes go through the dashboard's comments.
+- **Where `run_report` comes from a connector** (the in-org hosted server, or the local server over HTTP on claude.ai), a live dashboard is possible with Claude's Dashboard artifacts. That path is untested from claude.ai.
+The dashboard saves no Salesforce report.
 ## Never save
 Do not call `create_report`, `update_report`, `clone_report` or `delete_report` from this skill. If the user wants a slice kept, or a report changed, say so plainly ("Want me to save this as a report?") and carry on only after they say yes.

package/skills/report-runner/dashboard-loader.js ADDED Viewed

@@ -0,0 +1,76 @@
+function reportResultToRows({ answer }) {
+  var fail = function (e) {
+    if (e && typeof e === "object") {
+      var parts = [e.message, e.code, e.hint].filter(function (x) { return typeof x === "string" && x; });
+      if (parts.length) return new Error(parts.join(" "));
+    }
+    return new Error(typeof e === "string" && e ? e : "The answer carried an error.");
+  };
+  var parse = function (text) {
+    try { return JSON.parse(text); } catch (e) { throw new Error("The answer is not a ReportResult: it is text that is not JSON."); }
+  };
+  var textOf = function (a) {
+    var c = a && a.content;
+    return Array.isArray(c) && c[0] && typeof c[0].text === "string" ? c[0].text : "";
+  };
+  var r = answer;
+  if (typeof r === "string") r = parse(r);
+  if (r && typeof r === "object" && r.isError) throw fail(textOf(r) || r.error);
+  if (r && typeof r === "object" && r.structuredContent && typeof r.structuredContent === "object") r = r.structuredContent;
+  else if (r && typeof r === "object" && !r.report && Array.isArray(r.content) && textOf(r)) r = parse(textOf(r));
+  if (r && typeof r === "object" && r.isError) throw fail(textOf(r) || r.error);
+  if (r && typeof r === "object" && r.error) throw fail(r.error);
+  if (!r || typeof r !== "object" || !r.report || (!r.groups && !r.detail)) {
+    throw new Error("The answer is not a ReportResult: it has no report and no groups or detail.");
+  }
+  var columns = [];
+  var rows = [];
+  var unique = function (heading, fallback) {
+    return heading && columns.indexOf(heading) < 0 ? heading : fallback;
+  };
+  if (r.groups) {
+    var dims = r.groups.dimensions || [];
+    var meas = r.groups.measures || [];
+    var all = dims.concat(meas);
+    var heads = [];
+    all.forEach(function (c) {
+      var h = unique(c.label, c.name);
+      heads.push(h);
+      columns.push(h);
+    });
+    (r.groups.rows || []).forEach(function (row) {
+      var o = {};
+      heads.forEach(function (h, i) { o[h] = row[i]; });
+      rows.push(o);
+    });
+    var tm = (r.totals && r.totals.measures) || [];
+    var tv = (r.totals && r.totals.values) || [];
+    var total = {};
+    heads.forEach(function (h, i) { total[h] = i === 0 ? "Total" : ""; });
+    tm.forEach(function (name, i) {
+      var at = -1;
+      meas.forEach(function (m, j) { if (m.name === name) at = dims.length + j; });
+      if (at >= 0) total[heads[at]] = tv[i];
+    });
+    rows.push(total);
+  } else {
+    var cols = r.detail.columns || [];
+    cols.forEach(function (c) { columns.push(c.name); });
+    (r.detail.rows || []).forEach(function (row) {
+      var o = {};
+      cols.forEach(function (c, i) { o[c.name] = row[i]; });
+      rows.push(o);
+    });
+  }
+  var notes = Array.isArray(r.notes) ? r.notes : [];
+  var cut = !!(r.detail && r.detail.truncated === true) ||
+    notes.some(function (n) { return /\b(cut|truncated)\b|showing \d+ of \d+/i.test(String(n)); });
+  var meta = [];
+  if (r.report.url) meta.push({ label: "Report", value: String(r.report.url) });
+  (Array.isArray(r.filters) ? r.filters : []).forEach(function (f) { meta.push({ label: "Filter", value: String(f) }); });
+  notes.forEach(function (n) { meta.push({ label: "Note", value: String(n) }); });
+  return { columns: columns, rows: rows, cut: cut, meta: meta };
+}
+if (typeof module !== "undefined") module.exports = reportResultToRows;

package/skills/report-runner/reference.md CHANGED Viewed

@@ -40,6 +40,42 @@ Examples of slices, in the user's words:
 The server fixes two Salesforce quirks and says so in `notes`: it adds an aggregated column to the detail columns, and drops a grouped column from them.
+## Loader for a Claude Dashboard
+On the local door a dashboard to keep is built from attached result files. It is a copy as of the run (decision [0022](../../docs/decisions/0022-dashboard-from-attached-result-files.md)). Seen to work on 2026-11-11, not documented behaviour: JSON file datasets, one per report, each read by the loader below.
+**Make the files.** `npx -y salesforce-reports-mcp dashboard-files --org <alias> --defs <file.json> --out <dir>` runs report definitions read-only and writes one `ReportResult` file per definition. It is the subcommand of the installed server, so it needs no clone. Inside a clone of the repo, use `npm run dashboard-files -- --org <alias> --defs <file.json> --out <dir>` after `npm run build`. The defs file is a JSON object that maps a short id (letters, digits, dash and underscore) to `query_report` arguments, the definition fields at the top level. It prints `<id>: rows=<n> truncated=<bool>` for each file, or `<id>: failed`, and ends with `dashboard-files: written=<n> failed=<m>`. Exit codes: 0 when every report was written, 1 when any failed or the server could not be reached, 2 for a usage error. A single result already in the chat can be attached the same way, as a file.
+**Reshape each file.** The loader turns a `ReportResult` into plain rows:
+1. `groups.dimensions` and `groups.measures` are lists of objects. Their `name` values, dimensions first and then measures, name the cells of each row in `groups.rows`, in order. Zip each row with those names into one object per row, and use each `label` as the column heading.
+2. `totals.measures` and `totals.values` are two lists of the same length. Zip them into one more row, labelled "Total".
+3. A flat report has no `groups`: zip each row of `detail.rows` with the `name` of each entry in `detail.columns` instead, and say when `detail.truncated` is true.
+4. `filters` stay words. The report's own filters are shown as a caption or filter note, never as controls that would change the run. A page-side control may filter only rows already in the files, and never over a dataset whose `cut` is true, because its totals would be wrong.
+5. Carry `notes` and `report.url` through: show any note about cut rows, and keep the link to the report.
+The tested source is [dashboard-loader.js](dashboard-loader.js) in this folder. It is one function, `reportResultToRows({ answer })`, that runs alone. It returns `{columns, rows, cut, meta}` and throws the server's own words when the answer is an error. Do not rewrite it by hand. Paste it whole inside a wrapper and register the wrapper as each dataset's loader. The dashboard reads rows from `data`, so the wrapper returns them there:
+```
+function loadReport({ answer }) {
+  /* dashboard-loader.js pasted whole here */
+  var r = reportResultToRows({ answer: answer });
+  return { data: r.rows, columns: r.columns, cut: r.cut, meta: r.meta };
+}
+```
+Beyond the wrapper, follow the Dashboard type's own instructions.
+**Say it is a copy.** The page states that it is a copy and gives the date of the runs. To bring it up to date, run the reports again and attach the new files. A dashboard page cannot reach the local server, so it cannot re-run a report. Ask for design changes through the dashboard's comments to Claude.
+**Where `run_report` comes from a connector**, a live dataset is possible. Its source is a live call with nothing saved, and its `args` are the `query_report` input itself, the definition fields at the top level. This was not run from claude.ai and is untested.
+```
+{kind: 'call', connector, tool: 'query_report', args: {reportType, columns, groupingsDown, aggregates, filters, ...}}
+```
+Keep the run's input in the dashboard (the `reportId` and any `overrides`) so each refresh asks the same question. Check the shape of a real result before writing the loader.
 ## Limits
 - At most 2,000 detail rows and 100 columns per run, and 500 synchronous runs per org per hour. Prefer one grouped query over many small ones.