# 🌉 Bridge

### Every message, for everyone.

**Bridge is an AI agent that makes Slack workspaces accessible for teammates who are blind, dyslexic, neurodivergent, or working in a second language — automatically, and privately.**

`Slack · Bolt for JavaScript`  ·  `Google Gemini`  ·  `Model Context Protocol`  ·  `Node.js 18+`  ·  `MIT License`

*Built for the [Slack Agent Builder Challenge](https://slackhack.devpost.com/) — **Agent for Good** track.*

---

## 💙 The problem

Slack is where work happens — but not equally for everyone. Over **1.3 billion people** live with a disability, and millions more work in a second language. Every day, in every workspace:

- A **blind** teammate hits a wall at every screenshot posted without a description.
- A **dyslexic** engineer rereads a jargon-dense announcement four times and still isn't sure what to do.
- A teammate working in their **third language** quietly drops out of a fast-moving thread.

They don't need a separate tool. They need the conversation *itself* to include them. **That's Bridge.**

---

## ✨ What it does

| Feature | Who it helps | How it works |
|---|---|---|
| 🖼️ **Automatic alt-text** | Blind & low-vision users | Every image posted in a channel gets a faithful description threaded under it — text transcribed, charts explained, error messages read out. No one has to remember to write it. |
| ✍️ **Simplify with Bridge** | Dyslexic, neurodivergent & non-native readers | A message shortcut rewrites any message in plain language, ending with a clear **"👉 What you need to do."** |
| 🌍 **Translate with Bridge** | Non-native speakers | Set your language once (`/bridge language Hindi`), then translate any message in one click — mentions, tone & formatting preserved. |
| 📚 **Plain-language catch-ups** | Anyone lost in long threads | Ask the Bridge assistant *"catch me up on #project-x"* and get an accessible digest with decisions, action items & citations. |

> 🔒 **Privacy by design:** simplifications and translations are delivered **ephemerally** — only the person who asked ever sees them. Nobody is publicly marked as needing an accommodation.

---

## 🧠 What makes it an *agent*, not a chatbot

Bridge's assistant runs an **autonomous tool-use loop**. You ask one question; Gemini decides which tools to call, in what order, and chains them — no hard-coded paths.

```
You:  "Find where we decided the launch date and explain it simply in Hindi."

Bridge (thinking, live status shown in Slack):
  → 🔍 search_messages          (Real-Time Search API)
  → 📖 read_channel_history
  → ✍️ simplify_text             (via MCP)
  → 🌍 translate_text            (via MCP)
  → ✅ replies in plain Hindi, with a citation to the original message
```

---

## 🏗️ Architecture

![Bridge architecture](architecture.png)

Bridge deliberately uses **all three** of the challenge's qualifying technologies:

1. **⚡ Slack AI capabilities** — a first-class AI assistant: assistant threads, suggested prompts, and live "thinking" status updates.
2. **🔌 MCP server integration** — Bridge's accessibility engine (`simplify_text`, `translate_text`, `describe_image`) runs as a **standalone MCP server**. The Slack agent discovers and calls it as an **MCP client** at runtime — and because it's standard MCP over stdio, *the same server plugs into Claude Desktop, IDEs, or any other MCP client unchanged.* Accessibility tools that work **beyond Slack**.
3. **🔍 Real-Time Search API** — `assistant.search.context` grounds every answer in real workspace messages, so the agent cites sources instead of hallucinating.

All natural-language work — reasoning, vision (alt-text), simplification, translation — is powered by **Google Gemini**.

---

## 🚀 Quick start

**Prerequisites:** Node.js 18+, a Slack workspace where you can install apps, and a free [Google AI Studio API key](https://aistudio.google.com/apikey).

```bash
# 1. Clone & install
git clone https://github.com/<you>/bridge.git
cd bridge
npm install

# 2. Configure
cp .env.example .env      # then fill in the 4 values (see below)

# 3. Run
npm start
```

You should see:

```
🔌 MCP connected: bridge-accessibility server exposing [simplify_text, translate_text, describe_image]
⚡ Bridge is running (Socket Mode)
```

### Create the Slack app (2 minutes)

1. Go to **[api.slack.com/apps](https://api.slack.com/apps) → Create New App → From a manifest**.
2. Pick your workspace and paste the contents of [`manifest.json`](manifest.json). Create.
3. **Basic Information → App-Level Tokens** → generate a token with the `connections:write` scope → this is `SLACK_APP_TOKEN`.
4. **Install App** → copy the **Bot User OAuth Token** (`SLACK_BOT_TOKEN`) and the **Signing Secret** from Basic Information.

### Your `.env`

```ini
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
GEMINI_API_KEY=...        # from aistudio.google.com/apikey (free tier)
```

---

## 🎮 Try it

| Do this | See this |
|---|---|
| `/invite @Bridge` into a channel, then drop in a screenshot | Bridge threads an alt-text description under it |
| Hover any message → ⋯ → **Simplify with Bridge** | A private, plain-language version appears |
| `/bridge language Spanish`, then ⋯ → **Translate with Bridge** | The message, privately, in Spanish |
| Open **Bridge** in the sidebar → *"catch me up on #general"* | A cited, plain-language digest |

---

## 🧩 Use the accessibility engine *outside* Slack

Because the engine is a real MCP server, you can add it to **Claude Desktop** (or any MCP client) and get the same tools anywhere:

```jsonc
// claude_desktop_config.json
{
  "mcpServers": {
    "bridge-accessibility": {
      "command": "node",
      "args": ["<path-to-repo>/src/mcp-server.js"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}
```

---

## 📁 Project structure

```
src/
├── app.js          # Slack app — assistant, shortcuts, /bridge, auto alt-text
├── agent.js        # Autonomous tool-use loop (Gemini) + MCP client
├── mcp-server.js   # Bridge Accessibility MCP server (simplify/translate/describe)
├── gemini.js       # Gemini calls, accessibility-tuned prompts
└── prefs.js        # Per-user language preferences
manifest.json       # Paste-ready Slack app configuration
architecture.png    # Architecture diagram
```

---

## 🛠️ Built with

**Node.js** · **Bolt for JavaScript** (Socket Mode) · **Slack AI** assistant threads · **Model Context Protocol** (server + client) · **Real-Time Search API** · **Google Gemini**

---

## 🌱 Roadmap

- 🎙️ Voice-note transcription & summarization
- 📖 Per-user reading-level personalization
- 🤟 Sign-language avatar clips for key announcements
- 🏪 One-click install via the Slack Marketplace

---

## 📜 License

MIT — free to use, adapt, and build on. Accessibility should be.

---

**Accessibility isn't a feature you add later. With Bridge, it's built into the conversation itself.**

*🌉 Bridge — every message, for everyone.*