salesforce-reports-mcp 0.2.0 → 0.3.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.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +43 -29
- package/dist/reports/api.js +19 -0
- package/dist/reports/dashboards.js +308 -0
- package/dist/server.js +210 -3
- package/dist/widget/dashboard.html +946 -0
- package/dist/widget/report.html +722 -63
- package/dist/widget/view.js +32 -10
- package/package.json +4 -1
- package/skills/report-designer/transport.md +6 -2
- package/skills/report-runner/SKILL.md +11 -1
- package/skills/report-runner/transport.md +6 -2
package/dist/widget/view.js
CHANGED
|
@@ -2,27 +2,49 @@ import { readFileSync } from "node:fs";
|
|
|
2
2
|
import { createRequire } from "node:module";
|
|
3
3
|
/** The report view: one MCP App resource that draws a ReportResult from run_report or query_report. */
|
|
4
4
|
export const REPORT_VIEW_URI = "ui://salesforce-reports/report";
|
|
5
|
+
/** The dashboard view: a second MCP App resource that draws a DashboardResult from run_dashboard or refresh_dashboard. */
|
|
6
|
+
export const DASHBOARD_VIEW_URI = "ui://salesforce-reports/dashboard";
|
|
5
7
|
const BUNDLE_MARKER = "/*@ext-apps-bundle*/";
|
|
6
|
-
|
|
8
|
+
/** Where a template's <style> takes src/widget/tokens.css, the vendored SLDS token values (decision 0018). */
|
|
9
|
+
export const TOKENS_MARKER = "/*@slds-tokens*/";
|
|
10
|
+
/** Put the token CSS in place of the marker. scripts/build-widget.ts does this at build, so dist has no marker. */
|
|
11
|
+
export function inlineTokens(template, tokens) {
|
|
12
|
+
if (!template.includes(TOKENS_MARKER))
|
|
13
|
+
throw new Error("The view template has no place for the SLDS tokens.");
|
|
14
|
+
return template.replace(TOKENS_MARKER, () => tokens.trim());
|
|
15
|
+
}
|
|
16
|
+
const cached = new Map();
|
|
7
17
|
/**
|
|
8
|
-
* The view as one self-contained HTML document: the template (inline CSS and view script) with the
|
|
18
|
+
* The report view as one self-contained HTML document: the template (inline CSS and view script) with the
|
|
9
19
|
* ext-apps browser client inlined, so the host needs no network and no csp allowlist.
|
|
10
20
|
* When a file is missing it returns a small document that says so; the server keeps running.
|
|
11
21
|
*/
|
|
12
22
|
export function reportViewHtml() {
|
|
13
|
-
|
|
14
|
-
|
|
23
|
+
return viewHtml("report.html", "Report");
|
|
24
|
+
}
|
|
25
|
+
/** The dashboard card, built the same way as the report view from dashboard.html. */
|
|
26
|
+
export function dashboardViewHtml() {
|
|
27
|
+
return viewHtml("dashboard.html", "Dashboard");
|
|
28
|
+
}
|
|
29
|
+
function viewHtml(file, what) {
|
|
30
|
+
const hit = cached.get(file);
|
|
31
|
+
if (hit)
|
|
32
|
+
return hit;
|
|
15
33
|
try {
|
|
16
|
-
|
|
34
|
+
let template = readFileSync(new URL(`./${file}`, import.meta.url), "utf8");
|
|
35
|
+
// A template read from src (tests, tsx) still has the marker; a built one already carries the tokens.
|
|
36
|
+
if (template.includes(TOKENS_MARKER))
|
|
37
|
+
template = inlineTokens(template, readFileSync(new URL("./tokens.css", import.meta.url), "utf8"));
|
|
17
38
|
const bundlePath = createRequire(import.meta.url).resolve("@modelcontextprotocol/ext-apps/app-with-deps");
|
|
18
39
|
const bundle = inlineBundle(readFileSync(bundlePath, "utf8"));
|
|
19
40
|
if (!template.includes(BUNDLE_MARKER))
|
|
20
41
|
throw new Error("The view template has no place for the ext-apps client.");
|
|
21
|
-
|
|
22
|
-
|
|
42
|
+
const html = template.replace(BUNDLE_MARKER, () => bundle);
|
|
43
|
+
cached.set(file, html);
|
|
44
|
+
return html;
|
|
23
45
|
}
|
|
24
46
|
catch (error) {
|
|
25
|
-
return missingView(error instanceof Error ? error.message : String(error));
|
|
47
|
+
return missingView(what, error instanceof Error ? error.message : String(error));
|
|
26
48
|
}
|
|
27
49
|
}
|
|
28
50
|
/**
|
|
@@ -44,7 +66,7 @@ export function inlineBundle(bundle) {
|
|
|
44
66
|
const body = bundle.slice(0, match.index).replace(/<\/script/gi, "<\\/script");
|
|
45
67
|
return `const ExtApps = (() => {\n${body}\nreturn {${entries.join(",")}};\n})();`;
|
|
46
68
|
}
|
|
47
|
-
function missingView(reason) {
|
|
69
|
+
function missingView(what, reason) {
|
|
48
70
|
const safe = reason.replace(/[&<>"]/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """ })[c]);
|
|
49
|
-
return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title
|
|
71
|
+
return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${what} view unavailable</title></head><body><p>The ${what.toLowerCase()} view is not available in this install: ${safe} The text result is unchanged.</p></body></html>`;
|
|
50
72
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "salesforce-reports-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "MCP server to find, define, run, save and combine Salesforce reports through the Reports and Dashboards REST API",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"salesforce",
|
|
@@ -33,18 +33,21 @@
|
|
|
33
33
|
},
|
|
34
34
|
"scripts": {
|
|
35
35
|
"build": "tsc && tsx scripts/build-widget.ts",
|
|
36
|
+
"typecheck": "tsc -p tsconfig.check.json",
|
|
36
37
|
"test": "vitest run",
|
|
37
38
|
"test:render": "playwright test",
|
|
38
39
|
"live": "tsx scripts/live-check.ts",
|
|
39
40
|
"parity": "tsx scripts/parity-check.ts",
|
|
40
41
|
"capture": "tsx scripts/capture-fixtures.ts",
|
|
41
42
|
"prepare": "npm run build",
|
|
43
|
+
"mcp-login": "tsx scripts/mcp-login.ts",
|
|
42
44
|
"mcp-check": "tsx scripts/mcp-check.ts",
|
|
43
45
|
"mcp:generate": "tsx salesforce/scripts/generate-metadata.ts",
|
|
44
46
|
"mcp:setup": "tsx salesforce/scripts/mcp-setup.ts",
|
|
45
47
|
"mcp:teardown": "tsx salesforce/scripts/mcp-teardown.ts",
|
|
46
48
|
"callout:setup": "tsx salesforce/scripts/callout-setup.ts",
|
|
47
49
|
"callout:renew": "tsx salesforce/scripts/callout-setup.ts --renew-certificate",
|
|
50
|
+
"verify": "tsx scripts/verify.ts",
|
|
48
51
|
"demo:gif": "tsx scripts/demo-gif.ts"
|
|
49
52
|
},
|
|
50
53
|
"dependencies": {
|
|
@@ -31,7 +31,7 @@ The `sf` CLI signs the request with the org's stored session. Never fetch, print
|
|
|
31
31
|
|
|
32
32
|
## Tools on the REST door
|
|
33
33
|
|
|
34
|
-
The door has
|
|
34
|
+
The door has fifteen tools.
|
|
35
35
|
|
|
36
36
|
Over MCP the tool schema tells you the input fields. Here it does not, so use these names exactly. The definition fields are `reportType`, `format`, `columns`, `groupingsDown`, `groupingsAcross`, `aggregates`, `filters`, `filterLogic`, `dateFilter`, `sortBy`, `topRows`, `scope` and `reportMetadata`, with the shapes in `reference.md`. The result controls are `detail` and `maxRows`.
|
|
37
37
|
|
|
@@ -45,9 +45,13 @@ Over MCP the tool schema tells you the input fields. Here it does not, so use th
|
|
|
45
45
|
| `run_report` | read | **`reportId`**, `overrides` (any definition fields, for this run only), `detail`, `maxRows` |
|
|
46
46
|
| `query_report` | read, calls the org's REST API from inside the org | **`reportType`**, the definition fields, `detail`, `maxRows` |
|
|
47
47
|
| `combine_reports` | read | **`mode`** (`stack` or `join`), **`inputs`** (2 to 5 of `{alias, reportId, overrides}` or `{alias, definition}`), `joinOn`, `detail`, `maxRows` |
|
|
48
|
+
| `list_dashboards` | read | `query`, `folder`, `limit` |
|
|
49
|
+
| `describe_dashboard` | read, calls the org's REST API from inside the org | **`dashboardId`** |
|
|
50
|
+
| `run_dashboard` | read, calls the org's REST API from inside the org | **`dashboardId`**, `filters` (`[{name, option}]`, from `describe_dashboard`), `maxRows` |
|
|
48
51
|
| `create_report` | save, needs the write permission | **`name`**, `description`, `folderId`, `fromReportId`, the definition fields (`reportType` when there is no `fromReportId`) |
|
|
49
52
|
| `update_report` | save, needs the write permission | **`reportId`**, `name`, `description`, `folderId`, the definition fields to change |
|
|
50
53
|
| `clone_report` | save, needs the write permission | **`reportId`**, `name`, `folderId` |
|
|
54
|
+
| `refresh_dashboard` | write, needs the write permission; waits up to about 30 seconds | **`dashboardId`**, `filters`, `maxRows` |
|
|
51
55
|
|
|
52
56
|
Deleting a report is not on this door. It answers 404 `UNKNOWN_TOOL`. Deleting needs the local MCP server started with `--allow-delete`, or Salesforce itself.
|
|
53
57
|
|
|
@@ -68,7 +72,7 @@ Act on `code`:
|
|
|
68
72
|
| Code | Means | Do |
|
|
69
73
|
| --- | --- | --- |
|
|
70
74
|
| `INVALID_INPUT`, or a Salesforce error code | The input is wrong, often a column name | Fix the input from `message` and `hint` and try once more, as the skill says. |
|
|
71
|
-
| `WRITE_NOT_ALLOWED` (HTTP 403) | The user lacks the write permission for saves | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
75
|
+
| `WRITE_NOT_ALLOWED` (HTTP 403) | The user lacks the write permission for saves and dashboard refreshes | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
72
76
|
| `CALLOUT_SESSION` | The door could not call the org's own REST API under this sign-in. On the hosted MCP server, the org lacks the optional callout package | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
73
77
|
| `CALLOUT_CREDENTIAL` | On the hosted MCP server, the org has the callout package, but this user lacks its permission set (the `hint` names it) or its token failed | A refusal. Do not retry. Follow the skill's refusal steps for `CALLOUT_SESSION`, and pass on the `hint`. |
|
|
74
78
|
| `CALLOUT_FAILED`, `RESULT_TOO_LARGE` | The run was too big or too slow inside the org | Narrow it (fewer columns, a tighter date range, no detail rows) and try once. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: report-runner
|
|
3
|
-
description: Explore data and answer questions from Salesforce reports that already exist. Use when the user asks what is in a report, asks for a number a report could give (pipeline, bookings, forecast, win rate, activity), asks why a number moved, or wants a saved report cut another way (by owner, last quarter instead, without closed deals) to look at. This skill reads and never saves. For changing a report or making a new one, use report-designer. For moving a report between orgs or into git, use report-deploy.
|
|
3
|
+
description: Explore data and answer questions from Salesforce reports and dashboards that already exist. Use when the user asks what is in a report or a dashboard, asks for a number a report could give (pipeline, bookings, forecast, win rate, activity), asks why a number moved, or wants a saved report cut another way (by owner, last quarter instead, without closed deals) to look at. This skill reads and never saves; it refreshes a dashboard only when the user says yes. For changing a report or making a new one, use report-designer. For moving a report between orgs or into git, use report-deploy.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Answering from Salesforce reports
|
|
@@ -17,6 +17,7 @@ The tools named below may come from any door: the local MCP server, the hosted M
|
|
|
17
17
|
- No match: say so, then use `query_report` to answer the question without a saved report (see "No saved report" below), and offer to save it afterwards.
|
|
18
18
|
2. **Say what it counts before you run it.** Call `describe_report`. Then give one or two plain sentences: what each row or group is, grouped by what, over which dates, and for whom. Scope matters ("only your opportunities"). Name silent defaults ("it only counts deals closing this fiscal quarter, because that is the default date range"). Read `filters` in the result for this; see `reference.md`.
|
|
19
19
|
3. **Run it and lead with the answer.** Call `run_report`. Say the headline first: the total and the biggest movers. Then the group table, at most about 10 rows inline, ranked. Then anything odd: an empty group, one deal carrying a stage, rows that were cut.
|
|
20
|
+
- **Card or no card.** Where the host draws the result as a report card above your reply (Claude Desktop and other hosts that draw MCP Apps), lead with the one finding the card cannot show (concentration, change, risk, the next question), keep the reply short, and never repeat the card's rows, totals or a table. Without a card, give the headline and the group table as above.
|
|
20
21
|
4. **Offer the next slice.** Give two or three concrete follow-ups in the user's words, such as "by owner", "last quarter instead" or "without closed deals". Each becomes a `run_report` with `overrides`, which changes that run only. Take the column for a new slice from `describe_report_type` with a `search` word ("owner" finds `FULL_NAME` on Opportunity); a guessed name such as `OWNER` fails. Comparisons go through `combine_reports`: `stack` for this period against last, `join` for two measures by the same dimension.
|
|
21
22
|
5. **Always give the report link** from the result, and say when numbers are partial.
|
|
22
23
|
|
|
@@ -24,6 +25,15 @@ The tools named below may come from any door: the local MCP server, the hosted M
|
|
|
24
25
|
|
|
25
26
|
When no report fits, or the user wants a number cut a way no saved report does, use `query_report`. It defines the report in the call and saves nothing. Find the `reportType` with `list_report_types`, then the column names with `describe_report_type` (give it a `search` word). Never guess column names. The definition grammar is in `reference.md`. If the user likes the result and wants it kept, say you can save it as a report. Do not save it yourself; that is a different job and needs their yes. If `query_report` is not offered or answers `CALLOUT_SESSION`, follow "When the org refuses" below.
|
|
26
27
|
|
|
28
|
+
## Dashboards
|
|
29
|
+
|
|
30
|
+
Reach for a dashboard tool instead of a report run when the user names a dashboard ("the pipeline dashboard"), or asks for the set of figures a dashboard already gathers ("how does the board look this week"). For one number, or a cut no dashboard has, stay with reports: a report run is live and takes `overrides`; a dashboard shows what Salesforce cached at its last refresh. The dashboard tools are on every door.
|
|
31
|
+
|
|
32
|
+
1. **Find it** with `list_dashboards` and the user's words. Pick or ask as for reports.
|
|
33
|
+
2. **Learn its filters** with `describe_dashboard` when the user wants a slice ("only Prospecting"). Filters are chosen by name and option label, and only from the options the dashboard offers. For any other cut, run the source report a component names with `run_report` and `overrides`.
|
|
34
|
+
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`.
|
|
35
|
+
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.
|
|
36
|
+
|
|
27
37
|
## Never save
|
|
28
38
|
|
|
29
39
|
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.
|
|
@@ -31,7 +31,7 @@ The `sf` CLI signs the request with the org's stored session. Never fetch, print
|
|
|
31
31
|
|
|
32
32
|
## Tools on the REST door
|
|
33
33
|
|
|
34
|
-
The door has
|
|
34
|
+
The door has fifteen tools.
|
|
35
35
|
|
|
36
36
|
Over MCP the tool schema tells you the input fields. Here it does not, so use these names exactly. The definition fields are `reportType`, `format`, `columns`, `groupingsDown`, `groupingsAcross`, `aggregates`, `filters`, `filterLogic`, `dateFilter`, `sortBy`, `topRows`, `scope` and `reportMetadata`, with the shapes in `reference.md`. The result controls are `detail` and `maxRows`.
|
|
37
37
|
|
|
@@ -45,9 +45,13 @@ Over MCP the tool schema tells you the input fields. Here it does not, so use th
|
|
|
45
45
|
| `run_report` | read | **`reportId`**, `overrides` (any definition fields, for this run only), `detail`, `maxRows` |
|
|
46
46
|
| `query_report` | read, calls the org's REST API from inside the org | **`reportType`**, the definition fields, `detail`, `maxRows` |
|
|
47
47
|
| `combine_reports` | read | **`mode`** (`stack` or `join`), **`inputs`** (2 to 5 of `{alias, reportId, overrides}` or `{alias, definition}`), `joinOn`, `detail`, `maxRows` |
|
|
48
|
+
| `list_dashboards` | read | `query`, `folder`, `limit` |
|
|
49
|
+
| `describe_dashboard` | read, calls the org's REST API from inside the org | **`dashboardId`** |
|
|
50
|
+
| `run_dashboard` | read, calls the org's REST API from inside the org | **`dashboardId`**, `filters` (`[{name, option}]`, from `describe_dashboard`), `maxRows` |
|
|
48
51
|
| `create_report` | save, needs the write permission | **`name`**, `description`, `folderId`, `fromReportId`, the definition fields (`reportType` when there is no `fromReportId`) |
|
|
49
52
|
| `update_report` | save, needs the write permission | **`reportId`**, `name`, `description`, `folderId`, the definition fields to change |
|
|
50
53
|
| `clone_report` | save, needs the write permission | **`reportId`**, `name`, `folderId` |
|
|
54
|
+
| `refresh_dashboard` | write, needs the write permission; waits up to about 30 seconds | **`dashboardId`**, `filters`, `maxRows` |
|
|
51
55
|
|
|
52
56
|
Deleting a report is not on this door. It answers 404 `UNKNOWN_TOOL`. Deleting needs the local MCP server started with `--allow-delete`, or Salesforce itself.
|
|
53
57
|
|
|
@@ -68,7 +72,7 @@ Act on `code`:
|
|
|
68
72
|
| Code | Means | Do |
|
|
69
73
|
| --- | --- | --- |
|
|
70
74
|
| `INVALID_INPUT`, or a Salesforce error code | The input is wrong, often a column name | Fix the input from `message` and `hint` and try once more, as the skill says. |
|
|
71
|
-
| `WRITE_NOT_ALLOWED` (HTTP 403) | The user lacks the write permission for saves | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
75
|
+
| `WRITE_NOT_ALLOWED` (HTTP 403) | The user lacks the write permission for saves and dashboard refreshes | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
72
76
|
| `CALLOUT_SESSION` | The door could not call the org's own REST API under this sign-in. On the hosted MCP server, the org lacks the optional callout package | A refusal. Do not retry. Follow the skill's refusal steps. |
|
|
73
77
|
| `CALLOUT_CREDENTIAL` | On the hosted MCP server, the org has the callout package, but this user lacks its permission set (the `hint` names it) or its token failed | A refusal. Do not retry. Follow the skill's refusal steps for `CALLOUT_SESSION`, and pass on the `hint`. |
|
|
74
78
|
| `CALLOUT_FAILED`, `RESULT_TOO_LARGE` | The run was too big or too slow inside the org | Narrow it (fewer columns, a tighter date range, no detail rows) and try once. |
|