salesforce-reports-mcp 0.2.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-reports",
-  "version": "0.2.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

@@ -1,29 +1,30 @@
 # salesforce-reports-mcp
 
-Claude finds, builds, runs and saves Salesforce reports. You ask a question in plain words and get the answer, with the report behind it.
+[![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. It takes one useful job, reports, and delivers it to Claude three ways, from a server on your laptop to a feature that lives inside Salesforce. 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.**
 
-> **You:** List the report types I can build on, then build me an opportunity report grouped by stage without saving it.
+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:** The org has 156 report types; here they are by category. Opportunities by stage: 8 open deals, $3,091,000. Negotiation/Review holds 3 of them and 39% of the value. Salesforce applied its default filters: close date this fiscal quarter, probability above 0. Nothing was saved. Want it across all close dates, or saved to your Private Reports?
+> **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.ai, through the MCP server hosted by Salesforce, signed in as the user ([rehearsal](docs/rehearsals/runner-hosted.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)
 
-## What this repo shows
+## The answers are in Salesforce. Most people cannot get them out.
 
-| Claim | Where to look | Evidence you can check |
-| --- | --- | --- |
-| **1. Three ways to connect Salesforce and Claude**, each with its own trade-offs | [Three ways to connect](#three-ways-to-connect) | One tool contract and result shape on every door (12 tools locally, 11 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; 65 Apex tests at 98% 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), [6 probes](docs/probes/) before building, [14 decision records](docs/decisions/README.md), [live findings](docs/design.md), [7 rehearsals](docs/rehearsals/README.md) |
+**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.**
 
-## The product
+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.
 
-**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 jobs, done by asking
 
-**Three experiences.** Each is a Claude skill, and Claude picks the right one from what you say.
+**The person with the question gets the answer. No one waits on the one colleague who knows Report Builder.**
+
+Each is a Claude skill, and Claude picks the right one from what you say.
 
 | Skill | For | What Claude does |
 | --- | --- | --- |
@@ -35,129 +36,110 @@ This repo is working software, and a demonstration. It takes one useful job, rep
 >
 > **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.** In Claude Desktop, a report run on the local server also draws as a card the way Salesforce draws it: the title, the filters, the groups with totals, a link to open it in Salesforce and, for an unsaved report, a button that asks Claude to save it. It is an MCP App that loads nothing from the network. 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)).
-
-![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)
+## Numbers you can repeat in a meeting
 
-*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
+**Every answer says what was counted, what was filtered and what was left out, so nobody presents a number they cannot explain.**
 
-## Three ways to connect
-
-The same tools reach Claude three ways. 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
-```
+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.
 
-| | 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 12, delete only with a flag | 11, no delete | 11, no delete |
-| **Choose it when** | One person, no org change allowed | An admin wants the feature in the org, used from scripts and agents | A team wants Claude in the browser, governed by the org |
+## The answer arrives as a picture
 
-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 the sequence diagrams.
+**In Claude Desktop the result draws as a card in the chat: the headline, the filters, the groups and a button to save it.**
 
-## A feature inside Salesforce
+Salesforce dashboards draw the same way, every component as its own chart.
 
-The in-org doors 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)):
+![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)
 
-| 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 |
+*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
 
-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)).
+Claude can find a Salesforce dashboard, read the numbers Salesforce last cached and refresh it when the data is old.
 
-## Security and identity
+## Then keep it as a Claude dashboard
 
-Each door signs in differently, and each is least privilege by default.
+**Ask for a dashboard, and Claude turns the report it just ran into a page you can keep and share.**
 
-| 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. |
+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.
 
-Sharing, folder access and field-level security apply on every door, because every call runs as the user.
+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.
 
-**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:
+## What you need, and what you do not
 
-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.
+**No new licence and no install in Salesforce. A person who can already run reports and use the Salesforce CLI can start asking.**
 
-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.
+You need:
 
-## How it was built
+- 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.
 
-The method was the same for every feature: probe the platform, decide in writing, build, then check against a real org.
+If your company restricts API access or the Salesforce CLI, that is the question to take to your admin.
 
-| Step | What it produced |
+| It does not need | Because |
 | --- | --- |
-| **Probe** before building | [6 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 |
-| **Decide** in writing | [14 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 | 161 unit and server tests, 8 render tests that draw the report card in a browser, 65 Apex tests, a live end-to-end check that leaves no report behind, and a parity check across doors |
-| **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 |
+| 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 |
 
-## Get started
+## Run it on your own org
 
-| You want | Start here |
-| --- | --- |
-| Claude Code or Desktop on your own org, nothing installed in Salesforce | [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) |
+**Two commands, and Claude is working on your own data.**
 
-The quickest try is the Claude Code plugin, which bundles the skills and the local server:
+Run them 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
 ```
 
-The tools, the result shape, the safety rails and the limits are in [docs/reference.md](docs/reference.md).
+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.
 
-## Develop
+Then ask:
 
-```
-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)
-```
+- "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.
 
-`npm run live` creates several private reports named `zz-live-check-*`, deletes them, and fails if any remain. Use a sandbox or scratch org.
+## 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
 
-- Dashboards: list, describe, refresh, and read component data.
-- 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

@@ -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;
+}