Metadata-Version: 2.4
Name: algorise-bridge
Version: 0.1.1
Summary: CLI and MCP server for publishing agent output into your Algorise workspace
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# Algorise Bridge

**Publish agent output into Algorise** — from Claude Code, Cursor, CI, or any script.

Algorise Bridge is a CLI and MCP server that connects external coding agents to your
Algorise workspace. Push files, notes, and links; choose where they land; collaborate
with your team and digital employees; pull results back into your local workflow.

- **Publish** — files, URLs, or inline markdown land as reviewable artifacts
- **Route** — send work to your inbox, a Collection, Dataset, or Report
- **Collaborate** — post updates, request review, poll for replies from digital employees

Requires Python 3.12+ and an Algorise account.

## Quick start

```bash
# Install (see INSTALL.md for all options)
curl -fsSL https://cli.algorise.ai/install | bash

# Authorize via browser (OAuth — no API keys to paste)
algorise login

# Publish a file into your workspace inbox
algorise publish ./draft.md --title "Draft report" --agent claude-code

# See what you have published
algorise inbox
```

Published work appears in your Algorise dashboard, inbox, and notifications.

## Install

This package installs two commands:

| Command | Purpose |
|---|---|
| `algorise` | CLI for publishing and collaboration |
| `algorise-bridge-mcp` | MCP server (stdio) for in-editor agents |

```bash
# Recommended — one-line installer (uses uv, no system Python required)
curl -fsSL https://cli.algorise.ai/install | bash

# uv tool (persistent install)
uv tool install algorise-bridge

# Run without installing
uvx algorise-bridge algorise login

# pip / pipx (needs Python 3.12+)
pipx install algorise-bridge
```

Full install notes: [INSTALL.md](./INSTALL.md).

## Authenticate

Auth uses **browser OAuth** (OAuth 2.0 device-authorization grant). Tokens are
short-lived, refreshable, centrally revocable, and act as you within your current
organization.

```bash
algorise login
```

This prints a verification URL and user code, opens your browser, and waits for
approval (you must already be signed in to Algorise). The session is saved to
`~/.algorise/config` (mode 600).

```bash
algorise whoami   # profile, URL, org/user/scopes
algorise logout   # clear the active profile's session
```

Active sessions can be listed and revoked in the product under
**Settings → Connected CLIs**.

## Typical workflow

```bash
# 1. Publish work from your repo or agent session
algorise publish ./analysis.md --title "Competitor scan" --agent cursor

# 2. Route directly into a knowledge base (optional)
algorise publish ./policy.pdf --to collection --collection <collection-id>

# 3. Request a human review from the CLI
algorise review <artifact-id> "Please verify the sources"

# 4. After a digital-employee handoff in the UI, poll for replies
algorise pull <agent-session-id>
```

Review, approve, and hand off to digital employees in the Algorise UI. Bridge
delivers work into the workspace; it does not auto-publish on your behalf outside
Algorise.

## Profiles

One installed CLI can target multiple backends (e.g. staging and production) with
per-profile saved tokens — similar to `aws --profile`.

```bash
algorise login --profile staging  --api-url https://staging.example.com
algorise login --profile prod     --api-url https://app.example.com

algorise profiles                 # list profiles (* = active)
algorise use prod                 # switch active profile
algorise --profile staging whoami # one-off override

algorise logout --profile staging # clear one profile
algorise logout --all             # clear everything
```

Profiles are stored in `~/.algorise/config`. A legacy flat config is migrated
automatically into a `default` profile on first use.

### Resolution order

For each invocation, API URL and token resolve in this order (highest first):

1. `--api-url URL` (one-off; token from the selected profile or env)
2. `--profile NAME`
3. `ALGORISE_BRIDGE_PROFILE` env
4. `ALGORISE_BRIDGE_API_URL` / `ALGORISE_API_URL` (+ token env) — ad-hoc, no profile (CI)
5. Active profile in `~/.algorise/config`
6. Local dev fallback (`http://localhost:7100`)

## Environment variables

Most users only run `algorise login`. These exist for CI and headless runners:

| Variable | Purpose |
|---|---|
| `ALGORISE_BRIDGE_API_URL` | API base URL (falls back through `ALGORISE_API_URL`, saved config, release default, then localhost) |
| `ALGORISE_BRIDGE_DEFAULT_URL` | Release-time public API base, baked into published builds |
| `ALGORISE_BRIDGE_TOKEN` | Session token override (falls back to `ALGORISE_TOKEN`, then saved config) |
| `ALGORISE_BRIDGE_PROFILE` | Named profile (same as `--profile`; used by the MCP server, which has no CLI flags) |

When no URL is configured, commands that need the API fail with a clear message
instead of silently hitting localhost.

## CLI reference

| Command | Description |
|---|---|
| `algorise [--profile NAME] [--api-url URL] <command>` | Global backend selectors |
| `algorise login [--profile] [--api-url] [--name] [--scopes] [--no-browser]` | Browser OAuth; saves token under profile |
| `algorise logout [--profile] [--all]` | Clear session(s) |
| `algorise whoami` | Show resolved profile, URL, org/user/scopes |
| `algorise profiles` (alias `envs`) | List configured profiles |
| `algorise use NAME` | Set the active profile |
| `algorise publish PATH [--title] [--summary] [--type] [--agent] [--to …] [--collection ID] [--dataset ID]` | Publish a file |
| `algorise publish --url URL [--title]` | Publish a URL as a link |
| `algorise publish --text "…" [--title]` | Publish inline markdown as a note |
| `algorise note TEXT [--title] [--summary] [--agent]` | Publish an inline note |
| `algorise artifacts [--target] [--limit]` | List published artifacts |
| `algorise inbox [--limit]` | List artifacts with compiled previews |
| `algorise update ARTIFACT_ID BODY [--review]` | Post a progress update |
| `algorise notify TITLE MESSAGE [--url]` | Send a standalone notification |
| `algorise review ARTIFACT_ID [BODY]` | Request review and show the thread |
| `algorise pull SESSION [--since ISO]` | Poll a collaboration session for replies |
| `algorise quota` | Show remaining ingest quota |

### Destinations (`--to`)

Type is inferred from the file extension; `--type` overrides. Default destination
is the reviewable inbox.

| Extension | Type | Valid `--to` targets |
|---|---|---|
| pdf, docx, pptx, md, mdx, txt | `document` | inbox, collection, report |
| html, htm, xml | `page` | inbox, report |
| png, jpg, jpeg, svg, mp4 | `media` | inbox, collection |
| csv, json | `data` | inbox, dataset |
| (`--url`) | `link` | inbox |
| (`--text`) | `note` | inbox, collection |

`--collection ID` / `--dataset ID` imply the matching `--to`. Collection and
dataset targets embed content and are metered — check `algorise quota` first.
Over-cap ingests return **HTTP 402**; saturated org queues return **HTTP 429**.

## MCP server

The bundled MCP server (`algorise-bridge-mcp`, stdio transport) exposes the same
capabilities to in-editor agents. It reuses the CLI session in `~/.algorise/config`.

Run `algorise login` once, then register the server.

**Claude Code / Cursor** (`.mcp.json`):

```json
{
  "mcpServers": {
    "algorise-bridge": {
      "command": "uvx",
      "args": ["--from", "algorise-bridge", "algorise-bridge-mcp"]
    }
  }
}
```

If installed in a virtualenv, use `"command": "algorise-bridge-mcp"` instead.

Override API URL or token per server via `env` (`ALGORISE_BRIDGE_API_URL`,
`ALGORISE_BRIDGE_TOKEN`). For multiple backends, register separate server entries
with `ALGORISE_BRIDGE_PROFILE` in each `env` block.

### MCP tools

| Tool | Description |
|---|---|
| `publish_note(text, title?, summary?, agent?)` | Publish an inline markdown/MDX note |
| `publish_artifact(..., to?, collection_id?, dataset_id?)` | Publish content to a destination |
| `post_update(artifact_id, body, review_requested?)` | Post a progress update or request review |
| `notify(title, message, action_url?)` | Send a standalone notification |
| `get_inbox(limit?)` | List recently published artifacts (with previews) |
| `get_quota()` | Remaining ingest quota headroom |
| `request_review(artifact_id, body)` | Request a human review |
| `get_artifact(artifact_id)` | Fetch one artifact and its review state |
| `list_artifact_replies(artifact_id, since?)` | Replay an artifact's collaboration thread |
| `pull_updates(agent_session_id, since?)` | Poll a session for new replies |

## License

MIT
