diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea68642..64d248d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,7 +100,7 @@ Stable releases are driven by Changesets and the [Release workflow](.github/work Thus, after you merge a feature PR, you can either: 1. Merge the subsequent release PR to publish to npm if you want it released immediately, or -2. Wait a few feature PRs build up, before merging a release PR and publishing to npm (this also allows you to split up your changes into multiple PRs without releasing). +2. Let a few feature PRs build up before merging a release PR and publishing to npm (this also allows you to split up your changes into multiple PRs without releasing). ### Changesets diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 366128b..a8e1d88 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -1,13 +1,13 @@ # Transcend MCP Servers -> **Alpha** — these packages are under active development and have not yet been published to npm. APIs may change without notice. +> **Beta** — these packages are under active development. APIs may change without notice. [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers that let AI agents interact with the [Transcend](https://transcend.io) privacy platform. Every server supports both **stdio** (local process) and **Streamable HTTP** (remote hosting) transports, so it works with any compliant client (Claude Desktop, Cursor, Cline, custom agents, etc.). ## Prerequisites - **Node.js** ≥ 22.12 (see each CLI package’s `engines` in `package.json`). -- Packages are **alpha** and **not yet published to npm**. Global install and `npx` examples below assume a future registry release. **Until then**, clone this repository: copy [`secret.env.example`](../../secret.env.example) to **`secret.env`** at the repo root and set `TRANSCEND_API_KEY`; then from the repo root run `pnpm exec turbo run build --filter="@transcend-io/..."` (trailing `...` includes dependencies such as `mcp-server-base`), then `set -a && source ./secret.env && set +a` and `pnpm -F @transcend-io/ exec node ./dist/cli.mjs` (or use [`scripts/mcp-run.sh`](../../scripts/mcp-run.sh) — see **Run from the monorepo** in each package README and [CONTRIBUTING.md](../../CONTRIBUTING.md#mcp-servers)). +- Packages are in **beta**. Install via `npm install -g @transcend-io/` or use `npx -y @transcend-io/`. To develop from source, clone this repository: copy [`secret.env.example`](../../secret.env.example) to **`secret.env`** at the repo root and set `TRANSCEND_API_KEY`; then from the repo root run `pnpm exec turbo run build --filter="@transcend-io/..."` (trailing `...` includes dependencies such as `mcp-server-base`), then `set -a && source ./secret.env && set +a` and `pnpm -F @transcend-io/ exec node ./dist/cli.mjs` (or use [`scripts/mcp-run.sh`](../../scripts/mcp-run.sh) — see **Run from the monorepo** in each package README and [CONTRIBUTING.md](../../CONTRIBUTING.md#mcp-servers)). In client config, `npx` with `-y @transcend-io/...` runs that package’s published `bin` (see `package.json` in each package). @@ -17,7 +17,9 @@ There are two ways to consume the MCP tools, and they can be mixed freely. ### Unified server -Install **`@transcend-io/mcp`** to get every tool (71 across all domains) in a single process. This is the fastest way to get started and is ideal when your agent can handle a large tool set. +Install **`@transcend-io/mcp`** to get every tool (70 across all domains) in a single process. This is the fastest way to get started and is ideal when your agent can handle a large tool set. + +**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`): ```json { @@ -31,10 +33,27 @@ Install **`@transcend-io/mcp`** to get every tool (71 across all domains) in a s } ``` +**VS Code** (`.vscode/mcp.json`): + +```json +{ + "servers": { + "transcend": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@transcend-io/mcp"], + "env": { "TRANSCEND_API_KEY": "your-api-key" } + } + } +} +``` + ### Domain servers Install only the domains you need. Smaller tool counts help AI agents stay focused and reduce token overhead from tool descriptions. You can run multiple domain servers side by side. +**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`): + ```json { "mcpServers": { @@ -52,6 +71,27 @@ Install only the domains you need. Smaller tool counts help AI agents stay focus } ``` +**VS Code** (`.vscode/mcp.json`): + +```json +{ + "servers": { + "transcend-consent": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@transcend-io/mcp-server-consent"], + "env": { "TRANSCEND_API_KEY": "your-api-key" } + }, + "transcend-dsr": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@transcend-io/mcp-server-dsr"], + "env": { "TRANSCEND_API_KEY": "your-api-key" } + } + } +} +``` + ### Picking the right approach | Scenario | Recommendation | @@ -100,10 +140,10 @@ When both cookie and API key headers are present, the session cookie takes prior | Package | Binary | Tools | Description | | ----------------------------------------------------- | --------------------------- | ----: | ------------------------------------------------ | -| [`mcp`](./mcp/) | `transcend-mcp` | 71 | Unified server — all tools in one process | +| [`mcp`](./mcp/) | `transcend-mcp` | 70 | Unified server — all tools in one process | | [`mcp-server-admin`](./mcp-server-admin/) | `transcend-mcp-admin` | 8 | Organization, users, teams, API keys | | [`mcp-server-assessment`](./mcp-server-assessment/) | `transcend-mcp-assessment` | 14 | Privacy assessments, templates, groups | -| [`mcp-server-consent`](./mcp-server-consent/) | `transcend-mcp-consent` | 12 | Consent management, cookie & data-flow triage | +| [`mcp-server-consent`](./mcp-server-consent/) | `transcend-mcp-consent` | 11 | Consent management, cookie & data-flow triage | | [`mcp-server-base`](./mcp-server-base/) | — | — | Shared infrastructure (not installed directly) | | [`mcp-server-discovery`](./mcp-server-discovery/) | `transcend-mcp-discovery` | 6 | Data discovery, classification, NER | | [`mcp-server-dsr`](./mcp-server-dsr/) | `transcend-mcp-dsr` | 12 | Data subject requests (submit, track, respond) | diff --git a/packages/mcp/mcp-server-admin/README.md b/packages/mcp/mcp-server-admin/README.md index 86f5f48..e572eed 100644 --- a/packages/mcp/mcp-server-admin/README.md +++ b/packages/mcp/mcp-server-admin/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-admin -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for organization administration. Provides tools for managing users, teams, API keys, and organization settings. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-admin ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -87,4 +87,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-assessment/README.md b/packages/mcp/mcp-server-assessment/README.md index 2e32398..7dfb06d 100644 --- a/packages/mcp/mcp-server-assessment/README.md +++ b/packages/mcp/mcp-server-assessment/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-assessment -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for privacy assessments. Provides tools for creating, managing, and completing privacy impact assessments and assessment templates. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-assessment ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -93,4 +93,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-base/README.md b/packages/mcp/mcp-server-base/README.md index 9064e5f..6214141 100644 --- a/packages/mcp/mcp-server-base/README.md +++ b/packages/mcp/mcp-server-base/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-base -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Shared infrastructure for all Transcend MCP Server packages. Provides the base GraphQL and REST clients, tool type definitions, validation helpers, error handling, and the `createMCPServer` factory used by each domain server. @@ -8,9 +8,9 @@ Requires **Node.js ≥ 22.12** (see `engines` in `package.json`) when building o ## Install -This package is **not** a standalone MCP CLI: it has no `bin`. Domain servers and the unified `mcp-server` depend on it. In this repository it is consumed as `workspace:*`; when published to npm, downstream packages will list it as a normal dependency. +This package is **not** a standalone MCP CLI: it has no `bin`. Domain servers and the unified `mcp` package depend on it. In this repository it is consumed as `workspace:*`; when published to npm, downstream packages will list it as a normal dependency. -Until publication, use a checkout of this repository (see **Development** below). +For development, use a checkout of this repository (see **Development** below). API keys for running a domain or unified MCP server locally belong in the repository root **`secret.env`** (copy from [`secret.env.example`](../../../secret.env.example)); see [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers). diff --git a/packages/mcp/mcp-server-consent/README.md b/packages/mcp/mcp-server-consent/README.md index 5b2cc97..c5d9e6e 100644 --- a/packages/mcp/mcp-server-consent/README.md +++ b/packages/mcp/mcp-server-consent/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-consent -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for consent management. Provides tools for managing consent preferences, cookie triage, data flow management, and consent regime configuration. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-consent ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -80,10 +80,9 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout - `consent_set_preferences` — Set consent preferences - `consent_list_purposes` — List tracking purposes - `consent_list_data_flows` — List data flows +- `consent_list_cookies` — List cookies - `consent_list_airgap_bundles` — List Airgap bundles - `consent_list_regimes` — List consent regimes -- `consent_list_triage_cookies` — List cookies for triage -- `consent_list_triage_data_flows` — List data flows for triage - `consent_get_triage_stats` — Get cookie/data flow triage statistics - `consent_update_cookies` — Update cookies (approve, junk, assign purposes) - `consent_update_data_flows` — Update data flows @@ -91,4 +90,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-discovery/README.md b/packages/mcp/mcp-server-discovery/README.md index 916e938..2c83d20 100644 --- a/packages/mcp/mcp-server-discovery/README.md +++ b/packages/mcp/mcp-server-discovery/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-discovery -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for data discovery. Provides tools for scanning, classifying, and extracting entities from data. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-discovery ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -85,4 +85,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-dsr/README.md b/packages/mcp/mcp-server-dsr/README.md index 9f7efa4..5af9c44 100644 --- a/packages/mcp/mcp-server-dsr/README.md +++ b/packages/mcp/mcp-server-dsr/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-dsr -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for data subject requests (DSR). Provides tools for submitting, tracking, and responding to privacy requests such as access, erasure, and opt-out. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-dsr ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -91,4 +91,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-inventory/README.md b/packages/mcp/mcp-server-inventory/README.md index 375328d..0981056 100644 --- a/packages/mcp/mcp-server-inventory/README.md +++ b/packages/mcp/mcp-server-inventory/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-inventory -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for data inventory management. Provides tools for managing data silos (integrations), data points, vendors, categories, and identifiers. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-inventory ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -89,4 +89,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-preferences/README.md b/packages/mcp/mcp-server-preferences/README.md index 6313ed7..a0fdbf0 100644 --- a/packages/mcp/mcp-server-preferences/README.md +++ b/packages/mcp/mcp-server-preferences/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-preferences -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for privacy preference management. Provides tools for querying, upserting, and deleting user privacy preference records and their identifiers. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-preferences ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -85,4 +85,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp-server-workflows/README.md b/packages/mcp/mcp-server-workflows/README.md index a7c24d1..9221adc 100644 --- a/packages/mcp/mcp-server-workflows/README.md +++ b/packages/mcp/mcp-server-workflows/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp-server-workflows -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Transcend MCP Server for workflow configuration. Provides tools for listing workflows, email templates, and updating workflow settings. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp-server-workflows ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -82,4 +82,4 @@ See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout ## Related packages -Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md) which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. +Also available as part of the unified [`@transcend-io/mcp`](../mcp/README.md), which includes all domains. See the [root README](../../../README.md#mcp-servers) for the full list. diff --git a/packages/mcp/mcp/README.md b/packages/mcp/mcp/README.md index 8468f81..a904cd5 100644 --- a/packages/mcp/mcp/README.md +++ b/packages/mcp/mcp/README.md @@ -1,6 +1,6 @@ # @transcend-io/mcp -> **Alpha** — this package is under active development and has not yet been published to npm. APIs may change without notice. +> **Beta** — this package is under active development. APIs may change without notice. Unified Transcend MCP Server that combines all domain tools into a single server. This is the "everything in one place" option — install this package when you want access to all 70+ Transcend tools at once. @@ -10,13 +10,13 @@ For local runs from this repository, copy [`secret.env.example`](../../../secret ## Install -When the package is available on npm, install the CLI globally: +Install the CLI globally: ```bash npm install -g @transcend-io/mcp ``` -Until then, run from a checkout of this repository (see **Run from the monorepo** below). +Or run from a checkout of this repository (see **Run from the monorepo** below). ## Usage @@ -86,16 +86,6 @@ pnpm -F @transcend-io/mcp exec node ./dist/cli.mjs See [CONTRIBUTING.md](../../../CONTRIBUTING.md#mcp-servers) for workspace layout and `pnpm --filter` workflows. -### Environment variables - -| Variable | Required | Default | Description | -| ------------------- | -------- | ------------------------------------------ | -------------------------------------------------- | -| `TRANSCEND_API_KEY` | Yes | — | Transcend API key | -| `TRANSCEND_API_URL` | No | `https://api.transcend.io` | GraphQL backend API URL (matches CLI convention) | -| `SOMBRA_URL` | No | `https://multi-tenant.sombra.transcend.io` | Sombra REST API URL (matches CLI / SDK convention) | - -**Monorepo:** keep these in root **`secret.env`** (from [`secret.env.example`](../../../secret.env.example)); see **Run from the monorepo**. - ## Architecture This package composes all domain MCP packages via `ToolRegistry`, which aggregates tools from each domain (`getConsentTools`, `getDSRTools`, etc.) into a single tool namespace. A composed `TranscendGraphQLClient` mixes in all domain GraphQL capabilities so each tool has access to the API surface it needs.