sf-intelligence 0.3.1 → 0.3.3

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 (4) hide show
  1. package/README.md +77 -56
  2. package/dist/index.js +27603 -8334
  3. package/package.json +1 -1
  4. package/server.json +13 -2
package/README.md CHANGED
@@ -1,105 +1,126 @@
1
1
  # sf-intelligence
2
2
 
3
- A **grounded, fail-closed backend for AI assistants** working in one Salesforce
4
- org — answers come from the org's **real metadata**, not a guess.
5
-
6
- `sf-intelligence` is an **offline-first, read-only, MCP-first knowledge base**
7
- for a single Salesforce org. You run one `sf project retrieve`; it builds a local
8
- Markdown vault and a DuckDB dependency graph, then answers questions locally
9
- through an MCP server (the `sfi.*` tools) — no network egress for vault answers.
10
- It is not a standalone chatbot: a semantic router **advises** — it turns each
11
- plain-language question into a meaning-ranked shortlist of the `sfi.*` tools
12
- that can answer it, tagged with the plane it needs (offline vault / opt-in live
13
- / hybrid) and a confidence band — and your **host LLM decides** which tools to
14
- run. It **fails closed**: write imperatives, prompt injection, and
15
- record-value exfiltration are refused by shape (with a read-only alternative
16
- offered), unanswerable asks get an honest gap instead of a lookalike tool, and
17
- genuine ambiguity gets a clarifying question instead of a guess. Terse
18
- follow-ups resolve through an optional host-passed `context.previous` param —
19
- the server itself stores no conversation state. An opt-in live read-only plane
20
- can answer record counts and samples. MIT + Commons Clause.
3
+ A **grounded, fail-closed backend for AI assistants** working in one Salesforce org — answers come from the org's **real metadata**, not a guess.
4
+
5
+ `sf-intelligence` is an **offline-first, read-only, MCP-first knowledge base** for a single Salesforce org. One `sf project retrieve` builds a local vault (Markdown + a DuckDB dependency graph); a semantic router **advises** a ranked tool shortlist and your **host LLM decides** which to run. It **fails closed** — write imperatives and prompt injection are refused by shape, an unanswerable ask gets an honest gap instead of a lookalike tool, and genuine ambiguity gets a clarifying question instead of a guess. MIT + Commons Clause.
6
+
7
+ Requires **Node.js 20+**. `npx -y sf-intelligence …` needs no install; `npm install -g sf-intelligence` puts `sfi` on your PATH for shorter commands.
21
8
 
22
9
  ## Upgrading to 0.3.0 (breaking)
23
10
 
24
- 0.3.0 changes defaults. If you are coming from 0.2.x, read this before upgrading —
25
- full detail in [CHANGELOG.md](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/CHANGELOG.md).
11
+ Coming from 0.2.x? Read this first — full detail in
12
+ [CHANGELOG.md](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/CHANGELOG.md).
26
13
 
27
- - **`SFI_TOOL_PROFILE` now defaults to `core`.** 19 tools are advertised and
28
- directly invokable; the other ~190 are reached with
29
- `sfi.run_analysis { name: 'sfi.<tool>', args }`. Set `SFI_TOOL_PROFILE=full`
30
- to restore the previous advertise-and-invoke-everything behavior.
31
- - **`liveEnabled: true` no longer opens the live plane.** Grant standing consent
32
- with `sfi.live_consent { grant: true }` (OrgId + principal bound, scoped,
33
- 7-day expiry) or set `SFI_LIVE_PLANE_ENABLED=1`.
34
- - **Existing on-disk live grants stop working** — v1 consent records are dropped.
35
- Re-grant once.
36
- - **The update check is now opt-in.** Set `SFI_UPDATE_CHECK=1` (default network
37
- mode is `off`).
38
- - **Every success envelope gains a `contentPolicy` block** (~280 bytes) marking
39
- org metadata as untrusted data for hosts.
14
+ - **`SFI_TOOL_PROFILE` now defaults to `core`.** 25 tools are advertised and
15
+ directly invokable; the rest are reached via
16
+ `sfi.run_analysis { name: 'sfi.<tool>', args }`. `SFI_TOOL_PROFILE=full`
17
+ restores advertise-and-invoke-everything.
18
+ - **`liveEnabled: true` no longer opens the live plane.** Grant standing
19
+ consent with `sfi.live_consent { grant: true }` or set
20
+ `SFI_LIVE_PLANE_ENABLED=1` — existing on-disk live grants stop working, so
21
+ re-grant once.
22
+ - **The update check is now opt-in** (`SFI_UPDATE_CHECK=1`), and every
23
+ success envelope gains a `contentPolicy` block marking org metadata as
24
+ untrusted data for hosts.
40
25
 
41
- ## Install
26
+ ## Try it now — no Salesforce org needed
42
27
 
43
- Requires **Node.js 20+** and an authenticated **Salesforce CLI** (`sf`).
28
+ One command serves a built-in **synthetic demo org** ("Verdant Energy," a fictional solar installer) over MCP — fully offline, no auth, no `sf` CLI, builds in a few seconds:
44
29
 
45
30
  ```sh
46
- npm install -g sf-intelligence
31
+ claude mcp add --transport stdio --scope user sf-intelligence-demo -- npx -y sf-intelligence demo
47
32
  ```
48
33
 
49
- (or run it ad hoc with `npx -y sf-intelligence …` — no global install needed)
34
+ Any other MCP client — same registration as the "real org" block below, except `"args": ["-y", "sf-intelligence", "demo"]` and **no `--vault`**: `sfi demo` manages its own cached vault under `~/.sf-intelligence/demo`. Ask it *"what happens when I save a Project?"* or *"what breaks if I delete `Invoice__c.Amount__c`?"*. When you're ready for your own org, keep reading.
35
+
36
+ ## Register the MCP server (your real org)
50
37
 
51
- ## Register the MCP server
38
+ Also requires an authenticated **Salesforce CLI** (`sf`). Each host reads a **different config file in a different format**, and most don't run inside your Salesforce project — always pass an **absolute `--vault` path**. Full per-host, per-platform detail (exact paths, logs, troubleshooting): [docs/guides/mcp-hosts.md](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/docs/guides/mcp-hosts.md).
52
39
 
53
- **Claude Code** (from your Salesforce DX repo):
40
+ | Host | Config file | Top-level key |
41
+ |---|---|---|
42
+ | Claude Code | `.mcp.json` (project) or `~/.claude.json` | `mcpServers` |
43
+ | Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
44
+ | Cursor | `.cursor/mcp.json` | `mcpServers` |
45
+ | Codex | `~/.codex/config.toml` | `[mcp_servers.*]` (TOML) |
46
+ | VS Code + GitHub Copilot | `.vscode/mcp.json` | **`servers`** — not `mcpServers` |
47
+
48
+ **Claude Code** — from your Salesforce DX repo:
54
49
 
55
50
  ```sh
56
- claude mcp add --transport stdio --scope project sf-intelligence -- npx -y sf-intelligence mcp
51
+ claude mcp add --scope project sf-intelligence -- \
52
+ npx -y sf-intelligence mcp --vault "$PWD/org-kb"
57
53
  ```
58
54
 
59
- **Claude Desktop, or any other MCP client** — add to the client's MCP config:
55
+ **Claude Desktop, Cursor, or any `mcpServers`-style client** — add to its config, then fully restart the app:
60
56
 
61
57
  ```json
62
58
  {
63
59
  "mcpServers": {
60
+ "sf-intelligence": {
61
+ "command": "npx",
62
+ "args": ["-y", "sf-intelligence", "mcp", "--vault", "/abs/path/to/org-kb"]
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ **VS Code + GitHub Copilot** — create `.vscode/mcp.json`. The top-level key is `servers`, **not** `mcpServers` — pasting the block above here parses fine and registers nothing:
69
+
70
+ ```json
71
+ {
72
+ "servers": {
64
73
  "sf-intelligence": {
65
74
  "type": "stdio",
66
75
  "command": "npx",
67
- "args": ["-y", "sf-intelligence", "mcp"]
76
+ "args": ["-y", "sf-intelligence", "mcp", "--vault", "/abs/path/to/org-kb"]
68
77
  }
69
78
  }
70
79
  }
71
80
  ```
72
81
 
82
+ **Codex** — `codex mcp add sf-intelligence -- npx -y sf-intelligence mcp --vault /abs/path/to/org-kb`
83
+ (or the TOML equivalent in `~/.codex/config.toml`).
84
+
73
85
  ## First run
74
86
 
75
87
  From your Salesforce DX repo (the directory with `sfdx-project.json`):
76
88
 
77
89
  ```sh
78
- sfi init # create the local org-kb/ vault
79
- sfi refresh --target-org my-org-alias # retrieve metadata, build the vault
80
- sfi status # freshness, source-tree hash, counts
81
- sfi doctor # diagnose sf CLI / vault / auth issues
90
+ sfi init --target-org my-org-alias # create the vault, bind it to one org
91
+ sfi refresh --target-org my-org-alias # retrieve metadata, build the vault
92
+ sfi status # freshness, source-tree hash, counts
93
+ sfi doctor # diagnose sf CLI / vault / auth issues
82
94
  ```
83
95
 
84
- Then ask anything in your MCP client — *"what fields does Account have?"*,
85
- *"what breaks if I delete this field?"*, *"why can't this profile see
86
- Opportunities?"*, *"give me a tour of this org."*
96
+ `--target-org` is **required** on `sfi init` whenever stdin isn't a terminal — which includes every MCP host, so always pass it there.
97
+
98
+ Then ask anything in your MCP client — *"what fields does Account have?"*, *"what breaks if I delete this field?"*, *"who can edit Salary__c?"*, *"why can't this profile see Opportunities?"*, *"what happens when I save a Project?"*, *"give me a tour of this org."*
99
+
100
+ **Connected, but the org looks empty?** Before the first `sfi refresh` finishes, the server boots in setup mode and exposes exactly one tool, `sfi.setup_status` — ask your chat "what do you need from me?" and it will name the exact next command (and where it's looking for the vault).
87
101
 
88
102
  ## Boundaries
89
103
 
90
- Read-only and offline by default. Static analysis, not runtime. No business
91
- record data in the vault. The product names its limits plainly rather than
92
- guessing.
104
+ Read-only and offline by default. Static analysis, not runtime. No business record data in the vault. The product names its limits plainly rather than guessing.
105
+
106
+ ## Feedback
107
+
108
+ A weak or wrong answer, or a question it couldn't route — that's the most useful thing to send back. It's captured **locally**, nothing phones home:
109
+
110
+ ```sh
111
+ sfi feedback mark "where is the SSN field used" --wrong # or --weak
112
+ sfi feedback export # → sfi-feedback.json (scrubbed)
113
+ ```
114
+
115
+ Share it, or just describe the gap, at <https://github.com/PranavNagrecha/Salesforce-Intelligence/issues>.
93
116
 
94
117
  ## Documentation
95
118
 
96
- Full guides, capabilities, the tool catalog, and configuration:
97
- **https://sfi.auditforce.cloud**
119
+ Full guides, capabilities, the tool catalog, and configuration: **https://sfi.auditforce.cloud**
98
120
 
99
- - [Getting started](https://sfi.auditforce.cloud/getting-started.html)
121
+ - [Getting started](https://sfi.auditforce.cloud/getting-started.html) · [Quality & trust](https://sfi.auditforce.cloud/trust.html)
100
122
  - [Capabilities](https://sfi.auditforce.cloud/capabilities.html) · [All tools](https://sfi.auditforce.cloud/tools.html)
101
123
  - [Configuration](https://sfi.auditforce.cloud/configuration.html) · [FAQ](https://sfi.auditforce.cloud/faq.html)
102
- - [Quality & trust](https://sfi.auditforce.cloud/trust.html)
103
124
 
104
125
  ## License
105
126