Metadata-Version: 2.4
Name: sabel-forge-mcp
Version: 0.1.68
Summary: MCP server suite for Intercom workspace and Fin AI configuration, audit, and migration.
Author: Forge
License: Proprietary
License-File: LICENSE.md
Keywords: automation,claude,fin,intercom,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.17
Requires-Dist: mcp>=1.0
Requires-Dist: playwright>=1.45
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# forge (sabel-forge-mcp)

A CLI and MCP server suite for Intercom workspace management and automation:
migrations, workspace configuration, routing, Fin AI content, and workflow
authoring. Ships two MCP servers — `forge-workspace` (workspace config:
articles, teams, tickets, macros, attributes, …) and `forge-fin` (Fin AI
agent, Voice, knowledge sources, workflows) — plus the `forge` CLI for
machine setup.

## Requirements

- **Python 3.11+**
- **Google Chrome** — UI-automation tools drive your own Chrome over the
  DevTools Protocol. No bundled browser is downloaded, ever.
- An **Intercom access token** per workspace you manage
  (Developer Hub → your app → Authentication).
- A **forge license key**.

## Install

```sh
uv tool install sabel-forge-mcp        # recommended
# or: pipx install sabel-forge-mcp
# or: pip install sabel-forge-mcp
```

Everything is included — REST tools *and* UI-automation tools work out of
the box. There are no extras to opt into and no `playwright install`
browser download (Playwright ships as a plain dependency and is only used
as the connection library to your own Chrome).

Verify:

```sh
forge --version        # → forge (sabel-forge-mcp) x.y.z
```

Then activate your license:

```sh
forge auth login
```

> **Upgrading from ≤ 0.1.63?** `forge install ui-deps` and the
> `[ui-automation]` extra are gone — a plain install/upgrade now carries
> everything: `uv tool upgrade sabel-forge-mcp`.

## Configure a workspace

Each Intercom workspace is a folder under `~/.forge/workspaces/` holding a
`forge.json`. The file names the **environment variable** that holds the
workspace's token — never the token itself (inline tokens are rejected):

```jsonc
// ~/.forge/workspaces/Client_Acme/forge.json
{
  "name": "Client_Acme",
  "industry": "fintech",          // optional; matches a playbook name
  "region": "eu",                 // us | eu | au — the Intercom datacenter
  "intercom_token_env": "CLIENT_ACME_TOKEN"
}
```

Put the token in `~/.secrets` (chmod 600, sourced from your shell rc):

```sh
export CLIENT_ACME_TOKEN="tok:..."
```

`region` matters: REST **reads** work from anywhere, but REST **writes**
and all admin-UI automation are datacenter-specific. If omitted, forge
auto-detects it on first use and writes it back into `forge.json`.

You can also let your agent do all of this — the `add_workspace` MCP tool
walks through the same steps and validates the token and region.

## Wire up the MCP servers

For Claude Code:

```sh
claude mcp add forge-workspace -- forge-workspace
claude mcp add forge-fin -- forge-fin
```

Launch your agent once at any directory; every tool takes a `workspace`
argument, so one server process serves all configured workspaces. After
adding a new token to `~/.secrets`, restart the agent so the servers
inherit the new environment.

## UI automation and the Chrome host

Tools ending in `_via_ui` drive the Intercom admin UI (for resources with
no write REST API). They run **exclusively as tabs in one long-lived
Google Chrome** bound to a local DevTools port:

- The first `*_via_ui` run **auto-starts the host** — a Chrome window
  opens, you log into Intercom once, and the login persists on disk.
- Manage it explicitly if you prefer:

  ```sh
  forge ui serve --workspace <name>   # start manually; log in once
  forge ui status                     # endpoint, workspace, region
  forge ui stop                       # shut it down
  ```

- The browser survives tool failures — a failed run leaves the page open
  for inspection, and re-running a tool resumes idempotently.
- One browser can hold logins for several Intercom datacenters; a tool
  targeting a different region opens a fresh login tab and tells you.

## Upgrading

```sh
uv tool upgrade sabel-forge-mcp      # or: pipx upgrade sabel-forge-mcp
```

The MCP servers check PyPI in the background and mention when a newer
release is available.
