workfront-fusion-mcp

# Workfront & Workfront Fusion MCP

One repository, **14 independently deployable Lambda functions** -- one per
Workfront/Fusion domain -- each exposing only its own scoped set of MCP
tools at its own HTTP route. **282 tools total**, covering every endpoint
listed in `WORKFRONT_MCP_SOLUTIONS.md` (full CRUD per object where the
underlying API supports it, not just the common list/get/create path).
See `WORKFRONT_MCP_SOLUTIONS.md` for the full
architecture writeup (endpoint tables, call-order dependencies per server,
auth details, and the single-repo-vs-separate-repos tradeoff this repo
settled on).

This mirrors the pattern already proven in `chaunceyplum/mcp` (the AEC
Adobe Experience Cloud MCP server): a stateless JSON-RPC 2.0 Lambda
handler per server, a single flat `TOOLS` dict per function, and
credentials resolved from SSM at deploy time via `{{resolve:ssm:...}}`.
The difference here: instead of one Lambda with all tools, **each server
is its own function with its own route**, so an MCP client only ever sees
the tools relevant to whichever endpoint(s) it's wired to.

## Why one repo instead of separate repos per server

We evaluated splitting each server into its own GitHub repo (see the
"one repo per server" alternative in `WORKFRONT_MCP_SOLUTIONS.md`) and
settled on a single repo with N independently deployable functions
instead, because:

- **The actual goal -- "the LLM only sees relevant tools" -- is a runtime
  endpoint property, not a source-control property.** A client hitting
  `/mcp/workfront/core` never sees another server's
  tools regardless of which repo the code lives in.
- **Isolation that matters (auth, blast radius) comes from per-function
  config, not per-repo config**, and SAM gives us that directly: every
  function below has its **own** `Environment` block resolving its
  **own** SSM namespace -- nothing is shared via `Globals`, so a bug in
  one server's code can't read another server's credentials.
- **One CI pipeline, one set of shared tooling (`common/`)** is simpler
  to maintain solo/small-team than 14 repos + a versioned shared package,
  and repos are cheap to split out later if team ownership ever actually
  diverges.

## Servers

| Folder | Route | Covers |
|---|---|---|
| Folder | Route | Tools | Covers |
|---|---|---|---|
| `servers/core/` | /mcp/workfront/core | 43 | Core Work Management: portfolios, programs, templates, template tasks, projects, tasks, and issues (incl. issue→task conversion). |

## Shared code (`common/`)

| Module | Purpose |
|---|---|
| `common/auth.py` | Generic Adobe IMS OAuth2 Server-to-Server (`client_credentials`) token fetch, cached per `(client_id, scope)`. |
| `common/workfront_client.py` | Classic Workfront REST API client (`/attask/api/v{version}`) + generic per-objcode CRUD helpers + `wf_set_custom_fields` (the `DE:` custom-form-value mechanism). |
| `common/crud_factory.py` | Builds a standard list/get/create/update/delete/set-custom-fields tool set for a single object code -- most server tool modules are a one-line call into this. |
| `common/comment_stream_client.py` | Comment Stream API v1 client (separate host + IMS scope from classic REST). |
| `common/fusion_client.py` | Workfront Fusion API client (separate host + IMS scope; Fusion is experimental per Adobe's own labeling). |
| `common/planning_client.py` | Planning API v2 client (workspaces / record-types / fields / views / records). |
| `common/dispatcher.py` | MCP JSON-RPC 2.0 Lambda handler factory (`initialize`, `tools/list`, `tools/call`) -- every server's `lambda_handler.py` is a few lines wiring its own `TOOLS` dict into this. |

## Deploy

```bash
sam build
sam deploy --guided   # first time -- saves samconfig.toml (gitignored; see samconfig.toml.example)
sam deploy             # subsequent deploys -- updates all 14 functions in one stack
```

`sam deploy` updates the whole stack in one pass; you're still deploying
14 independent functions with independent env/config, just via one
command. If you later want to deploy a single server's fix without
touching the others, target it directly:

```bash
sam deploy --resolve-s3   # or use `aws lambda update-function-code` for a hotfix to one function
```

### Populate SSM parameters

Each server reads only its own namespace. Populate the ones for the
servers you're actually standing up first (see the build order in
`WORKFRONT_MCP_SOLUTIONS.md` -- Users, then Core, tend to unblock the rest):

| SSM namespace | Env vars it feeds |
|---|---|
| `wf-mcp/core` | `WF_CLIENT_ID`, `WF_CLIENT_SECRET`, `WF_DOMAIN` |

Example for the core server:

```bash
aws ssm put-parameter --name /wf-mcp/core/client-id     --type SecureString --value "..."
aws ssm put-parameter --name /wf-mcp/core/client-secret --type SecureString --value "..."
aws ssm put-parameter --name /wf-mcp/core/domain        --type String       --value "yourtenant"
```

### Wire up an MCP client

Each server gets its own entry, pointing at its own route from the SAM
outputs:

```json
{
  "mcpServers": {
    "workfront-core": { "url": "https://<api-id>.execute-api.<region>.amazonaws.com/mcp/workfront/core" },
    "workfront-users": { "url": "https://<api-id>.execute-api.<region>.amazonaws.com/mcp/workfront/users" }
  }
}
```

Only wire up the servers relevant to a given client/session -- that's
what actually keeps the model's tool list scoped.

## Status

Every endpoint listed in `WORKFRONT_MCP_SOLUTIONS.md` has at least one
corresponding tool (282 total), and every server's `lambda_handler.py`
was re-verified end-to-end (import + a live `tools/list`/`tools/call`
dispatch against mocked HTTP) after each round of additions -- see the
commit history for the specific tool-by-tool audit.

That said, this is still a **scaffold** in one sense: the JSON-RPC
dispatcher, auth clients, and CRUD tool wiring are real and complete, but
several endpoint details are flagged inline (`# NOTE` / docstrings) as
pending verification against a live tenant -- there is no Workfront/Fusion
tenant credentialed against this repo yet. Before relying on any tool in
production, confirm against your own Adobe Developer Console app
registration:

- The exact OAuth scope string(s) for classic Workfront REST, Comment
  Stream, Fusion, and Planning (placeholders are marked in `common/*_client.py`).
- The issue→task conversion endpoint/verb (`servers/core/tools/issues.py`).
- The Planning API v2 base path (`common/planning_client.py`).
- The Fusion API base host (`FUSION_API_BASE`).
- The Document Webhooks API registration path/payload shape
  (`servers/documents/tools/document_webhooks.py` guesses `/documentwebhook`).
- The named-queries path (`servers/search/tools/named_queries.py` guesses
  `/namedqueries` and `/namedqueries/run`).
- Whether Fusion actually exposes `PATCH /scenarios/{id}` for metadata
  separately from `/scenarios/{id}/draft` for blueprint edits
  (`servers/fusion_scenarios/tools/scenarios.py`).