# Workato Dev MCP

A **local, zero-dependency MCP server** to author, lint, deploy, and debug **Workato recipes from
Claude** (Code, Desktop, or any MCP client). It wraps the Workato Developer REST API, the Recipe
Lifecycle Management (RLCM) package API, and the Data Tables record API.

**Why not the official one?** The hosted Workato Developer MCP (`app.workato.com/mcp`) is
management/read-only — it can't create or update recipe **code** or start/stop recipes. This can.
It also adds a pure-Python recipe **linter**, RLCM export/import, Data Table row CRUD, and AI Hub
MCP-server management.

- **Zero dependencies** — Python 3.8+ standard library only. No `pip install`, no build step.
- **Bring your own token** — each developer uses their own Workato API-client token. Nothing hosted or shared.
- **[56 tools](docs/TOOLS.md)** across recipes, linting, RLCM round-trip, connections, data/lookup
  tables, API Platform, and AI Hub MCP servers.

> Forked from [`krishnagutta/workato-dev-mcp`](https://github.com/krishnagutta/workato-dev-mcp);
> extends it with RLCM round-trip, Data Table CRUD, a scaffolder, AI Hub MCP management, and a
> pure-Python port of Workato Labs' [`recipe-lint`](https://github.com/workato-devs/recipe-lint)
> (MIT). Full attribution in [`LICENSE`](LICENSE).

## Setup (Claude Code)

First get a **Workato API-client token**: Workspace admin → **API clients** (which privileges to
grant — and how to wire Claude Desktop / other clients — are in **[docs/SETUP.md](docs/SETUP.md)**).
Then:

```bash
git clone https://github.com/gmunro-lyft/Workato-Claude-MCP.git
cd Workato-Claude-MCP
cp .env.example .env                 # 1. copy the env template
# 2. edit .env → set WORKATO_TOKEN=wrkaus-…
python3 mcp/server.py --selftest     # 3. confirm the server loads (no token needed)
claude                               # 4. launch Claude Code; approve "workato-dev" once
```

Then in a new session try: *"list my Workato recipes"* or *"lint recipe 12345678"*.

## The recipe edit loop

```
get_recipe(id, include_code=true)   # pull the code tree (source of truth for editing)
  → edit the JSON in conversation
  → lint_recipe(recipe_id=id)       # catch structural/datapill bugs BEFORE saving
  → stop_recipe(id)                 # running recipes can't be updated
  → update_recipe(id, code=<json>)
  → start_recipe(id)                # start = the real compiler; read its validation errors
  → list_jobs / get_job             # after a test run, inspect real per-step I/O
```

Run `workato_recipe_tips` and `get_learnings` once before building — they capture the datapill
format, the trigger `extended_output_schema` requirement, the HTTP string-body trick, custom-code
schema gotchas, valid condition operands, and the job-log debugging pattern.

## Linting

Two local, no-token tools statically analyse recipes before deploy: **`lint_recipe`** (one recipe,
by `path` or `recipe_id`) and **`validate_package`** (a whole package directory + package-level
checks). Both return structured `diagnostics` from a pure-Python port of `recipe-lint`'s Tier 0/1
rules. See **[docs/LINTING.md](docs/LINTING.md)** for the rule table and the full 66-rule engine.

## Region

Defaults to the **US** data center. For another region set `WORKATO_API_BASE` (and
`WORKATO_DATA_TABLES_BASE` for Data Table row tools) in `.env` — e.g. EU is
`https://app.eu.workato.com/api`. Full table in [docs/SETUP.md](docs/SETUP.md#data-center--region).

## Verify & test

All of these are offline, need no token, and require no install (stdlib only):

```bash
python3 mcp/server.py --selftest          # the tool registry loads and is internally consistent
python3 mcp/server.py --list-tools        # print every tool + a one-line description
python3 mcp/server.py --version           # print the server version
python3 -m unittest discover -s tests     # run the unit tests
python3 tools/gen_tools_doc.py --check    # docs/TOOLS.md is in sync with the tools
```

The tests also run under `pytest` if you prefer it.

## Documentation

- **[docs/SETUP.md](docs/SETUP.md)** — create the API client, privileges, token wiring (Code / Desktop / other), regions
- **[docs/TOOLS.md](docs/TOOLS.md)** — the full 56-tool reference (generated from the server)
- **[docs/LINTING.md](docs/LINTING.md)** — lint rules + the upstream Go engine
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — add a tool, run the checks, and the allowlist-`.gitignore` rule

## Capturing learnings

The knowledge base grows as you use it. `mcp/learnings.md` is the append-only intake queue — when
Claude hits a gotcha not in `workato_recipe_tips`, it calls `log_learning`. **Scrub any
workspace-specific names/IDs before committing** (see [CONTRIBUTING](CONTRIBUTING.md#learnings)) —
the file is tracked and publishes verbatim. During review, raw learnings are promoted into
`workato_recipe_tips` (the curated tier). `log_learning` / `get_learnings` are pure local file
ops — no token.

## Notes / limits

- **This is a dev tool.** It can create, edit, start/stop, and **delete** recipes and Data Table
  rows. Point it at a dev/impl workspace and treat `delete_recipe` / `deploy_package` /
  `delete_data_table_row` with care (they confirm intent in their descriptions).
- **AI Hub MCP tools may be plan-gated.** The `*_mcp_*` tools need the API client's **MCP**
  privilege; without it Workato returns the HTML login page or 403/404. Run `check_mcp_privileges`
  first. (A different surface from the API-Platform `list_api_*` tools.)
- **It doesn't touch the AI Hub authoring layer** beyond server management. After a recipe
  param-set change, the consuming MCP client needs an app restart to see the new schema.
- **Sharing.** Commit this folder to an internal git repo; teammates clone, set `WORKATO_TOKEN` in
  `.env`, and approve the project-scoped `.mcp.json` on first launch.

## License

[MIT](LICENSE). Builds on [`krishnagutta/workato-dev-mcp`](https://github.com/krishnagutta/workato-dev-mcp)
and ports lint rules from [`recipe-lint`](https://github.com/workato-devs/recipe-lint) (MIT) — see
[`LICENSE`](LICENSE).