orgintel

An MCP server that analyzes Salesforce permission architecture — profiles, permission sets, and permission set groups — to support RBAC remediation. It reads an org, snapshots the permission model into a local DuckDB store, and answers questions about it. Phases 1–4 (acquisition, analysis core, eval harness, agent).

Two hard guarantees, both enforced as mechanism rather than policy:

• Read-only. orgintel never issues an insert, update, delete, or metadata deploy against any org. Enforced by a transport-layer route allowlist (see clients/transport.py); a non-allowlisted request raises before it is sent.
• No personal identifiers persisted. The users table has no name, username, or email column — the columns do not exist. soql_query masks identifier columns in its results. See DESIGN-P1.md §2.7.

Why it's built this way

A mid-size org has ~850k FieldPermissions rows — a raw dump is ~20M tokens, ~100× a context window. The model never sees raw API output. Every tool returns an aggregate, a diff, or a bounded slice; the join happens in DuckDB. Every response carries a budget that discloses truncation and how to narrow.

Setup

Requires uv and the Salesforce CLI (sf).

uv sync
uv run pytest        # 51 tests, no org needed

Auth (Phase 1: SFDX token reuse)

orgintel reads the access token from an org you've already authenticated with the Salesforce CLI — zero extra setup. JWT bearer flow is a planned seam, not yet built.

sf org login web --alias my-org      # once
sf org list                          # confirm it's Connected

The subprocess argv is fixed and its output (which contains a live token) is never logged.

Tools

Tool	What it returns
snapshot_org(org_alias, scope?)	Bulk-fetches the permission model into DuckDB. Returns summary stats only — counts, timing, snapshot_id.
list_snapshots()	Available snapshots, newest first.
list_profiles(snapshot_id)	Profiles by user count: license, perm cardinality, ModifyAllData flag, unassigned count.
describe_object(org_alias, api_name)	Live field list with a sensitivity_guess flag (SSN/DOB/account-number/… from config), sensitive fields first.
permission_diff(snapshot_id, principal_a, principal_b)	Symmetric difference of two principals. Differing fields grouped by (a_perm, b_perm) signature. The workhorse.
soql_query(org_alias, query, max_rows=200)	Read-only SOQL. SELECT-only parser guard, row cap, identifier columns redacted.
find_sensitive_access(snapshot_id)	(P2) Every principal granting read/edit on a name-matched sensitive field, with affected user counts resolved through effective permissions. Recall-first.
verify_decomposition(snapshot_id, proposal)	(P2) Formal check that a proposed base-profile + permission-set/group refactor leaves every user's effective permissions unchanged. Returns per-user added/removed grants; an uncovered user fails.
propose_decomposition(snapshot_id, threshold?, target_base_count?)	(P4) Computes a thin-base + permission-set decomposition (deterministic) and runs it through verify_decomposition before returning. If it doesn't preserve every user's access, you get the failure, not the proposal. Returns placeholder keys + member names + shared grants for the model to name.

scope defaults to all tables. Apex in SetupEntityAccess is excluded by default (84% of that table, ~noise for RBAC); pass "setup_entity_access:apex" to include it.

Two P2 functions — effective_permissions (union across profile + permission sets + PSG components, minus muting) and cluster_profiles (Jaccard clustering of profiles) — are internal building blocks, not yet exposed as tools. verify_decomposition is the crown jewel: permission-refactor correctness is formally checkable, so "did the refactor preserve access" is a boolean, not a judgement call — and propose_decomposition is gated by it, so an unverifiable proposal is never returned.

Agent (P4)

agent/ is an MCP client that drives these tools via the Anthropic API (claude-opus-5). The division of labor is the whole point: the tools compute and verify; the model orchestrates, names, and judges. propose_decomposition returns a verified structure with placeholder names; the model names each base in the customer's vocabulary and writes the rationale. The model also judges whether an unmatched field name looks sensitive (mbr_num__c, dob_enc__c) — the gap P3 measured as evasive recall.

uv sync --extra agent
orgintel-agent "snapshot appfoliosteph, then propose a decomposition"   # billable

The model call sits behind an LLM protocol, so the loop, tool bridge, and judge are all tested with a scripted fake — no API key, no billing. Only orgintel-agent makes real calls. uv run python -m evals.agent_delta measures the evasive-recall lift the judge buys (0.0 → 1.0 with the offline stand-in; detectable recall held at 1.0).

Register with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "orgintel": {
      "command": "uv",
      "args": ["run", "orgintel"],
      "cwd": "/Users/shaumikpathak/Downloads/MCP Salesforce"
    }
  }
}

Then in Claude: "Snapshot my-org, then show me the profiles with the most users, then diff the top two."

Eval harness (P3)

The highest-signal artifact in the project: a scoreboard for the deterministic analysis core, built before the agent so it develops against numbers, not vibes.

uv run python -m evals.run      # writes evals/REPORT.md + a run to evals/history/

fixtures/generate.py synthesizes org snapshots with planted ground truth (deterministic given a seed): latent roles, redundant pairs that should collapse, adversarial "do not consolidate" cases, and sensitive fields — some pattern-detectable, some named to evade (mbr_num__c, dob_enc__c). The harness scores cluster purity, sensitive-field recall (detectable target 1.0; evasive recall is the gap the P4 model must close, measured explicitly), and privilege preservation (verify_decomposition must certify a ground-truth decomposition and catch a broken one). Each run diffs against the previous, so a prompt or pattern change that drops recall shows up immediately.

Snapshot store

One DuckDB file, default ~/.orgintel/snapshots.db, override with ORGINTEL_DB. Set it per client engagement to keep each org's data in its own file. A snapshot holds principal/object/field metadata and pseudonymous user ids — re-identification requires authenticated access to the source org. Snapshot files are git-ignored.

Layout

src/orgintel/
  clients/     thin async SF wrappers (REST, Bulk 2.0, SFDX auth) — no DB, guarded transport
  store/       DuckDB schema (SQL migrations), ingest, queries, snapshot loader — no network
  analysis/    pure functions: diff, effective perms, clustering, sensitivity, verify, propose — no I/O
  agent/       MCP client + Anthropic-backed model (LLM protocol), tool loop, field judge
  config/      sensitivity.yaml (patterns + setup-entity scope)
  snapshot.py  the acquisition coordinator (auth -> fetch -> ingest)
  server.py    nine FastMCP tools — thin
fixtures/      deterministic synthetic orgs with planted ground truth (P3)
evals/         scoreboard: run.py (deterministic core) + agent_delta.py (P4 model lift)

See DESIGN-P1.md for the schema rationale and CLAUDE.md for conventions.