# Saudi Hosting Review — local developer beta

Paths such as `examples/`, `docs/` and `SECURITY.md` refer to files inside the installed tarball.

Version **0.1.0-beta.2** · [العربية](README.ar.md) · Independent advisory software from Aziz Al Khunizan / azizme.com. No certification or badge issuance. Built locally; public distribution and marketplace installation are separate release decisions.

The CLI and stdio MCP server share a bounded static scanner and the website's deterministic engines. Outputs contain allowlisted SDK/region hints, relative file references, coverage, separate regulatory applicability and four proposed-scope assessments, data-journey candidates and provider questions. When AI is referenced or declared, a seven-stage supply-chain table covers inference/fallback, embeddings/retrieval, moderation, agent tools, traces/abuse logs, retention and training; stage use and geography remain unknown until separately evidenced. Unknown means unknown. The scanner cannot establish production locations, contracts, subprocessors or foreign access.

## Install and inspect before connecting an AI client

Requires **Node.js 22 or newer**. Download the versioned tarball and SHA256SUMS.txt from the developer page, compare the SHA-256, and inspect the contents. On Windows, use `Get-FileHash -Algorithm SHA256 -LiteralPath "C:\Downloads\azizme-saudi-hosting-review-0.1.0-beta.2.tgz"`; on macOS/Linux use `shasum -a 256` or `sha256sum`. Create a tool folder separate from the project you want to review. The following is an example, not a command to install into your application:

```powershell
node --version
New-Item -ItemType Directory -Path 'C:\Tools\saudi-hosting-review'
Set-Location -LiteralPath 'C:\Tools\saudi-hosting-review'
npm init -y
npm install --ignore-scripts --no-audit --no-fund 'C:\Downloads\azizme-saudi-hosting-review-0.1.0-beta.2.tgz'
node 'C:\Tools\saudi-hosting-review\node_modules\@azizme\saudi-hosting-review\dist\cli.js' list --root 'C:\Projects\my-app'
node 'C:\Tools\saudi-hosting-review\node_modules\@azizme\saudi-hosting-review\dist\cli.js' inspect --root 'C:\Projects\my-app' --locale en --format markdown
```

On macOS/Linux, use an existing separate tool folder, the same npm commands and absolute paths such as `/Users/you/Tools/saudi-hosting-review/node_modules/@azizme/saudi-hosting-review/dist/cli.js`. Quote paths containing spaces. These platforms are documented but not exercised in this Windows build.

Installation downloads the **tool's** pinned dependencies. Review execution uses no network, AI account or API key. No scripts or dependencies from the selected application are installed or executed. The npm shrinkwrap pins transitive packages. No `npx`, `@latest`, global installation or unpublished registry package is required.

The scanner does not upload your repository to azizme.com. Its outputs are passed to your chosen AI client. A cloud model may receive those outputs and other context under that provider's settings. Local execution does not make the whole AI conversation offline. Inspect the CLI output before connecting a client; automatic minimization cannot promise perfect secret detection.

## CLI

Run the actual `dist/cli.js` path, followed by:

| Command | Result |
|---|---|
| `list --root "ABS_PROJECT"` | Dry-run candidate paths and coverage; no file content read |
| `inspect --root "ABS_PROJECT" --locale ar --format json` | Sanitized review JSON; Markdown is the default |
| `inspect --root "ABS_PROJECT" --role customer --personal-data unknown` | Explicit finite declarations; omitted answers remain unknown |
| `inspect --root "ABS_PROJECT" --scope-input "sanitized-components.json"` | Four-scope review using the JSON shape exported by the What-if Lab, with hypothetical mode/metadata removed; evidence declarations must replace hypothetical provenance |
| `sources` | Bundled reviewed source excerpts and metadata; no online refresh |
| `compare --root "ABS_PROJECT" --before "before.json" --after "after.json"` | Compare two same-root JSON reports, or their extracted `snapshot` objects |

`--max-files 1..400` lowers the cap. `--output "ABS_NONPUBLIC/report.md"` or `.json` saves explicitly to an existing directory outside the selected project and Git/public/build directories, and refuses overwrite. Otherwise results go to stdout only. Ctrl+C cancels scanning. Reports are not automatically committed or saved. The CLI never exports a badge.

Start from examples/scope-input.unknown.json (`examples/scope-input.unknown.json`), copy it into a private working folder, replace the service description and inventory, and keep unsupported geography as `null`. The starter deliberately has an incomplete inventory and cannot support a positive scope claim. Use the exact input shape under `src/schemas.ts` for scope inputs: `proposedScopePolicyVersion`, `serviceBoundary`, `componentFacts`. Country arrays use ISO alpha-2 values or `null` for unknown. Positive provenance `documented` means evidence **supplied by the user**, not independently verified by the scanner. The engine still checks required references and limits. No input mode can turn a real scan into a positive hypothetical result.

Beta.2 accepts beta.1 and beta.2 snapshots for the same root. Comparison reports scanner-version changes separately from source-bundle and observed architecture changes; it does not silently treat a new source bundle as new deployment evidence.

## Connect locally

The actual MCP entry point is `node_modules/@azizme/saudi-hosting-review/dist/server.js`. The server requires `--root` with one absolute project path at startup. A webpage cannot launch or talk to this stdio server. No localhost bridge or HTTP service is supplied.

For a trusted Codex project, review and merge examples/codex.config.toml (`examples/codex.config.toml`) into that project's `.codex/config.toml`, replacing the two example paths. The block does not change the global configuration. If the client cannot find Node.js 22 or later, replace `command = "node"` with its absolute executable path. Windows TOML paths can use forward slashes. Restart the client after changing project configuration. Alternatively, `codex mcp add saudi-hosting-review -- node "ABS_SERVER_JS" --root "ABS_PROJECT"` follows current CLI syntax but changes the user's Codex configuration; run it only if you intend that scope. Use `/mcp` in the client to inspect connectivity. No client configuration was installed by this package.

For Claude Code, merge the supplied JSON template (`examples/claude.mcp.json`) into the selected project's `.mcp.json`, or run `claude mcp add --scope project --transport stdio saudi-hosting-review -- node "ABS_SERVER_JS" --root "ABS_PROJECT"` from that project. Do not replace existing server entries. Review the client's project approval, then check `claude mcp list`. A pending-approval state is expected before approval; it is not a successful connection.

Native Codex 0.153.2 app-server testing covered all six tool discovery entries, inspection, an Arabic review pack, source-resource reading and project skill discovery. The test used a synthetic project and ephemeral thread, with no model turn and unchanged user configuration. Claude Code 2.1.239 validated the workflow package and recognized project MCP configuration as pending approval; a Claude MCP handshake and model-driven review remain untested. The official SDK client tested the complete stdio workflow in both supported protocol modes. No paid model call was made.

Supported tools: `inspect_project`, `assess_applicability`, `assess_proposed_scopes`, `get_source_evidence`, `build_review_pack`, `compare_review_snapshots`. A public source resource (`saudi-hosting://sources`) and bilingual workflow prompt (`review-selected-project`) are included. Scan IDs are process-local; only the last three scans remain. Snapshot root fingerprints prevent accidental cross-root comparison; imported snapshots remain unverified user data.

## Workflow plugin

`plugin.json` and `.codex-plugin/plugin.json` package the bilingual Saudi hosting review skill (`skills/saudi-hosting-review/SKILL.md`). The workflow works with the MCP or in a clearly labelled prompt-only mode. The plugin deliberately has no automatic MCP launcher: selecting a fixed root and installing the tool remain explicit setup actions. No global configuration, marketplace entry, background hook, external account or network connector is installed.

The portable plugin manifest and skill layout follow current official documentation. Plugin marketplace installation has not been exercised. For Codex, copy `skills/saudi-hosting-review` to the selected project's `.agents/skills/`. For Claude Code, use `.claude/skills/` in that project. Restart the client if needed, invoke `$saudi-hosting-review` in Codex or `/saudi-hosting-review` in Claude Code, and specify the selected root and output language. Follow the English plugin guide (`docs/plugin.en.md`) or Arabic plugin guide (`docs/plugin.ar.md`). Skill discovery is separate from connecting MCP. The supplied workflow is useful without a plugin marketplace.

## Maintenance and validation

From this source package in the website checkout: `npm ci --ignore-scripts`, `npm run check`. The build synchronizes the reviewed sibling `saudi-hosting-core` into `lib/core`, then compiles TypeScript. Tests cover synthetic secret canaries, injected instructions, junction/hardlink escapes, bounded/empty/binary scans, cancellation, export containment, all six real SDK tools and clean tarball installation. The public npm artifact includes compiled runtime and reviewable source; it runs without the website checkout.

Scope policy: `saudi-hosted-draft-1.0`. Regulatory source bundle: `saudi-hosting-sources-2026-10-03.2`. Updating either requires an explicit reviewed source change, sync, tests, new package version and new checksum. There is no runtime auto-update or scheduled source refresh. Read SECURITY.md (`SECURITY.md`) for the filesystem race and OS-sandbox limits.

Setup references reviewed 3 October 2026: [official MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/), [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Claude Code MCP](https://code.claude.com/docs/en/mcp), [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins). Local `codex mcp add --help` was checked. These links explain client setup, not Saudi legal requirements.