Skip to main content
Glama
README.md
# albato-builder-mcp

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2.svg)](https://modelcontextprotocol.io)

[Albato](https://albato.com) is a no-code integration platform: users connect apps into automations
(bundles) without writing code. The Albato Builder is where developers add their own apps to the
platform: connections, triggers, actions and lists, built on top of the app's API.

This is an [MCP](https://modelcontextprotocol.io) server for the Albato Builder API. Connect it to Claude Code,
Claude Desktop or another MCP client, and the model can work with your Albato Builder apps directly. It
can read a whole version, create and edit actions, triggers, lists and connections, test-run requests
against the partner API, and check a version against the publication rules before it goes to
moderation.

The server is built so the model cannot break anything by accident:

- **It writes only to the private version.** It never touches the public version, a version shared by
  link, or a version under moderation.
- **Every write supports `dryRun`.** The server validates the body and shows it without sending it to the API.
- **Deletions and request test runs need your confirmation in the chat.** Fixes from a review are
  applied only to the items you pick.
- **Tokens never appear in tool responses or in the log.** Secrets in `test_request` output are masked too.

## Contents

- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Tools](#tools)
- [Version review](#version-review)
- [How it works](#how-it-works)
- [Project layout](#project-layout)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Known limitations](#known-limitations)
- [License](#license)

## Requirements

- **Node.js 20** or newer (`node --version`)
- **An Albato account token** (JWT). See [Get a token](#2-get-a-token)
- **An MCP client**: Claude Code, Claude Desktop or any client that supports stdio servers. A
  [Streamable HTTP mode](#http-mode) is also available

## Quick start

### 1. Install

```bash
git clone https://github.com/ermigut/albato-builder-mcp.git
cd albato-builder-mcp
npm install
```

### 2. Get a token

The token is an Albato user JWT. The
[`POST /user/auth`](https://api.albato.com/docs/v1/en/index.html#api-Auth-getAccessToken) method
trades your email and password for a token. The token is in `data.authToken` of the response, and its
expiry is in `data.authTokenExpirationDateTime`.

macOS, Linux, Git Bash:

```bash
curl -s -X POST https://api.albato.com/user/auth \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "<password>"}'
```

PowerShell (prints only the token):

```powershell
$body = @{ email = "you@example.com"; password = "<password>" } | ConvertTo-Json
(Invoke-RestMethod -Method Post -Uri https://api.albato.com/user/auth -ContentType "application/json" -Body $body).data.authToken
```

Your shell history keeps a command that contains a password, so clear it afterwards. Tokens expire.
When `npm run check` reports a token problem, get a new one.

### 3. Add the token to `.env`

Copy the template to `.env` in the repository root:

```bash
cp .env.example .env            # macOS, Linux, Git Bash
```

```powershell
Copy-Item .env.example .env     # PowerShell
```

Put the token after `ALBATO_TOKEN=`. `.env` is listed in `.gitignore`. Never put a token in code or in
`.env.example`.

### 4. Check the setup

```bash
npm run check
```

The check starts the server the way an MCP client does, lists its tools, prompts and rules catalog,
and makes one read-only API call. It creates and changes nothing. A healthy run looks like this:

```
  ok   server responds: {"name":"albato-builder","version":"0.1.0"}
  ok   tools available: 34
  ok   apps in the account: 3

Result: everything is in place. The server is ready to be connected to an MCP client.
```

Any problem is printed on a line that starts with `FAIL`, together with a hint (see
[Troubleshooting](#troubleshooting)). The script exits with code 1 when something fails, so you can
run it in CI.

### 5. Connect a client

You need the **absolute path** to `src/server.mjs`. The server reads the token from `.env` by itself,
so the client config doesn't need it.

**Claude Code:**

```bash
claude mcp add --scope user albato-builder -- node "/absolute/path/albato-builder-mcp/src/server.mjs"
```

`--scope user` makes the server available in every project. Without it, the server is available only
in the current folder. Run `claude mcp list` to confirm the server is registered. If you use
`--scope project`, Claude Code writes the path to `.mcp.json`, which is listed in `.gitignore`.

**Claude Desktop and other clients:** add the server to the client config. For Claude Desktop, the
file is `claude_desktop_config.json`. It is in `%APPDATA%\Claude\` on Windows and in
`~/Library/Application Support/Claude/` on macOS.

```json
{
  "mcpServers": {
    "albato-builder": {
      "command": "node",
      "args": ["/absolute/path/albato-builder-mcp/src/server.mjs"]
    }
  }
}
```

On Windows, write the path with forward slashes, for example
`C:/Users/me/albato-builder-mcp/src/server.mjs`. Restart the client after you edit the config.

To keep the token in the client config instead, add an `"env": { "ALBATO_TOKEN": "..." }` block next
to `args`. It takes precedence over `.env`.

### 6. Try it

Example requests:

- "Show my Albato apps"
- "Go through app 12345: what's in it and what looks broken"
- "Build a 'Create deal' action from this API documentation: ..." (the model shows the body with
  `dryRun` first, then writes it)
- "Test-run the request of the 'Create deal' action" (the model asks first, because the request goes
  to the partner API through a live connection)

For reviews, use the [review commands](#review-commands).

### HTTP mode

> **Experimental.** The HTTP mode works, but it's newer than the stdio mode and may change.

The same tools are also available over Streamable HTTP. This mode doesn't read tokens from `.env`.
Each user sends their own Albato token in `Authorization: Bearer`. The server identifies the user
through `/user/profile` and acts on their behalf.

```bash
npm run start:http   # http://127.0.0.1:8787/mcp
```

```bash
claude mcp add --transport http albato-builder-http http://127.0.0.1:8787/mcp --header "Authorization: Bearer <token>"
```

- Each connection gets its own MCP session, with its own write log, review runs, plans and fix
  history. One user's `reviewId` or `planId` returns "not found" for another user.
- Finding dismissals are shared per app. The audit log records who made each change (`user-<id>`).
- The `apply_fixes` confirmation (elicitation) comes back in the tool call response, so it works with
  clients that don't open a separate GET stream. The server waits up to 10 minutes for an answer.
- OAuth isn't supported yet. The mode works with clients that let you set request headers yourself.
- To listen on any address other than localhost, you must also set `MCP_ALLOWED_HOSTS`, which
  protects against DNS rebinding. The server doesn't terminate TLS: put it behind a reverse proxy.

## Configuration

You can set any variable in `.env` at the repository root, in the environment, or in the `env` block
of the client config. Values from the environment and the client config take precedence over the
file. `.env.example` lists every variable.

| Variable | Required | Purpose |
|---|---|---|
| `ALBATO_TOKEN` | yes (stdio) | Token of the main account |
| `ALBATO_BASE_URL` | no | API address without `/v1`. Default: `https://api.albato.com`. |
| `ALBATO_TOKEN_<NAME>` | no | Tokens of additional accounts (see below) |
| `ALBATO_BASE_URL_<NAME>` | no | API address for that token, if it differs |
| `ALBATO_CONTRACT` | no | Path to `builder-api.json`. Default: `contracts/builder-api.json` |
| `ALBATO_CREDENTIALS_CONTRACT` | no | Path to `credentials-api.json`. Default: `contracts/credentials-api.json` |
| `ALBATO_BUNDLE_CONTRACT` | no | Path to `bundle-api.json`. Default: `contracts/bundle-api.json` |
| `ALBATO_STATE_DIR` | no | Where dismissed findings and the fix audit log are stored. Default: `.state` |
| `MCP_HTTP_HOST` | no | HTTP mode: address to listen on. Default: `127.0.0.1` |
| `MCP_HTTP_PORT` | no | HTTP mode: port. Default: `8787` |
| `MCP_ALLOWED_HOSTS` | no | HTTP mode: comma-separated host names that clients use. Required when the server listens on anything other than localhost |

Use absolute paths. The server resolves a relative path from the folder the client started it in.

**Multiple accounts.** Each account needs its own token:

```
ALBATO_TOKEN=<main account>
ALBATO_TOKEN_PARTNER=<second account>
```

When more than one token is set, every tool takes a `token` parameter with the lowercase name (here,
`partner`). The name in `.env` can use any case. Without the parameter, the server uses
`ALBATO_TOKEN`. A token can access only its own account, and tool responses and logs show only the
token's name.

## Tools

The Builder exposes about 22 resources. Flat tools for each resource and operation would add up to
roughly 150, which is too many to fit in the model's context. Instead, the generic tools take a
`resource` parameter and validate the body against that resource's schema from the contract. Call
`describe_resource` before the first write to a resource.

| Group | Tools |
|---|---|
| Apps and versions | `list_apps` (with name search), `get_app_tree` (a whole version, with technical checks), `ensure_editable_version` |
| Read | `list_entities` (a projection by default, plus `full`, `expand` and `pick`), `get_entity`, `get_entities` (batch read) |
| Write | `create_entity`, `create_entities` (batch, where `"$N"` refers to entities created earlier in the same batch), `update_entity`, `update_entities` (batch), `sort_entities`, `copy_entity`, `restore_entity`, `delete_entity` |
| Schema | `describe_resource`: fields, allowed codes and notes the contract doesn't cover |
| Testing | `test_request` (runs one request through a live connection), `check_response_mapping` (compares the mapping with a sample response, offline), `run_credential_wizard` (runs the multi-step connection wizard the way a bundle does) |
| Connections | `list_credentials`, `describe_credential`, `create_credential`, `update_credential`, `refresh_credential`, `test_credential`, `delete_credential` |
| Review | `review_version`, `diff_versions`, `dismiss_finding`, `plan_fixes`, `apply_fixes`, `revert_fixes` |
| Publication | `submit_for_moderation`, `share_version`, `list_categories` |

The server also provides four MCP prompts (see [Review commands](#review-commands)) and the resource
`albato://rules/publication`, which holds the full rules catalog.

### Built-in behavior

- **Confirmations.** `delete_entity` and `test_request` do nothing without `confirmed: true`. Without
  it, `delete_entity` shows what would be deleted, including child lists, wizard steps and fields that
  would lose their list. Deletion is permanent for entities created in the current version. Triggers
  and actions that also exist in earlier versions are only marked `deprecated`.
- **Editable version.** Before each write, including a `dryRun`, the server checks the version's
  status. If the version is closed, the error tells you what to do next: use the private version, or
  call `ensure_editable_version`. That tool creates a new version only with your consent and with the
  name you give it. A new version copies the latest version in full, and its entity IDs match.
- **Batches.** For more than two reads, creates or edits, use the batch tools. They validate every
  operation before the first write and take one version lock. You can roll back a batch with
  `revert_fixes`. There's deliberately no batch delete.
- **Helpful validation.** A validation error names the correct value instead of just saying
  "invalid". The server also catches mistakes the API accepts without complaint, for example:
  - a list request without pagination, or pagination that never changes the page
  - a webhook trigger without a Webhook connection field, a subscription without the URL, or a
    subscription without an unsubscribe request
  - a `{{systemVar.…}}` substitution with no matching variable
  - status handlers that overlap
  - wizard steps in the wrong order
  - broken field key syntax
  - async and migration setups that will never start
- **Nested arrays.** When you send a nested array in an edit, the backend replaces the whole array.
  An element without an `id` is created again, and an element missing from the array is deleted. The
  validator warns about this. To change one part, send only that part, for example
  `{requests: [{id, response: {id, cfsMappings}}]}`.
- **Existing errors.** An edit is rejected only for problems the edit itself introduces. A problem
  that existed before the edit produces a warning instead.
- **Test runs.**
  - `test_request` masks authorization headers and parameters (`Bearer <hidden: 82 chars>`).
  - It returns `responseAudit`, which lists the response fields that have no mapping.
  - It suggests a ready-made error handler built from the partner's real error response.
  - On a paginated request, it explains how to read the result: a bundle fetches every page, but
    you see only the last one.
- **Subscriptions are never recreated.** Running bundles depend on a specific webhook subscription.
  The server rejects deleting a subscription that a trigger still uses and rejects replacing a
  trigger's `dataStarterId`. Editing the subscription in place is allowed.
- **Lists are fetched in full.** The API returns 20 records per page, so the server pages through the
  rest for you.
- **Workspaces.** The client sets the `WorkspaceId` header itself, based on the app in the request.

## Version review

A review checks the version as it currently exists in the account, not what was said in the chat. A
version an agent built five minutes ago and one a partner built in the UI months ago are checked the
same way. The same engine handles four scenarios:

- self-check after a build (`scope: "session"`)
- publication readiness (`scope: "all"`)
- changes since the public version (`diff_versions`, `scope: "changed"`)
- a comparison with the task description

### Rules

The rules are data, stored in `rules/publication.yaml` (73 rules). Each rule has a level (`blocker`,
`warning`, `info`), a class and a wording. The rule families are:

| Prefix | Covers |
|---|---|
| `PUB-GEN`, `PUB-NAME`, `PUB-FLD`, `PUB-ACT`, `PUB-TRG`, `PUB-ENUM`, `PUB-SORT`, `PUB-CAT`, `PUB-CRT`, `PUB-VAR`, `PUB-MIG` | Publication rules: naming, descriptions, fields, ordering, categories, item creators, variables, migration |
| `PUB-UPD` | Updating a public version. Users' bundles move to the new version automatically, so a breaking change is a blocker |
| `TECH-*` | Technical checks: async, pagination, webhooks, wizard, nesting, keys, variables, status handlers, migration |
| `HYG-*` | Hygiene |

- **Classes.**
  - `auto` and `heuristic` rules are checked by the server. A heuristic finding always includes
    `why`.
  - `judgment` rules are not decided by the server, which never calls a model. Instead, it returns a
    question and a data packet (`include: ["packet"]`), and the host model makes the call by following
    the `review-publication` prompt.
- **Verdict.** The server's verdict is either `blocked` or `no_auto_blockers`. It never says a
  version is "ready".
- **Response budget.** If one rule has more than 10 findings, the extra ones are collapsed into
  `truncated`, and blockers come first.
- **App text is data.** Names, hints and scripts from the app are marked as user content, and the
  server never follows instructions found in them. Secrets in reports are masked.

### Apps in several languages

A version's languages come from the version itself (`languages`), and every name and hint check runs
for each of them: a name missing in one language, a lowercase name, a translation copied from the
English one. `titleEn` is always required; the other languages follow the app.

### Review, plan, apply

A review is read-only. Fixes go through a separate chain:

1. `review_version` returns findings and a `reviewId`.
2. `plan_fixes` turns them into numbered items. Each item shows "before → after", a risk level and a
   kind.
3. You answer, and `apply_fixes` applies only the items you picked.
   - Items marked `breaking` or `destructive` are left out of "all". They are applied only when you
     name their numbers explicitly (`named`).
   - If an entity changed after the plan was made, its item is skipped.
   - An edit that would replace a whole array of objects isn't applied.
   - When the client supports elicitation, the server asks for consent in a client dialog, without
     going through the model.
4. After applying, `recheck` reports which findings were closed, which remain and which are new.
5. `revert_fixes` restores the "before" state.

Every applied fix is written to `.state/audit.jsonl`.

**False positives.** You can dismiss a finding with `dismiss_finding` and a reason. A dismissal
applies to one rule, entity and field, and it's lifted automatically when the entity changes.
Dismissals are stored in `.state/dismissals.json`.

**Self-check.** The server's instructions tell the model to run `review_version` with
`scope: "session"` before it reports a build as done. You don't need to ask for it.

### Publication

- **`submit_for_moderation`.** Without `confirmed`, the tool only assembles the moderation form and
  shows it.
  - Missing fields are filled from the app's previous submission, the account profile and `info`.
    Anything that can't be found is listed in `missing`.
  - The test password is masked.
  - The whole version is reviewed first. A version with blockers isn't submitted without a `reason`.
    A recent full review is reused if the server hasn't written to the version since.
  - Skipping the review (`skipReview` + `reason`) is written to the audit log.
- **`share_version`.** This gives access by link and doesn't need a review. Without `confirmed`, it
  returns the link and explains what will happen. An app has one permanent link. Sharing makes the
  version final.
- **`list_categories`.** This returns the catalog categories. The server checks the categories you
  write to `info` against this list.

After you submit or share a version, it can no longer be edited.

### Review commands

The server provides four MCP prompts. In Claude Code they work as slash commands: type `/` and the
start of the name. The full name is `/mcp__albato-builder__<prompt>`. Each prompt adds a ready-made
workflow to the conversation: which tools to call, which rules to apply, and what the report should
look like. None of them fixes anything on its own.

| Command | Arguments | Use it to | You get |
|---|---|---|---|
| `review-publication` | `appId`, `versionId`?, `apiDocs`? | check a version before moderation | A verdict, blockers per entity (server findings and the model's judgment kept apart), warnings, and what couldn't be checked |
| `review-against-task` | `appId`, `task`, `versionId`? | compare what was built with the task | A "requirement – ✅/⚠️/❌ – where" table, extras beyond the task, and rule findings |
| `changes-since-public` | `appId` | see what users will get | Breaking changes first, then an "added / changed / fixed" changelog |
| `moderation-reply` | `appId`, `versionId`? | reply to the developer after a review | Per-entity text on what's wrong and how to fix it, without internal IDs or JSON |

`?` marks an optional argument. Without `versionId`, the latest version is used. `apiDocs` can be a
link to the partner's API docs, an OpenAPI spec or plain text. Without it, rules such as "covers as
many fields as the API has" are reported as "not checked" instead of "ok".

## How it works

The server doesn't hard-code the API. It reads machine-readable API contracts that ship with the
repository in `contracts/`:

- `builder-api.json` covers the Builder resources.
- `credentials-api.json` covers account connections.
- `bundle-api.json` covers the bundle wizard, which `run_credential_wizard` uses.

At startup, the server derives resources and their JSON schemas from the endpoint paths and nested
models, so there is no hand-written code per resource. The contracts are updated together with the
repository when the API changes; don't edit them by hand.

```
contracts/builder-api.json ─> contract.mjs ─> tools.mjs ─> mcp-server.mjs ─> server.mjs (stdio)
                              registry,        tool          tools, prompts,   http.mjs   (HTTP)
                              schemas          registry      rules resource
                                 │
                                 └─> validate.mjs, rules.mjs, nesting.mjs, async.mjs, migration.mjs,
                                     variables.mjs, keys.mjs, handler-order.mjs, versions.mjs ...
                                     checks applied before every write

rules/publication.yaml ─> catalog.mjs ─> review-tools.mjs ─> snapshot.mjs, review.mjs,
                                                             tech.mjs, checks.mjs, diff.mjs, state.mjs
```

- **Validation runs in two layers.** The contract schema checks the shape and the allowed codes.
  Semantic rules in `src/*.mjs` catch the cases the API accepts silently but that fail later in a
  live bundle. The `TECH-*` review rules reuse the same code, so a warning on write matches the
  review finding word for word.
- **Connections.** Each app defines its own connection form, so the contract doesn't describe the
  body. The tools read the form from `meta` at runtime and build the internal field names
  themselves. The model works with field codes.
- **Testing is per request.** The server test-runs one request at a time, and only with your
  confirmation. It doesn't run whole bundles, on purpose. A hook trigger needs a real event, an API
  trigger needs existing data, and an action creates real records in someone's account. The model
  can't set up any of that on its own. So the loop is: build with the tools, test each request with
  `test_request`, then hand the result to the user.

## Project layout

```
src/
  server.mjs         stdio entry point: tokens from .env, state in .state/
  http.mjs           HTTP entry point (Streamable HTTP, see remote.mjs)
  mcp-server.mjs     the server without a transport: tools, prompts, rules resource, elicitation
  tools.mjs          generic and specialized tools (no SDK dependency, tested offline)
  review-tools.mjs   review_version, diff_versions, dismiss_finding, plan/apply/revert_fixes
  contract.mjs       loads contracts, derives resources and schemas
  client.mjs         HTTP client: Bearer auth, response envelope, timeouts, custom verbs
  env.mjs, access.mjs  .env loading and token resolution
  ...                validation, review and domain modules
rules/publication.yaml   review rules catalog
contracts/               API contracts (builder, credentials, bundle)
scripts/check.mjs        npm run check
scripts/measure.mjs      npm run measure
test/                    offline tests
.env.example             settings template
.state/                  local state: dismissals, audit log (gitignored)
```

## Development

Run everything from the repository root.

```bash
npm install
npm test             # offline tests: no network or token needed
npm run check        # client → server → API chain, read-only
npm start            # stdio server (normally the MCP client starts it)
npm run start:http   # HTTP server on http://127.0.0.1:8787/mcp
npm run measure -- <appId> [versionId] [--token=<name>] [--json]
```

`npm run measure` walks a typical review path against a real app and reports the time and response
size (≈tokens) of each tool call. It's read-only. Run it before and after a change to compare how much
context the tools use.

When you change `rules/publication.yaml`, keep in mind that the tests won't accept an `auto` or
`heuristic` rule unless it comes with a case that violates it.

## Troubleshooting

Start with `npm run check`. It tells a token problem apart from a network problem and from a missing
contract.

| Symptom | Cause | Fix |
|---|---|---|
| `ALBATO_TOKEN is not set` | The server didn't find a token | Make sure the file is named exactly `.env` (not `.env.txt`), is in the repository root, and has a non-empty `ALBATO_TOKEN=` line |
| `looks like a token problem` | The API returned 401 or 403 | Get a new token (see [Get a token](#2-get-a-token)) |
| `environment is unreachable from this machine` | Network error or timeout | Check `ALBATO_BASE_URL`: no typos and no `/v1` at the end |
| `server did not start` | Missing dependencies, an old Node.js version, or contracts not found | Run `npm install`, check `node --version`, and make sure `contracts/` is in place or that the `ALBATO_*_CONTRACT` paths are correct |
| No `albato-builder` tools in the client | The client didn't start the server | Make sure the path in the config is absolute and points to `src/server.mjs`, then restart the client |
| "The app version is not editable" | The target version is public, shared or under moderation | Use the private version, or ask the model to call `ensure_editable_version` |

## Known limitations

- **Requests are tested one at a time.** The API can't run a whole trigger or bundle. Requests in
  `receivingRequests` run when a connection is saved, so a token-retrieval request can't be tested on
  its own with `test_request`.
- **Apps can't be deleted through the API.** The `apps` resource supports only list, get and create.
- **Status handler order.** Version-level status handlers can't be reordered through the API.
- **`responseData` from a test run** holds a single element, even when the request returns a list and
  `pathToArray` is set.
- **`expand: "rowSections"`** returns row sections without their fields. Use
  `expand: "rowSections.fields"`.
- **No OAuth in HTTP mode yet.** You pass the Bearer token in a header.

## License

[MIT](LICENSE)