raytio-mcp-server 1.16.1

package/AGENTS.md

@@ -0,0 +1,114 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, etc.) working in this repository. Human contributors should also follow these conventions.
+
+## Project overview
+
+Raytio MCP server — a Node.js/TypeScript stdio MCP server that exposes Raytio platform tools (DSM data requests, PPM work items) to AI agents. See `README.md` for feature and tool documentation.
+
+## Required workflow for every branch / MR
+
+### 1. Bump the version on every branch
+
+**Every branch that will produce a merge request MUST bump `version` in `package.json`.** This is non-negotiable because the server is (or will be) distributed to end users who rely on the version string to decide when to restart sessions or upgrade.
+
+Bump before opening the MR and again if you add further commits that change behaviour. Use [semver](https://semver.org):
+
+| Change | Bump |
+|---|---|
+| Backwards-incompatible change to tool inputs/outputs, config schema, auth, or wire protocol | **major** (`1.0.0` → `2.0.0`) |
+| New tool, new optional config field, new capability | **minor** (`1.0.0` → `1.1.0`) |
+| Bug fix, refactor, docs, internal change with no external contract change | **patch** (`1.0.0` → `1.0.1`) |
+
+Preferred command (updates `package.json` and `package-lock.json`, does not create a git tag):
+
+```bash
+npm version patch --no-git-tag-version   # or: minor / major
+```
+
+Commit the bump alongside your change (or as its own commit — either is fine, as long as it's in the MR).
+
+If your MR only touches docs or CI and has no runtime impact, you may skip the bump — but prefer a patch bump when in doubt. Reviewers will ask.
+
+### 2. Branch naming
+
+Follow the repo convention: `<issue-number>-<short-description>` (e.g. `12-add-ppm-export-tool`). This matches the CLAUDE.md workflow for all Raytio repos.
+
+### 3. Before opening the MR
+
+- `npm run build` passes with no TypeScript errors.
+- `npm test` passes. Add tests for new behaviour.
+- `config.env.example` and `README.md` reflect any new env vars or setup steps.
+- If you added, removed, or changed a tool (name, description, or input schema), regenerate the tool catalogue: `npm run docs:tools` and commit `docs/tools.md`.
+- Commit messages are descriptive and explain *why*, not just *what*.
+
+### 4. Opening the MR
+
+Use GitLab CLI with `Agent` + `Doing` labels:
+
+```bash
+glab mr create --label "Agent,Doing" --fill
+```
+
+When the work is ready for testing, update the labels:
+
+```bash
+glab mr update <mr-id> --label "Agent,Ready to Test"
+```
+
+## Conventions
+
+### Code
+
+- **TypeScript strict mode** — do not disable strict checks; fix the types instead.
+- **ESM modules** — use `.js` extensions on relative imports (TS compiles to ESM).
+- **Zod for runtime validation** — all tool inputs and external data must be parsed through a Zod schema. Zod schemas are converted to JSON Schema for MCP tool advertisement via `zod-to-json-schema`.
+- **No `any` except at library boundaries** where type inference hits a wall (e.g. `zod-to-json-schema` depth issue in `src/index.ts`). Leave a comment when you cast.
+- **Tools follow the `Tool` interface** in `src/tools/registry.ts`. Co-locate `*.test.ts` next to the implementation and export from the relevant `index.ts` (`dsm/` or `ppm/`).
+- **Domains and sub-domains** are declared in `src/tools/domains.ts`. When you add a new primary domain or a new sub-domain (e.g. a read-only slice), register it in both `primaryDomains` and `domainIndex`. Add a test case in `domains.test.ts`, then run `npm run docs:tools` so the catalogue reflects the change.
+
+### Configuration
+
+- Config is loaded from `process.env`, with `config.env` (resolved relative to the compiled module, not `process.cwd()`) as a local dev convenience. Override location via `RAYTIO_CONFIG_FILE`.
+- Never commit secrets. `config.env`, `config.json`, and `.env` are gitignored.
+- `config.env.example` is the canonical template. Update it when adding or removing env vars.
+
+### Testing
+
+- Unit tests with Vitest, co-located as `src/**/*.test.ts`.
+- Mock the Raytio API client at the boundary (`src/raytio/api-client.ts`); don't hit the network in tests.
+
+### Dependencies
+
+- Prefer minimal, well-maintained packages. The runtime is shipped to users, so every dep is dead weight until proven useful.
+- After `npm install`, commit both `package.json` and `package-lock.json`.
+
+## CI / release pipeline
+
+`.gitlab-ci.yml` runs on every push:
+
+- **`test`** (all branches) — `npm ci`, `npm test`, `npm run build`, and a staleness check on `docs/tools.md`. Fails CI if the generated tool catalogue was not regenerated after a tool change.
+- **`build`** (main only) — produces a `dist/` artifact.
+- **`publish-npm`** (main only) — publishes to npmjs.org via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, no `NPM_TOKEN`). The job is idempotent: if `package.json` version already exists on npm, it exits 0 without republishing — so a merge without a version bump does not fail the pipeline.
+
+To cut a release: bump `version` in `package.json` (§1) and merge to `main`. The pipeline picks it up and publishes automatically.
+
+## Release notes
+
+For every version bump, add a line to the changelog in the MR description (or a `CHANGELOG.md` once one exists):
+
+```
+## 1.2.3 — YYYY-MM-DD
+- Added `ppm_foo_bar` tool (#42)
+- Fixed decryption error when WADEK missing (#44)
+```
+
+This makes it easy to communicate upgrades to downstream consumers.
+
+## Things to avoid
+
+- **Do not** rely on `process.cwd()` for file paths — the server is launched from arbitrary directories by MCP clients.
+- **Do not** log secrets, tokens, encryption passwords, or full Cognito responses. Use the existing logging patterns in `src/raytio/`.
+- **Do not** add tools that perform destructive Raytio operations without explicit confirmation semantics.
+- **Do not** hardcode environment-specific URLs; route through the `RAYTIO_API_BASE_URL` config.
+- **Do not** merge without bumping `version`. See §1.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raytio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,486 @@
+# Raytio MCP Server
+
+An MCP (Model Context Protocol) server that enables AI agents to securely request and retrieve user data from the Raytio platform using end-to-end encryption.
+
+## Overview
+
+This server exposes Raytio platform capabilities to AI agents via MCP. Tools are organised into **domains**, and the full catalogue (names, descriptions, parameters) is generated from source at [`docs/tools.md`](./docs/tools.md).
+
+**Current domains:**
+
+| Domain | Purpose |
+|---|---|
+| **DSM** — Data Sharing & Requests | Request and retrieve end-to-end encrypted user data via Raytio forms and access applications. |
+| **PPM** — Project & Program Management | Read and update Raytio work items and activities with semantic status transitions. |
+| **PRM** — Party Relationship Management | Manage parties (organisations, groups, and people) that the business entity interacts with. |
+| **WRM** — Worker Relationship Management | Manage AI worker identities, model stacks, MCP tool registrations, roles, role memories, and agent run steps/artifacts. |
+
+All user data flowing through DSM is encrypted end-to-end using Raytio's Maxcryptor system (AES-256-GCM + WADEK key wrapping).
+
+## Adding MCP server to AI tool
+
+Two install paths:
+
+- **npx (recommended for end users)** — no clone, no build; `npx` downloads the published package from npm and runs it. Credentials come from env vars passed inline, or from a file pointed at by `RAYTIO_CONFIG_FILE` (see below).
+- **Local clone (recommended for contributors)** — clone this repo, run `npm install && npm run build`, and point the MCP client at `dist/index.js`. Credentials come from `config.env` colocated with the build.
+
+### Recommended setup for npx installs
+
+Keep all the credential env vars in a single file outside your project tree, and have the MCP client only pass `RAYTIO_CONFIG_FILE` pointing at it. This is shorter than inline `-e` blocks, keeps creds out of the MCP client's config file, and means rotating a password is a one-file edit instead of re-running `claude mcp add`.
+
+```bash
+# 1. Create the file (chmod 600 so only you can read it)
+mkdir -p ~/.config/raytio
+install -m 600 /dev/null ~/.config/raytio/mcp.env
+
+# 2. Populate it — same keys as config.env.example
+cat > ~/.config/raytio/mcp.env <<'EOF'
+RAYTIO_API_BASE_URL=https://api.rayt.io
+RAYTIO_COGNITO_USER_POOL_ID=us-east-1_xxxxxxxxx
+RAYTIO_COGNITO_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
+RAYTIO_COGNITO_REGION=us-east-1
+RAYTIO_AGENT_USERNAME=agent@example.com
+RAYTIO_AGENT_PASSWORD=...
+RAYTIO_AGENT_ENCRYPTION_PASSWORD=...
+RAYTIO_AGENT_CUSTOMER_ID=00000000-0000-0000-0000-000000000000
+RAYTIO_TARGET_USER_EMAIL=user@example.com
+# Optional: static override for tool domains (see "Tool domain selection" below).
+# If unset, domains are resolved dynamically from the user's backend roles.
+# RAYTIO_TOOL_DOMAINS=ppm-readonly
+EOF
+```
+
+Then register the MCP server, passing only the pointer:
+
+```bash
+# Claude Code
+claude mcp add raytio -s user \
+  -e RAYTIO_CONFIG_FILE=$HOME/.config/raytio/mcp.env \
+  -- npx -y raytio-mcp-server
+```
+
+```toml
+# Codex CLI (~/.codex/config.toml)
+[mcp_servers.raytio]
+command = "npx"
+args = ["-y", "raytio-mcp-server"]
+
+[mcp_servers.raytio.env]
+RAYTIO_CONFIG_FILE = "/home/you/.config/raytio/mcp.env"
+```
+
+For multiple registrations with different credentials (see "Splitting tools" below), use one file per registration: `~/.config/raytio/dsm.env`, `~/.config/raytio/ppm.env`, etc., each with its own `RAYTIO_CONFIG_FILE` pointer.
+
+### Claude Code
+
+#### Install via npx
+
+```bash
+claude mcp add raytio -s user \
+  -e RAYTIO_API_BASE_URL=https://api.rayt.io \
+  -e RAYTIO_COGNITO_USER_POOL_ID=... \
+  -e RAYTIO_COGNITO_CLIENT_ID=... \
+  -e RAYTIO_COGNITO_REGION=us-east-1 \
+  -e RAYTIO_AGENT_USERNAME=agent@example.com \
+  -e RAYTIO_AGENT_PASSWORD=... \
+  -e RAYTIO_AGENT_ENCRYPTION_PASSWORD=... \
+  -e RAYTIO_AGENT_CUSTOMER_ID=00000000-0000-0000-0000-000000000000 \
+  -- npx -y raytio-mcp-server
+```
+
+#### Install from a local clone
+
+Build first (`npm install && npm run build`), then register. The server resolves `config.env` relative to its own install location, so one registration works from every project on your machine:
+
+```bash
+claude mcp add raytio -s user -- node /absolute/path/to/mcp-server/dist/index.js
+```
+
+Credentials are picked up from `config.env` in the repo root (copy `config.env.example` and fill it in).
+
+#### Shared settings
+
+Verify: `claude mcp list`. Inside a session: `/mcp`. Remove: `claude mcp remove raytio`.
+
+**Scopes:**
+- `-s user` — available in every project for the current OS user (recommended for personal use).
+- `-s project` — writes to `.mcp.json` in the current repo, committed for teammates. Prefer the npx form at project scope, since absolute paths aren't portable.
+- *(default, local)* — private to your user, scoped to the current project.
+
+### Codex CLI
+
+[Codex CLI](https://github.com/openai/codex) registers MCP servers via `~/.codex/config.toml`.
+
+#### Install via npx
+
+```toml
+[mcp_servers.raytio]
+command = "npx"
+args = ["-y", "raytio-mcp-server"]
+
+[mcp_servers.raytio.env]
+RAYTIO_API_BASE_URL = "https://api.rayt.io"
+RAYTIO_COGNITO_USER_POOL_ID = "..."
+RAYTIO_COGNITO_CLIENT_ID = "..."
+RAYTIO_COGNITO_REGION = "us-east-1"
+RAYTIO_AGENT_USERNAME = "agent@example.com"
+RAYTIO_AGENT_PASSWORD = "..."
+RAYTIO_AGENT_ENCRYPTION_PASSWORD = "..."
+RAYTIO_AGENT_CUSTOMER_ID = "00000000-0000-0000-0000-000000000000"
+```
+
+#### Install from a local clone
+
+Build first (`npm install && npm run build`), then:
+
+```toml
+[mcp_servers.raytio]
+command = "node"
+args = ["/absolute/path/to/mcp-server/dist/index.js"]
+```
+
+Credentials are picked up from `config.env` next to the server install. To override inline, add a `[mcp_servers.raytio.env]` block as in the npx example.
+
+Restart Codex CLI after editing the config. Inside a session, `/mcp` lists loaded servers. Remove by deleting the block and restarting.
+
+### Tool domain selection
+
+The server decides which tools to expose using the following precedence:
+
+1. **`RAYTIO_TOOL_DOMAINS` env var** (static override) — if set and non-empty, this value is used directly. No backend query is made.
+2. **Dynamic role resolution** — if `RAYTIO_TOOL_DOMAINS` is not set, the server queries the authenticated user's roles via `fnd_authz_user_groups()` at startup and maps them to tool domains automatically.
+3. **All domains** (fallback) — if the role query fails or returns no recognised roles, every domain is exposed (matching pre-v1.4.0 behaviour).
+
+The server logs which path was taken at startup (to stderr).
+
+#### How dynamic resolution works
+
+On startup the server calls the backend RPC endpoint `fnd_authz_user_groups()` with the agent's Cognito credentials. This returns all roles the user holds (direct assignments + inherited via the role hierarchy). The roles are mapped to tool domains:
+
+| Role | Domain |
+|---|---|
+| `PROJECT_USER` | `ppm` (full read + write) |
+| `PROJECT_ADMINISTRATOR` | `ppm` + `wrm` (full read + write) |
+| `PROJECT_VIEWER` | `ppm-readonly` + `wrm-readonly` (read-only subset) |
+| `DATA_SHARING_USER`, `DATA_SHARING_ADMINISTRATOR` | `dsm` |
+| `WORKER_ADMINISTRATOR` | `wrm` (full read + write) |
+| `WORKER_VIEWER` | `wrm-readonly` (read-only subset) |
+
+If a user has both `PROJECT_VIEWER` and `PROJECT_USER` (or `PROJECT_ADMINISTRATOR`), `ppm` wins — it is a superset of `ppm-readonly`.
+
+The backend's row-level security (RLS) remains the authoritative access control layer. Dynamic filtering is a UX optimisation: it keeps the LLM's tool list relevant and prevents wasted calls to endpoints the agent can't access.
+
+#### Static override with `RAYTIO_TOOL_DOMAINS`
+
+Set `RAYTIO_TOOL_DOMAINS` (comma-separated) to bypass dynamic resolution entirely. This is useful when you want to:
+
+- Give each domain **its own credentials** (e.g. a DSM agent and a PPM agent), since each registration is a separate process with its own env.
+- **Restrict** an agent below its actual role (e.g. force `ppm-readonly` even though the account has `PROJECT_USER`).
+- **Lock in** a known domain set regardless of backend role changes.
+
+**Available domains** (source: `src/tools/domains.ts`, also listed at the top of `docs/tools.md`):
+
+| Domain ID | Notes |
+|---|---|
+| `dsm` | Data Sharing & Requests |
+| `ppm` | Project & Program Management (full read + write) |
+| `prm` | Party Relationship Management |
+| `ppm-readonly` | Read-only subset of PPM — no create/update/status transitions |
+| `wrm` | Worker Relationship Management (full read + write) |
+| `wrm-readonly` | Read-only subset of WRM — no create/update operations |
+
+**Example — separate DSM and PPM registrations with different credentials:**
+
+```bash
+claude mcp add raytio-dsm -s user \
+  -e RAYTIO_TOOL_DOMAINS=dsm \
+  -e RAYTIO_AGENT_USERNAME=dsm-agent@example.com \
+  -e RAYTIO_AGENT_PASSWORD=... \
+  -e RAYTIO_AGENT_ENCRYPTION_PASSWORD=... \
+  -e RAYTIO_AGENT_CUSTOMER_ID=... \
+  -- npx -y raytio-mcp-server
+
+claude mcp add raytio-ppm -s user \
+  -e RAYTIO_TOOL_DOMAINS=ppm \
+  -e RAYTIO_AGENT_USERNAME=ppm-agent@example.com \
+  -e RAYTIO_AGENT_PASSWORD=... \
+  -e RAYTIO_AGENT_ENCRYPTION_PASSWORD=... \
+  -e RAYTIO_AGENT_CUSTOMER_ID=... \
+  -- npx -y raytio-mcp-server
+```
+
+**Example — read-only PPM for a separate audit agent:**
+
+```bash
+claude mcp add raytio-ppm-ro -s user \
+  -e RAYTIO_TOOL_DOMAINS=ppm-readonly \
+  -e RAYTIO_AGENT_USERNAME=ppm-readonly@example.com \
+  ...
+  -- npx -y raytio-mcp-server
+```
+
+The same pattern works in Codex CLI by varying `RAYTIO_TOOL_DOMAINS` and the credential env vars per `[mcp_servers.<name>]` block.
+
+## Prerequisites
+
+All installs need a Raytio account with agent credentials, a customer ID, and Cognito access. Installing from a local clone additionally requires:
+
+- Node.js 20 or higher (use `nvm use` — `.nvmrc` pins the version)
+- npm or yarn
+
+## Installation (local clone)
+
+Skip this if you registered the server via `npx` above.
+
+```bash
+npm install
+```
+
+## Configuration
+
+### Environment Variables
+
+Copy `config.env.example` to `config.env` in the server's root directory and fill in the values below. The server resolves `config.env` relative to its own install location, so it works regardless of which directory Claude Code (or any other MCP client) launches it from. To point at a different file, set `RAYTIO_CONFIG_FILE=/absolute/path/to/creds.env`. Real `process.env` variables always take precedence over anything in the file.
+
+```env
+# Raytio API Configuration
+RAYTIO_API_BASE_URL=https://api.rayt.io
+RAYTIO_COGNITO_USER_POOL_ID=us-east-1_xxxxxxxxx
+RAYTIO_COGNITO_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
+RAYTIO_COGNITO_REGION=us-east-1
+
+# Agent User Credentials
+RAYTIO_AGENT_USERNAME=agent@example.com
+RAYTIO_AGENT_PASSWORD=your-agent-password
+RAYTIO_AGENT_ENCRYPTION_PASSWORD=your-encryption-password
+RAYTIO_AGENT_CUSTOMER_ID=00000000-0000-0000-0000-000000000000
+
+# Target User
+RAYTIO_TARGET_USER_EMAIL=user@example.com
+
+# Optional: Request Settings
+RAYTIO_REQUEST_TIMEOUT_SECONDS=600
+RAYTIO_POLL_INTERVAL_SECONDS=5
+RAYTIO_REQUEST_EXPIRY_MINUTES=10
+```
+
+See `config.env.example` for the full template.
+
+## Building
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `dist/` directory.
+
+## Running
+
+### Development Mode
+```bash
+npm run dev
+```
+
+### Production Mode
+```bash
+npm start
+```
+
+The server runs in stdio mode for MCP communication.
+
+## Tools
+
+The full catalogue of exposed tools — names, descriptions, and parameters — is **generated from source** at [`docs/tools.md`](./docs/tools.md). Regenerate it after adding or changing tools:
+
+```bash
+npm run docs:tools
+```
+
+### Error codes
+
+Tools return structured responses; error codes common across domains:
+
+- `PPM_NOT_FOUND` — ID doesn't exist or RLS hides it (PPM only)
+- `PPM_VALIDATION` — Input failed validation (PPM only)
+- `API_ERROR` — Network or server error (all tools)
+
+### Usage example (DSM)
+
+End-to-end flow: list schemas → create application → create form → send request → poll for the encrypted submission.
+
+```javascript
+const schemas = await list_schemas();
+
+const aa = await create_access_application({
+  name: 'Tax Filing Assistant',
+  description: 'Collecting tax information',
+});
+
+const form = await create_form({
+  access_application_id: aa.data.access_application_id,
+  system_schemas: ['ss_Right_To_Work', 'ss_Phone_Number'],
+  recipient_email: 'user@example.com',
+});
+
+const request = await send_request({
+  access_application_id: aa.data.access_application_id,
+  short_link_key: form.data.short_link_key,
+  recipient_email: 'user@example.com',
+  message: 'Please share your information',
+  expiry_minutes: 10,
+});
+
+let data = null;
+while (!data) {
+  const result = await poll_and_retrieve({
+    request_short_code: request.data.request_short_code,
+  });
+  if (result.data) data = result.data;
+  else await sleep(5000);
+}
+```
+
+## Architecture
+
+### Components
+
+- **Config Management**: Zod-validated environment variable loading
+- **Authentication**: AWS Cognito JWT token management with caching
+- **API Client**: Axios-based REST client with automatic token refresh
+- **Schema Loader**: File system-based schema loading and caching
+- **Encryption**:
+  - Maxcryptor: AES-256-GCM with PBKDF2 key derivation
+  - WADEK: Wrapped Asymmetric DEK for key sharing
+- **Tool Registry**: Unified `Tool` interface with Zod schema validation and `zod-to-json-schema` conversion
+- **DSM Tools**: Data request workflow (in `src/tools/dsm/`)
+- **PPM Tools**: Work item and activity management (in `src/tools/ppm/`)
+- **PRM Tools**: Party relationship management (in `src/tools/prm/`)
+- **WRM Tools**: Worker, model, MCP server/tool, role, guardrail, eval scorer, and agent run management (in `src/tools/wrm/`)
+- **MCP Server**: Stdio-based server implementing MCP protocol
+
+### Security
+
+- **End-to-End Encryption**: All data is encrypted with user's password
+- **WADEK Key Wrapping**: DEKs are wrapped with recipient's password
+- **JWT Authentication**: Cognito-based authentication with automatic refresh
+- **No Plaintext Storage**: Encryption passwords never leave the client
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+
+# Run specific test file
+npm test src/tools/list-schemas.test.ts
+```
+
+## Development
+
+### Project Structure
+
+```
+src/
+├── index.ts                          # MCP server entry point (dispatches via registry)
+├── config.ts                         # Configuration management
+├── raytio/
+│   ├── auth.ts                       # Cognito authentication + getCurrentUserId()
+│   ├── api-client.ts                 # REST API client (get/post/put/patch/delete + RequestOptions)
+│   └── types.ts                      # Auth type definitions
+├── crypto/
+│   ├── maxcryptor.ts                 # AES-256-GCM encryption
+│   └── wadek.ts                      # WADEK key wrapping
+├── schemas/
+│   └── loader.ts                     # Schema file loader
+├── ppm/                              # PPM domain helpers
+│   ├── types.ts                      # WorkItem, Activity interfaces
+│   ├── projection.ts                 # WORK_ITEM_SELECT, ACTIVITY_SELECT constants
+│   └── filters.ts                    # buildPostgrestQuery()
+├── prm/                              # PRM domain helpers
+│   ├── types.ts                      # Party interfaces
+│   └── projection.ts                 # PRM SELECT constants
+├── wrm/                              # WRM domain helpers
+│   ├── types.ts                      # WRM entity interfaces
+│   └── projection.ts                 # WRM SELECT constants
+└── tools/
+    ├── types.ts                      # ToolResponse + error codes
+    ├── registry.ts                   # Tool + ToolContext interfaces
+    ├── domains.ts                    # Domain definitions + resolveDomains()
+    ├── role-mapping.ts               # Role → domain resolution
+    ├── dsm/                          # DSM tools
+    │   ├── index.ts
+    │   └── ...
+    ├── ppm/                          # PPM tools
+    │   ├── index.ts
+    │   └── ...
+    ├── prm/                          # PRM tools
+    │   ├── index.ts
+    │   └── ...
+    └── wrm/                          # WRM tools
+        ├── index.ts
+        └── ...
+```
+
+### Adding New Tools
+
+1. Create a tool file implementing the `Tool` interface from `src/tools/registry.ts`
+2. Add tests in a co-located `*.test.ts` file
+3. Export from the relevant `index.ts` (dsm, ppm, or wrm)
+
+## Troubleshooting
+
+### Authentication Errors
+
+- Verify Cognito credentials are correct
+- Check user has access to the Raytio API
+- Ensure Cognito user pool ID and client ID match
+
+### Decryption Errors
+
+- Verify encryption password matches user's password
+- Check WADEK was created with correct password
+- Ensure data format matches expected schema
+
+### API Errors
+
+- Check API base URL is correct
+- Verify network connectivity
+- Review error messages in tool responses
+
+## Versioning and updates
+
+This server follows [semver](https://semver.org). The current version is published in `package.json` and logged at startup.
+
+**Keeping your install up to date** (local clone):
+
+```bash
+cd /path/to/mcp-server
+git pull
+npm install     # if package.json changed
+npm run build
+```
+
+Restart any running Claude Code sessions (exit/relaunch, or `/mcp` → reconnect) to pick up the new `dist/`. New sessions load the latest build automatically.
+
+The server is published to npm on every merge to `main` (see `.gitlab-ci.yml`), so end users can run the latest release with:
+
+```bash
+npx -y raytio-mcp-server
+```
+
+or register it in Claude Code / Codex CLI with `npx` instead of a local path.
+
+## Contributing
+
+See [`AGENTS.md`](./AGENTS.md) for contributor conventions — especially the requirement to bump `package.json` version on every branch / MR.
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions, please open an issue in the repository.

package/config.env.example

@@ -0,0 +1,32 @@
+# Raytio API Configuration
+RAYTIO_API_BASE_URL=https://api.rayt.io
+RAYTIO_COGNITO_USER_POOL_ID=us-east-1_xxxxxxxxx
+RAYTIO_COGNITO_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
+RAYTIO_COGNITO_REGION=us-east-1
+
+# Agent User Credentials
+RAYTIO_AGENT_USERNAME=agent-assistant@example.com
+RAYTIO_AGENT_PASSWORD=your-agent-password-here
+RAYTIO_AGENT_ENCRYPTION_PASSWORD=your-encryption-password-here
+RAYTIO_AGENT_CUSTOMER_ID=00000000-0000-0000-0000-000000000000
+
+# Target User
+RAYTIO_TARGET_USER_EMAIL=user@example.com
+
+# Optional: static override for which tool domains are exposed (comma-separated).
+# If set, bypasses dynamic role-based resolution entirely.
+# If unset, the server queries the user's backend roles at startup and exposes
+# only the domains the user has permissions for.
+# Run `npm run docs:tools` to see available domain IDs.
+# Example: RAYTIO_TOOL_DOMAINS=ppm-readonly
+# RAYTIO_TOOL_DOMAINS=dsm,ppm
+
+# Optional: Embedding Settings for semantic memory tools
+RAYTIO_EMBEDDING_API_KEY=your-embedding-api-key-here
+RAYTIO_EMBEDDING_API_URL=https://api.openai.com/v1/embeddings
+RAYTIO_EMBEDDING_MODEL=text-embedding-3-small
+
+# Optional: Request Settings
+RAYTIO_REQUEST_TIMEOUT_SECONDS=600
+RAYTIO_POLL_INTERVAL_SECONDS=5
+RAYTIO_REQUEST_EXPIRY_MINUTES=10