# 🌉 Bridge MCP Server

**"You don't need another automation tool. You just need a bridge."**

Connect Claude, Gemini, or any AI to your business tools via the Model Context Protocol (MCP).

---

## What is this?

Bridge is a hosted MCP server that gives AI direct access to your tools:

- **ClickUp** - Tasks, projects, time tracking, templates
- **Skills Library** - Pre-built instructions for common workflows
- **(Coming soon)** HubSpot, Guru, Google Analytics, and more

No workflows to build. No operations to count. Just ask your AI what you need.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Your AI (Claude/Gemini)                                       │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                           │
│   │  Bridge MCP     │ ◄── Hosted on Google Cloud Run            │
│   │  Server         │                                           │
│   └────────┬────────┘                                           │
│            │                                                    │
│     ┌──────┴──────┐                                             │
│     ▼             ▼                                             │
│  ClickUp      Skills                                            │
│   API         Library                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## For Claude Code: Deployment Instructions

Hey Claude Code! Here's how to deploy this server to Google Cloud Run.

### Prerequisites

1. Google Cloud CLI (`gcloud`) installed and authenticated
2. A Google Cloud project with billing enabled
3. Cloud Run and Cloud Build APIs enabled

### Step-by-Step Deployment

```bash
# 1. Navigate to this directory
cd /path/to/bridge-mcp

# 2. Make sure gcloud is authenticated
gcloud auth login

# 3. Set your project
gcloud config set project YOUR_PROJECT_ID

# 4. Enable required APIs
gcloud services enable cloudbuild.googleapis.com run.googleapis.com

# 5. Make deploy script executable and run it
chmod +x deploy.sh
./deploy.sh
```

### Or Deploy Manually

```bash
# Build the container
gcloud builds submit --tag gcr.io/bridge-mcp/bridge-mcp

# Deploy to Cloud Run
gcloud run deploy bridge-mcp \
  --image gcr.io/bridge-mcp/bridge-mcp \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi \
  --set-env-vars "SUPABASE_URL=...,SUPABASE_KEY=..."
```

### After Deployment

You'll get a URL like: `https://bridge-mcp-xxxxx-uc.a.run.app`

- Health check: `https://YOUR_URL/health`
- MCP endpoint: `https://YOUR_URL/mcp`

---

## Connecting to Claude

Once deployed, add this MCP server to Claude:

1. Go to Claude settings → Integrations → MCP Servers
2. Add new server with URL: `https://YOUR_URL/mcp`
3. Name it "Bridge"

Now you can ask Claude things like:
- "Get my ClickUp task templates" (requires your ClickUp API key)
- "Create a task from my Project Kickoff template"
- "Load the transcript-to-tasks skill"

---

## Project Structure

```
bridge-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   └── connectors/
│       ├── clickup.ts        # ClickUp API tools
│       └── skills.ts         # Skills library tools
├── package.json
├── tsconfig.json
├── Dockerfile
├── deploy.sh
└── README.md
```

---

## Adding New Connectors

To add a new connector (e.g., HubSpot):

1. Create `src/connectors/hubspot.ts`
2. Export a `registerHubSpotTools(server: McpServer)` function
3. Import and call it in `src/index.ts`
4. Rebuild and redeploy

---

## Local Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm start

# Server runs at http://localhost:8080
```

---

## Skills Library

Bridge can fetch skills (instruction files) from GitHub repos.

Default repo: `amara-ai/bridge-skills` (update in `src/connectors/skills.ts`)

Skills are markdown files that teach AI how to perform tasks:
- `transcript-to-tasks` - Turn meeting transcripts into ClickUp tasks
- `client-onboarding` - Standard client onboarding workflow
- `daily-standup-summary` - Summarize team progress

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `8080` |

Note: API keys (ClickUp, HubSpot, etc.) are passed per-request by users, not stored on the server.

---

## License

MIT - Built by AI Foundations by Amara

*"I prompt like shit. But I get glorious results."*