cedar-mcp-server 1.0.0

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build (typecheck)
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Integration tests
+        run: npm run test:integration

package/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Integration tests
+        run: npm run test:integration
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.nvmrc

@@ -0,0 +1 @@
+25

package/CHANGELOG.md

@@ -0,0 +1,241 @@
+# Changelog
+
+All notable changes to `cedar-mcp-server` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). This project uses [SemVer](https://semver.org/) from v1.0.0 onward. The `0.x` line is pre-release; breaking changes can happen between `0.x` releases.
+
+---
+
+## [Unreleased]
+
+(No unreleased changes yet.)
+
+---
+
+## [1.0.0] — 2026-05-22
+
+First published release. Twelve months of design + implementation + multi-round dogfood discipline now under SemVer. The 1.0.0 surface is 17 MCP tools, 8 MCP resource templates, 3 MCP prompts, plus a CLI entry that runs stdio (default) or Streamable HTTP.
+
+### Added
+
+#### `cedar_advise`: structured context bundle, not a sampling round-trip
+
+- `cedar_advise` returns a deterministic context bundle (schema summary, AST-classified policy inventory, intent-selected gotcha catalog, AVP `UpdatePolicy` mutability rules, Cedar patterns reference, sequencing guidance, next-steps text). The calling assistant produces the plan from the bundle. No MCP sampling capability required; no client LLM round-trip on the server side.
+- Auto-resolves to the single loaded store when `store_ref` is omitted (`auto_discovered.store_from: "single_loaded_store"`). With multiple stores loaded and no `store_ref`, returns `store_status: "ambiguous"` plus `available_stores` so the calling LLM can recover. Schemaless single-store cases degrade to `store_status: "not_provided"` rather than self-referential `not_found`.
+
+#### Stable policy IDs in `determining_policies`
+
+- Three-tier resolution: `@id("name")` annotation → file basename (when policies loaded via `cedar://policies/{store}` ref) → positional `policy<index>` fallback.
+- Applied to both `cedar_authorize` and `cedar_authorize_batch`; the two return identical ID shapes for the same policy set.
+- `cedar_authorize` also returns `decision_reason` with four explicit values: `permit_policy_fired`, `forbid_policy_fired`, `default_deny_no_permit_matched`, `evaluation_error`.
+
+#### Parser feedback and source locations
+
+- `cedar_validate` returns `line` and `column` (1-indexed) on every parse error, derived from the WASM source location and correctly accounting for multi-byte UTF-8 chars.
+- A 17-entry typo table populates the `hint` field for common misspellings (`int`/`in`, `prinicpal`/`principal`, `permint`/`permit`, `wen`/`when`, etc.); falls back to Cedar's own diagnostic help when no entry matches; `null` otherwise.
+
+#### Two-mode `cedar_validate`
+
+- Syntax-only mode (no schema): runs the parser alone. Useful for typo / scope sanity checks.
+- Syntax-and-schema mode (schema supplied or auto-discovered): adds attribute typing, action applicability, `UnsafeOptionalAttributeAccess` warnings.
+- Explicit `validation_mode: "auto" | "syntax_only" | "syntax_and_schema"` parameter forces a specific mode (default `"auto"`).
+
+#### Workspace auto-discovery for stdio
+
+- When stdio launches in a directory that looks like a Cedar policy store (`schema.cedarschema`, `schema.json`, or a `policies/` subdirectory), the server loads the cwd **synchronously before the transport accepts client requests**. By the time the first `resources/list` arrives, the store is already populated.
+- `cedar_validate`, `cedar_authorize`, `cedar_explain` consult the loaded store when their required inputs are omitted; the response's `auto_discovered.*_from` fields name which store satisfied each missing input.
+- Multi-store deployments surface an `ambiguous` error listing candidate names; pass `store: "<name>"` to disambiguate.
+- Security guard: refuses to load roots whose normalized path is empty (`file:///`), preventing the `isPathAllowed` `startsWith("")` bypass that would otherwise grant access to every filesystem path.
+
+#### `cedar_authorize_batch`: decision matrix over a shared policy set
+
+- Runs N authorization requests through one policy set in a single call. Returns total / allowed / denied / errored counts plus a per-request decision array with `determining_policies` (basenames, same H1 resolution as `cedar_authorize`). Schema-violating requests resolve to `decision: "Error"` when `schema + validateRequest` is in play.
+
+#### Template operations
+
+- `cedar_validate_template`: validates a Cedar policy template against a schema; supports cedarschema and JSON forms.
+- `cedar_link_template`: links a template to a concrete principal and resource, producing a template-linked policy.
+- `cedar_list_templates` / `cedar_list_template_links`: lists templates and links in a store; per-item read errors surface as structured errors rather than throwing.
+- `StoreManager` extended with `listTemplates`, `readTemplate`, `listTemplateLinks`, `readTemplateLink`.
+- New MCP Resources: `cedar://templates/{store}`, `cedar://templates/{store}/{id}`, `cedar://template-links/{store}`, `cedar://template-links/{store}/{id}`.
+
+#### Schema and entity standalone operations
+
+- `cedar_validate_schema`: standalone schema validation, JSON or cedarschema text. Returns validity flag, format, namespace list, entity/action/common-type counts, errors with source locations.
+- `cedar_diff_schema`: structural schema diff with AVP-aware risk classification per change (`safe` / `review` / `breaking`) plus a top-level `risk_level`. Accepts inline schema text or `cedar://schema/{store}` URIs.
+- `cedar_validate_entities`: validates an entity store against a schema; classifies errors by kind (`unknown_type`, `missing_required_attribute`, `type_mismatch`, `unknown_attribute`, `disallowed_parent_type`, `parse_error`, `other`).
+
+#### `cedar_generate_sample_request`
+
+- Generates a complete authorization request payload (principal, action, resource, entities) that produces a target Allow / Deny decision against a given policy and schema.
+- Pre-fills required entity attributes from the schema (Cedar's `required: true` default for JSON-schema attributes).
+- Verifies the generated payload against `cedar_authorize` with `validateRequest: true`; `ready_to_test: true` confirms a follow-up call with these exact inputs reproduces the documented decision. Schema-mismatched payloads return `ready_to_test: false` with an actionable error.
+- Single-prefix entity refs (`MyApp::User::"alice"`) regardless of whether the schema was supplied as `.cedarschema` text or as JSON.
+
+#### Streamable HTTP mode
+
+- New transport for shared team deployment. CLI: `cedar-mcp-server --http <port> [--host <host>] [--root name=path]...`. Stdio remains the default.
+- Per-session `McpServer` + transport pair with stateful `Mcp-Session-Id` routing.
+- Shared `storeManager` across HTTP sessions; deployment model is "one server per policy-store set." Deployer-configured roots via repeatable `--root` flags.
+- Security: localhost default-binding with DNS rebinding protection. Non-localhost binding (`--host 0.0.0.0`) is the deployer's responsibility (auth via reverse proxy).
+- Max-sessions cap (default 100, configurable via `CEDAR_MAX_HTTP_SESSIONS`) returns HTTP 503 when reached.
+- Idle-session TTL (default 30 min, configurable via `CEDAR_HTTP_SESSION_IDLE_TTL_MS`) with a periodic reaper.
+- `/health` endpoint returns `{ status, transport, mode, active_sessions, max_sessions, session_idle_ttl_ms }`.
+
+#### `cedar://` resources end-to-end
+
+- Each `ResourceTemplate` carries a `list:` callback so MCP clients can enumerate via `resources/list` rather than guessing URIs. Eight resource templates registered.
+- `notifications/resources/list_changed` emitted after every store reconciliation pass so cache-aware clients can refetch on root changes.
+- `ref-resolver.ts` resolves `cedar://policies/{store}`, `cedar://schema/{store}`, `cedar://entities/{store}` (and per-id variants), `cedar://templates/{store}`, `cedar://template-links/{store}`.
+- `cedar_authorize` / `cedar_authorize_batch` / `cedar_explain` / `cedar_validate` accept the matching `_ref` parameters.
+
+#### MCP Prompts
+
+- `cedar-review-policy-diff`: drives `cedar_diff_policy_stores` + `cedar_diff_schema`, summarizes risk, advises on promotion.
+- `cedar-explain-denial`: runs `cedar_authorize` via `cedar://` refs + `cedar_explain` on the deciding policies; produces a plain-English explanation.
+- `cedar-avp-migration-checklist`: guided checklist for AVP migration; optional `namespace` argument substitutes the placeholder.
+
+#### Server instructions and discoverability
+
+- `SERVER_INSTRUCTIONS` returned on `initialize`: a routing table that directs the MCP client to call `cedar_*` tools rather than `Read`/`Bash` on policy files, plus the workspace-auto-discovery directive. Truncated to fit under Claude Code's 2KB instructions budget.
+
+### Changed (relative to the development 0.0.1 milestone)
+
+- `cedar_advise`: replaced the sampling-based design with the deterministic context bundle described above. The old `previous_plan` delta-output API is gone with it; the calling assistant iterates the plan in conversation.
+- `cedar_diff_policy_stores`: `schema_diff` field is now a structured `SchemaDiff` object (with per-change risk classification) replacing the previous `schema_changed: boolean` + `schema_diff_note: string` fields.
+
+### Fixed (relative to the development 0.0.1 milestone)
+
+- `cedar_validate`: line / column derivation correctly counts Unicode code points (not UTF-16 code units), so non-ASCII characters before the error site no longer drift the reported column.
+- `cedar_validate_entities`: removed the incorrect `orphan_parent` error kind (no such Cedar concept); `disallowed_parent_type` now recognized rather than collapsing to `error_kind: "other"`.
+
+---
+
+## [0.0.1] — 2026-05-20
+
+Development milestone. Internal-only; never published to npm. Documents the four implementation phases (cedar_validate / cedar_authorize / cedar_format / cedar_translate; cedar_explain / cedar_check_policy_change / cedar_generate_sample_request; MCP Roots and Resources; cedar_advise via MCP sampling). Detailed feature breakdown below for historical reference; v1.0.0 above is the canonical surface.
+
+### Phase 4 — Planning: `cedar_advise`
+
+- `cedar_advise`: translates natural-language intent into a step-by-step Cedar policy change plan via MCP sampling. Server builds deterministic context (schema, policy inventory with patterns and Cedar text, selected gotchas, AVP rules summary); LLM produces intent interpretation, applicable Cedar pattern, ordered change steps with Cedar snippets, AVP deployment classification, and verification steps.
+- Iterative refinement via `previous_plan`: passing a previous result triggers delta output (unchanged/modified/added/removed steps).
+- Supporting modules: `avp-rules.ts` (10 AVP validation error categories, UpdatePolicy mutability map), `cedar-patterns.ts` (AST-based policy classifier), `gotchas.ts` (10-entry gotcha catalog with keyword-based selection), `context-builder.ts` (walks policy store files for prompt context).
+- `postProcess()` enforces deterministic corrections: `policy_new` always maps to `new_policy_via_create_policy`, `policy_delete` always maps to `requires_delete_recreate`, schema-before-policy ordering violations surface as a gotcha.
+
+(This sampling-based design was replaced in v1.0.0 by the deterministic context bundle. See the v1.0.0 entry above.)
+
+### Phase 3 — Roots, Resources, Diffing
+
+- MCP Roots integration: loads policy stores on server init, reloads on `RootsListChangedNotification`.
+- `StoreManager`: maps `file://` root URIs to named stores; reads `.cedar` policy files from `policies/` subdirectory; reads `schema.cedarschema` or `schema.json`. Security: validates policy IDs against `^[a-zA-Z0-9_-]+$` (no path traversal); rejects non-`file://` URIs.
+- `cedar://` MCP Resources: `cedar://policies/{store}`, `cedar://policies/{store}/{id}`, `cedar://schema/{store}`.
+- `policy_ref` and `schema_ref` parameters on `cedar_validate`, `cedar_authorize`, and `cedar_explain`: accept `cedar://` URIs as alternatives to inline text.
+- `cedar_diff_policy_stores`: structural diff (added/removed/modified policies with AVP immutability classification per change), schema diff, optional behavioral diff (runs authorization requests through both stores and surfaces decision drift).
+
+### Phase 2 — Planning and Understanding
+
+- `cedar_explain`: explains a Cedar policy in plain English with pattern detection. Supports templates via `templateToJson` fallback.
+- `cedar_check_policy_change`: determines whether a policy modification can be applied in-place in AVP or requires delete-and-recreate. Uses AST comparison against AVP UpdatePolicy immutability rules.
+- `cedar_generate_sample_request`: generates a complete authorization request payload (principal, action, resource, entities) that produces a target decision against a given policy. Verifies the generated payload against `cedar_authorize`.
+
+### Phase 1 — Validation and Evaluation
+
+- `cedar_validate`: validates Cedar policies against a schema using `@cedar-policy/cedar-wasm`. Returns errors with hints and source locations.
+- `cedar_authorize`: evaluates an authorization request locally. Auto-detects and converts all three AVP SDK entity formats (snake_case Ruby, camelCase Python/JS, PascalCase official API). Unwraps typed attribute wrappers and entity reference wrappers recursively.
+- `cedar_format`: formats Cedar policy text to canonical style.
+- `cedar_translate`: translates between Cedar text and JSON formats for policies and schemas.
+
+### Original [Unreleased] block (pre-v1.0.0, kept for archaeological reference)
+
+The features below were originally batched under `[Unreleased]` during the v0.x development line; all of them shipped as part of v1.0.0 above.
+
+#### Template operations (Batch A)
+- `cedar_validate_template`: validates a Cedar policy template (static template text) against a schema; supports both cedarschema and JSON schema formats.
+- `cedar_link_template`: links a policy template to a concrete principal and resource, producing a template-linked policy in the store.
+- `cedar_list_templates`: lists all policy templates in a store; per-item read errors surface as structured errors rather than throwing.
+- `cedar_list_template_links`: lists all template-linked policies in a store; per-item read errors surface as structured errors rather than throwing.
+- `StoreManager` extended with `listTemplates`, `readTemplate`, `listTemplateLinks`, and `readTemplateLink` methods.
+- New MCP Resources: `cedar://templates/{store}`, `cedar://templates/{store}/{id}`, `cedar://template-links/{store}`, `cedar://template-links/{store}/{id}`.
+- `SECURITY.md` added to the repository.
+
+#### Schema and entity standalone operations (Batch B)
+- `cedar_validate_schema`: standalone schema validation accepting JSON or cedarschema text; returns validity flag, detected format, namespace list, entity/action counts, and errors with source locations.
+- `cedar_diff_schema`: structural schema diff with AVP-aware risk classification; each change is classified as `safe`, `review`, or `breaking` with a reason; accepts inline schema text or `cedar://schema/{store}` URIs.
+- `cedar_validate_entities`: validates an entity store against a schema; classifies errors by kind (`unknown_type`, `missing_required_attribute`, `type_mismatch`, `unknown_attribute`, `disallowed_parent_type`, `parse_error`, `other`).
+
+#### Batch authorization (Batch C)
+- `cedar_authorize_batch`: runs N authorization requests through one policy set and returns the decision matrix (total/allowed/denied/errored counts plus per-request decision array with `determining_policies` from WASM `diagnostics.reason`). Schema-violating requests resolve to `decision: "Error"` when `schema + validateRequest` is in play; without schema, the same request is silently evaluated.
+
+#### MCP Prompts (Batch D)
+- `cedar-review-policy-diff`: drives `cedar_diff_policy_stores` + `cedar_diff_schema`, summarizes risk, advises on promotion.
+- `cedar-explain-denial`: runs `cedar_authorize` via `cedar://` refs + `cedar_explain` on deciding policies; produces plain-English explanation.
+- `cedar-avp-migration-checklist`: guided checklist for AVP migration; optional `namespace` arg substitutes `<YourNamespace>` placeholder when omitted.
+
+#### Entities resource access (Batch E)
+- `StoreManager` extended with `listEntities`, `readEntities`, and `readAllEntities` methods (entity files live in `entities/*.json` under the store root).
+- New MCP Resources: `cedar://entities/{store}` (merged JSON across entity files) and `cedar://entities/{store}/{file_id}` (single file).
+- `ref-resolver.ts` now also resolves `cedar://templates/{store}`, `cedar://templates/{store}/{id}`, `cedar://template-links/{store}`, and `cedar://template-links/{store}/{id}` — previously the corresponding MCP Resources were registered but the URIs were not resolvable as `*_ref` parameters in tools.
+- `cedar_authorize` and `cedar_authorize_batch` gained an `entities_ref` parameter; either inline `entities` or `entities_ref` is now accepted.
+
+#### HTTP transport (Batch F)
+- New Streamable HTTP transport for shared team deployment. CLI: `cedar-mcp-server --http <port> [--host <host>] [--root name=path]...`. Stdio remains the default.
+- Per-session McpServer + transport pair with stateful `Mcp-Session-Id` routing (Streamable HTTP spec requires per-session protocol state).
+- Shared `storeManager` across HTTP sessions — deployment model is "one server per policy-store set." Deployer-configured roots via repeatable `--root` flags; client `listRoots()` is not called in HTTP mode.
+- Security: localhost default-binding with DNS rebinding protection via the SDK's `createMcpExpressApp`. Non-localhost binding is the deployer's responsibility (auth via reverse proxy).
+- Max-sessions cap (default 100) returns HTTP 503 when reached; backpressure rather than eviction. Configurable via `maxSessions` option or `CEDAR_MAX_HTTP_SESSIONS` env var.
+- Idle-session TTL (default 30 min) with a periodic reaper that evicts sessions whose last request exceeds the TTL. Catches the case where `transport.onclose` doesn't fire (network partition, TCP RST). Configurable via `sessionIdleTtlMs` option or `CEDAR_HTTP_SESSION_IDLE_TTL_MS` env var.
+- New `/health` endpoint returns `{ status, transport, mode, active_sessions, max_sessions, session_idle_ttl_ms }`.
+- New deps: `express`, `@types/express`.
+- Integration smoke tests covering listTools/cedar_validate/cedar_authorize over real HTTP transport, the /health endpoint, malformed JSON body falsification, multiple concurrent sessions via independent Mcp-Session-Id, the deployer-configured `--root` path (cedar:// URI resolution end-to-end), max-sessions cap returning 503, and idle TTL eviction by the reaper.
+
+### Changed
+- `cedar_diff_policy_stores`: `schema_diff` field is now a structured `SchemaDiff` object (with per-change risk classification) replacing the previous `schema_changed: boolean` + `schema_diff_note: string` fields.
+
+### Fixed
+- `cedar_validate_entities`: removed incorrect `orphan_parent` error kind (no such Cedar concept); added `disallowed_parent_type` recognition that previously fell through to `error_kind: "other"`.
+
+---
+
+## [0.0.1] — 2026-05-20
+
+First tagged release. All four implementation phases shipped.
+
+### Phase 4 — Planning: `cedar_advise`
+
+- `cedar_advise`: translates natural-language intent into a step-by-step Cedar policy change plan via MCP sampling. Server builds deterministic context (schema, policy inventory with patterns and Cedar text, selected gotchas, AVP rules summary); LLM produces intent interpretation, applicable Cedar pattern, ordered change steps with Cedar snippets, AVP deployment classification, and verification steps.
+- Iterative refinement via `previous_plan`: passing a previous result triggers delta output (unchanged/modified/added/removed steps).
+- Supporting modules: `avp-rules.ts` (10 AVP validation error categories, UpdatePolicy mutability map), `cedar-patterns.ts` (AST-based policy classifier), `gotchas.ts` (10-entry gotcha catalog with keyword-based selection), `context-builder.ts` (walks policy store files for prompt context).
+- `postProcess()` enforces deterministic corrections: `policy_new` always maps to `new_policy_via_create_policy`, `policy_delete` always maps to `requires_delete_recreate`, schema-before-policy ordering violations surface as a gotcha.
+
+### Phase 3 — Roots, Resources, Diffing
+
+- MCP Roots integration: loads policy stores on server init, reloads on `RootsListChangedNotification`.
+- `StoreManager`: maps `file://` root URIs to named stores; reads `.cedar` policy files from `policies/` subdirectory; reads `schema.cedarschema` or `schema.json`. Security: validates policy IDs against `^[a-zA-Z0-9_-]+$` (no path traversal); rejects non-`file://` URIs.
+- `cedar://` MCP Resources: `cedar://policies/{store}`, `cedar://policies/{store}/{id}`, `cedar://schema/{store}`.
+- `policy_ref` and `schema_ref` parameters on `cedar_validate`, `cedar_authorize`, and `cedar_explain`: accept `cedar://` URIs as alternatives to inline text.
+- `cedar_diff_policy_stores`: structural diff (added/removed/modified policies with AVP immutability classification per change), schema diff, optional behavioral diff (runs authorization requests through both stores and surfaces decision drift).
+
+### Phase 2 — Planning and Understanding
+
+- `cedar_explain`: explains a Cedar policy in plain English with pattern detection. Supports templates via `templateToJson` fallback.
+- `cedar_check_policy_change`: determines whether a policy modification can be applied in-place in AVP or requires delete-and-recreate. Uses AST comparison against AVP UpdatePolicy immutability rules.
+- `cedar_generate_sample_request`: generates a complete authorization request payload (principal, action, resource, entities) that produces a target decision against a given policy. Verifies the generated payload against `cedar_authorize`.
+
+### Phase 1 — Validation and Evaluation
+
+- `cedar_validate`: validates Cedar policies against a schema using `@cedar-policy/cedar-wasm`. Returns errors with hints and source locations.
+- `cedar_authorize`: evaluates an authorization request locally. Auto-detects and converts all three AVP SDK entity formats (snake_case Ruby, camelCase Python/JS, PascalCase official API). Unwraps typed attribute wrappers and entity reference wrappers recursively.
+- `cedar_format`: formats Cedar policy text to canonical style.
+- `cedar_translate`: translates between Cedar text and JSON formats for policies and schemas.
+
+---
+
+[Unreleased]: https://github.com/Pigius/cedar-mcp-server/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Pigius/cedar-mcp-server/releases/tag/v1.0.0
+[0.0.1]: https://github.com/Pigius/cedar-mcp-server/releases/tag/v0.0.1
+
+---
+
+## Release process
+
+To release: bump version in `package.json`, commit, `git tag v0.X.Y`, `git push --tags`. The release workflow runs build + tests + `npm publish` with provenance. Requires `NPM_TOKEN` repo secret pre-configured.

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Contributions are welcome. This document covers how to set up locally, the conventions used in this project, and what's expected in a pull request.
+
+---
+
+## Local setup
+
+```bash
+git clone https://github.com/Pigius/cedar-mcp-server.git
+cd cedar-mcp-server
+npm install
+npm test
+```
+
+Requires Node.js 20 or higher.
+
+---
+
+## Project structure
+
+```
+src/
+  index.ts            MCP server entry point, roots loading
+  server.ts           Tool registration and request routing
+  tools/              One handler file per tool
+  tools/advise/       Supporting modules for cedar_advise
+  resources/          StoreManager, ref-resolver
+  parser/             Cedar AST utilities
+  utils/              Format detection, shared helpers
+test/
+  tools/              Unit tests for each tool handler
+  resources/          Unit tests for StoreManager and ref-resolver
+  integration/        End-to-end smoke tests
+  fixtures/           Shared test fixtures
+```
+
+Each tool lives in `src/tools/<name>.ts` with a corresponding test in `test/tools/<name>.test.ts`. The pattern is one exported handler function per file, tested independently of the MCP server wiring.
+
+---
+
+## Running tests
+
+```bash
+npm test                          # unit tests (fast, excludes integration)
+npm run test:integration          # integration smoke tests (spawns the server via stdio)
+```
+
+Unit tests are fast and self-contained. Integration tests spawn the server as a child process and require a built or runnable server; they run separately from the unit suite.
+
+---
+
+## Test data and NDA discipline
+
+Test fixtures in `test/fixtures/` use only the abstract datasets from this repository (DocMgmt, Gateway, generic SaaS namespaces). Do not add fixtures derived from real client systems. The same rule applies to examples in `examples/`: generic, abstract, no real company or product names.
+
+---
+
+## Conventions
+
+**TDD cadence.** For new tools and bug fixes, write a failing test first, then implement. Commits should reflect this: a red test commit, then a green implementation commit.
+
+**Post-phase audit.** Before any release tag or `npm publish`, run the post-phase audit checklist: verify claims in README match code, check for dead links, confirm version numbers are consistent across `package.json`, `CHANGELOG.md`, and README compatibility table.
+
+**No silent breaking changes.** If a tool's input or output shape changes in a way that breaks existing callers, that's a major version bump. Document it in `CHANGELOG.md` under the new version.
+
+**No new dependencies without a reason.** The WASM approach keeps the install footprint minimal. New runtime dependencies need justification.
+
+---
+
+## Pull request expectations
+
+- Tests pass: `npm test` green.
+- Type check clean: `npx tsc --noEmit` passes.
+- `CHANGELOG.md` updated under `[Unreleased]` with a description of what changed.
+- If you're adding a new tool, add it to the tools table and tool details section in `README.md`.
+- If you're changing a tool's input or output schema, update the relevant section in `README.md`.
+
+---
+
+## Issues
+
+Bug reports and feature requests via GitHub Issues. For bugs, include the tool name, the input that triggered the issue, and the actual vs expected output.

package/LICENSE

@@ -0,0 +1,182 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of recording and
+      distributing the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any other
+      contribution embodied in the Work constitutes patent or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of a character arising as a result
+      of this License or out of the use or inability to use the Work
+      (even if such Contributor has been advised of the possibility of
+      such damages).
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of
+      any other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 Daniel Aniszkiewicz
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.