mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-10 22:32:16 +02:00
feat: docs and ui tweaks
This commit is contained in:
DESKTOP-RTLN3BA\$punk
parent
64f2b4a6eb
commit
271a21aee6
103 changed files with 2161 additions and 2625 deletions
69
surfsense_web/content/docs/connectors/external/airtable.mdx
vendored
Normal file
69
surfsense_web/content/docs/connectors/external/airtable.mdx
vendored
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: Airtable
|
||||
description: Let the SurfSense agent browse your Airtable bases, tables, and records
|
||||
---
|
||||
|
||||
The Airtable connector connects SurfSense to Airtable's hosted MCP server, giving the agent live tools to list your bases, browse tables, and read records. Nothing is indexed in the background.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Register an OAuth Integration
|
||||
|
||||
1. Navigate to [airtable.com/create/oauth](https://airtable.com/create/oauth)
|
||||
2. In the **Builder Hub**, under **Developers**, click **"OAuth integrations"**
|
||||
3. Click **"Register an OAuth integration"**
|
||||
|
||||
|
||||
|
||||
Fill in the details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **OAuth redirect URL** | `http://localhost:3929/api/v1/auth/mcp/airtable/connector/callback` |
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
Click **"Register integration"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Configure Scopes
|
||||
|
||||
Enable the scopes SurfSense requests:
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `data.records:read` | See the data in records |
|
||||
| `schema.bases:read` | See the structure of a base, like table names or field types |
|
||||
|
||||
|
||||
|
||||
## Step 3: Fill in Support Information
|
||||
|
||||
Add a support email (plus privacy policy and terms URLs if you have them) and click **"Save changes"**.
|
||||
|
||||
|
||||
|
||||
## Step 4: Add the Credentials to SurfSense
|
||||
|
||||
Copy the **Client ID** and **Client Secret** from the integration page and add them to your `.env` file:
|
||||
|
||||
```bash
|
||||
AIRTABLE_CLIENT_ID=your_airtable_client_id
|
||||
AIRTABLE_CLIENT_SECRET=your_airtable_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open the **Connectors** dialog, and click **Connect** on Airtable:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
76
surfsense_web/content/docs/connectors/external/bookstack.mdx
vendored
Normal file
76
surfsense_web/content/docs/connectors/external/bookstack.mdx
vendored
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
---
|
||||
title: Bookstack
|
||||
description: Connect your Bookstack instance to SurfSense
|
||||
---
|
||||
|
||||
# BookStack Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Indexing deprecated">
|
||||
The BookStack indexing pipeline is currently deprecated — the knowledge base now stores files, notes, and uploads only. Existing BookStack connectors remain manageable, but new indexing runs are refused by the backend.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your BookStack instance to SurfSense.
|
||||
|
||||
## How it works
|
||||
|
||||
The BookStack connector uses the BookStack REST API to fetch all pages from your BookStack instance that your account has access to.
|
||||
|
||||
- For follow up indexing runs, the connector retrieves pages that have been updated since the last indexing attempt.
|
||||
- Indexing should be configured to run periodically, so updates should appear in your search results within minutes.
|
||||
|
||||
---
|
||||
|
||||
## Authorization
|
||||
|
||||
<Callout type="info" title="API Token Required">
|
||||
You need to create an API token from your BookStack instance. The token requires "Access System API" permission.
|
||||
</Callout>
|
||||
|
||||
### Step 1: Create an API Token
|
||||
|
||||
1. Log in to your BookStack instance
|
||||
2. Click on your profile icon → Edit Profile
|
||||
3. Navigate to the "API Tokens" tab
|
||||
4. Click "Create Token" and give it a name
|
||||
5. Copy both the **Token ID** and **Token Secret**
|
||||
6. Paste them in the connector form
|
||||
|
||||
### Step 2: Grant necessary access
|
||||
|
||||
Your user account must have "Access System API" permission. The connector will only index content your account can view.
|
||||
|
||||
<Callout type="info" title="Rate Limiting">
|
||||
BookStack API has a rate limit of 180 requests per minute. The connector automatically handles rate limiting to ensure reliable indexing.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Periodic Sync">
|
||||
Enable periodic sync to automatically re-index pages when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Connecting to SurfSense
|
||||
|
||||
1. Navigate to the Connector Dashboard and select the **BookStack** Connector.
|
||||
2. Fill in the required fields:
|
||||
|
||||
| Field | Description | Example |
|
||||
|-------|-------------|---------|
|
||||
| **Connector Name** | A friendly name to identify this connector | `My BookStack Connector` |
|
||||
| **BookStack Base URL** | The full URL of your BookStack instance | `https://docs.example.com` |
|
||||
| **Token ID** | Your API Token ID from BookStack | |
|
||||
| **Token Secret** | Your API Token Secret from BookStack | |
|
||||
|
||||
3. Click **Connect** to establish the connection.
|
||||
4. Once connected, your BookStack pages will be indexed automatically.
|
||||
|
||||
### What Gets Indexed
|
||||
|
||||
The BookStack connector indexes the following data:
|
||||
|
||||
| Data Type | Description |
|
||||
|-----------|-------------|
|
||||
| Pages | All pages from your BookStack instance |
|
||||
| Content | Page content in Markdown format |
|
||||
| Metadata | Page titles and metadata |
|
||||
| Structure | Book and chapter hierarchy information |
|
||||
133
surfsense_web/content/docs/connectors/external/circleback.mdx
vendored
Normal file
133
surfsense_web/content/docs/connectors/external/circleback.mdx
vendored
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
---
|
||||
title: Circleback
|
||||
description: Connect your Circleback meetings to SurfSense
|
||||
---
|
||||
|
||||
# Circleback Integration Setup Guide
|
||||
|
||||
This guide walks you through connecting your Circleback meetings to SurfSense for meeting search and AI-powered insights.
|
||||
|
||||
## How it works
|
||||
|
||||
The Circleback connector uses a **webhook-based integration**. Unlike other connectors that pull data from APIs, Circleback automatically pushes meeting data to SurfSense when meetings are processed.
|
||||
|
||||
- Meetings are sent to SurfSense immediately after Circleback processes them
|
||||
- No API keys or credentials required
|
||||
- No periodic indexing needed - data arrives in real-time
|
||||
- Each meeting is stored with its notes, transcript, action items, and insights
|
||||
|
||||
---
|
||||
|
||||
## What Gets Indexed
|
||||
|
||||
| Content Type | Description |
|
||||
|--------------|-------------|
|
||||
| Meeting Notes | AI-generated meeting notes in Markdown format |
|
||||
| Transcript | Full meeting transcript with speaker identification and timestamps |
|
||||
| Action Items | Tasks with assignees and status |
|
||||
| Attendees | Names and emails of meeting participants |
|
||||
| Insights | Custom insights extracted from the meeting |
|
||||
| Metadata | Date, duration, tags, meeting URL, and Circleback link |
|
||||
|
||||
<Callout type="info">
|
||||
Meeting recordings are not stored in SurfSense, but a link to the recording (valid for 24 hours from Circleback) is included in the indexed document.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Setup Guide
|
||||
|
||||
### Step 1: Create the Connector in SurfSense
|
||||
|
||||
1. Navigate to **Connectors** → **Add Connector** → **Circleback**
|
||||
2. Enter a connector name (e.g., `My Circleback Meetings`)
|
||||
3. Click **Connect** to create the connector
|
||||
|
||||
<Callout type="info" title="No Credentials Needed">
|
||||
Circleback uses webhooks, so no API key or authentication is required. The webhook URL is unique to your workspace.
|
||||
</Callout>
|
||||
|
||||
### Step 2: Copy Your Webhook URL
|
||||
|
||||
After creating the connector:
|
||||
|
||||
1. Open the connector settings
|
||||
2. Find the **Webhook URL** field
|
||||
3. Click **Copy** to copy the URL to your clipboard
|
||||
|
||||
The webhook URL looks like:
|
||||
```
|
||||
https://your-surfsense-url/api/v1/webhooks/circleback/{workspace_id}
|
||||
```
|
||||
|
||||
### Step 3: Configure Circleback Automation
|
||||
|
||||
1. Log into your [Circleback account](https://app.circleback.ai)
|
||||
2. Go to **Automations** (in the main navigation)
|
||||
3. Click **Create automation**
|
||||
4. Add conditions to filter which meetings trigger the webhook (optional):
|
||||
- Specific calendar(s)
|
||||
- Meeting tags
|
||||
- Meeting participants
|
||||
5. Select **Send webhook request** as the action
|
||||
6. Enter your SurfSense webhook URL
|
||||
7. Select the meeting outcomes to include (notes, action items, transcript, insights)
|
||||
8. Optionally test with your most recent meeting
|
||||
9. Name and save the automation
|
||||
|
||||
For detailed instructions, see [Circleback's official webhook documentation](https://circleback.ai/docs/webhook-integration).
|
||||
|
||||
<Callout type="warn">
|
||||
Make sure your SurfSense backend is accessible from the internet for Circleback to send webhooks. If self-hosting, you may need to configure a reverse proxy or use a tunneling service.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Connector Configuration
|
||||
|
||||
| Field | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Connector Name** | A friendly name to identify this connector | Yes |
|
||||
|
||||
<Callout type="info">
|
||||
Unlike other connectors, Circleback doesn't support periodic indexing since it's webhook-based. Meetings are automatically pushed to SurfSense when processed by Circleback.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Verifying the Integration
|
||||
|
||||
Once configured, new meetings will automatically appear in SurfSense after Circleback processes them. To verify:
|
||||
|
||||
1. Attend or process a meeting with Circleback
|
||||
2. Wait for Circleback to complete processing (usually a few minutes after the meeting ends)
|
||||
3. Check your SurfSense workspace for the new meeting document
|
||||
|
||||
Each meeting document includes:
|
||||
- A direct link to view the meeting on Circleback
|
||||
- Full searchable transcript
|
||||
- Extracted action items with assignees
|
||||
- Meeting metadata and insights
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Meetings not appearing**
|
||||
- Verify the webhook URL is correctly configured in Circleback
|
||||
- Check that your SurfSense backend is accessible from the internet
|
||||
- Look for errors in your SurfSense backend logs
|
||||
|
||||
**Webhook URL not showing**
|
||||
- Refresh the connector configuration page
|
||||
- Ensure the connector was created successfully
|
||||
- Check that your backend is running
|
||||
|
||||
**Duplicate meetings**
|
||||
- Each meeting is uniquely identified by its Circleback meeting ID
|
||||
- If content changes, the existing document is updated rather than duplicated
|
||||
|
||||
**Delayed indexing**
|
||||
- Meeting data is processed asynchronously
|
||||
- Documents should appear within a minute of receiving the webhook
|
||||
- Check the task queue if experiencing longer delays
|
||||
71
surfsense_web/content/docs/connectors/external/dropbox.mdx
vendored
Normal file
71
surfsense_web/content/docs/connectors/external/dropbox.mdx
vendored
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
title: Dropbox
|
||||
description: Import your Dropbox files into the SurfSense knowledge base
|
||||
---
|
||||
|
||||
The Dropbox connector lets you pick files from Dropbox and index them into your knowledge base. It lives in the Documents sidebar's **Import** menu, not the connector catalog.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just use **Import → Dropbox**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a Dropbox App
|
||||
|
||||
1. Navigate to [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps) and sign in
|
||||
2. Click **"Create app"** and fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Choose an API** | **"Scoped access"** |
|
||||
| **Choose the type of access** | **"Full Dropbox"** |
|
||||
| **Name your app** | `SurfSense` (or any unique name) |
|
||||
|
||||
3. Click **"Create app"**
|
||||
|
||||
## Step 2: Configure the Redirect URI
|
||||
|
||||
1. On your app's **Settings** page, scroll to the **OAuth 2** section
|
||||
2. Under **Redirect URIs**, add:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/dropbox/connector/callback
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
## Step 3: Configure Permissions
|
||||
|
||||
1. Go to the **Permissions** tab of your app
|
||||
2. Enable all of the following scopes and click **"Submit"**:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `files.metadata.read` | View information about files and folders |
|
||||
| `files.content.read` | View and download file content |
|
||||
| `files.content.write` | Create, modify, and delete files |
|
||||
| `account_info.read` | View basic account information |
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Add the Credentials to SurfSense
|
||||
|
||||
On the **Settings** page, copy the **App key** and **App secret** (click "Show" to reveal), and add them to your `.env` file:
|
||||
|
||||
```bash
|
||||
DROPBOX_APP_KEY=your_dropbox_app_key
|
||||
DROPBOX_APP_SECRET=your_dropbox_app_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open **Documents → Import → Dropbox**, and authorize:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
89
surfsense_web/content/docs/connectors/external/github.mdx
vendored
Normal file
89
surfsense_web/content/docs/connectors/external/github.mdx
vendored
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
title: GitHub
|
||||
description: Connect your GitHub repositories to SurfSense
|
||||
---
|
||||
|
||||
# GitHub Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Indexing deprecated">
|
||||
The GitHub indexing pipeline is currently deprecated — the knowledge base now stores files, notes, and uploads only. Existing GitHub connectors remain manageable, but new indexing runs are refused by the backend.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your GitHub repositories to SurfSense for code search and AI-powered insights.
|
||||
|
||||
## How it works
|
||||
|
||||
The GitHub connector uses [gitingest](https://gitingest.com) to fetch and process repository contents from GitHub.
|
||||
|
||||
- For follow-up indexing runs, the connector retrieves the latest repository state and updates changed files.
|
||||
- Indexing should be configured to run periodically, so updates should appear in your search results within minutes.
|
||||
|
||||
---
|
||||
|
||||
## What Gets Indexed
|
||||
|
||||
| Content Type | Examples |
|
||||
|--------------|----------|
|
||||
| Code Files | Python, JavaScript, TypeScript, Go, Rust, Java, etc. |
|
||||
| Documentation | README files, Markdown documents, text files |
|
||||
| Configuration | JSON, YAML, TOML, .env examples, Dockerfiles |
|
||||
|
||||
<Callout type="warn">
|
||||
Binary files and files larger than 5MB are automatically excluded.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Public Repos)
|
||||
|
||||
1. Navigate to **Connectors** → **Add Connector** → **GitHub**
|
||||
2. Enter repository names: `owner/repo` (e.g., `facebook/react, vercel/next.js`)
|
||||
3. Click **Connect GitHub**
|
||||
|
||||
No authentication required for public repositories.
|
||||
|
||||
---
|
||||
|
||||
## Private Repositories
|
||||
|
||||
For private repos, you need a GitHub Personal Access Token (PAT).
|
||||
|
||||
### Generate a PAT
|
||||
|
||||
1. Go to [GitHub's token creation page](https://github.com/settings/tokens/new?description=surfsense&scopes=repo) (pre-filled with `repo` scope)
|
||||
2. Set an expiration
|
||||
3. Click **Generate token** and copy it
|
||||
|
||||
<Callout type="warn">
|
||||
The token starts with `ghp_`. Store it securely.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Periodic Sync">
|
||||
Enable periodic sync to automatically re-index repositories when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Connector Configuration
|
||||
|
||||
| Field | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Connector Name** | A friendly name to identify this connector | Yes |
|
||||
| **GitHub Personal Access Token** | Your PAT (only for private repos) | No |
|
||||
| **Repository Names** | Comma-separated list: `owner/repo1, owner/repo2` | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Repository not found**
|
||||
- Verify format is `owner/repo`
|
||||
- For private repos, ensure PAT has access
|
||||
|
||||
**Authentication failed**
|
||||
- Check PAT is valid and not expired
|
||||
- Token should start with `ghp_` or `github_pat_`
|
||||
|
||||
**Rate limit exceeded**
|
||||
- Use a PAT for higher limits (5,000/hour vs 60 unauthenticated)
|
||||
- Reduce sync frequency
|
||||
97
surfsense_web/content/docs/connectors/external/google.mdx
vendored
Normal file
97
surfsense_web/content/docs/connectors/external/google.mdx
vendored
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
title: Google (Drive, Gmail, Calendar)
|
||||
description: Set up one Google OAuth app for the Drive, Gmail, and Calendar connectors
|
||||
---
|
||||
|
||||
One Google Cloud OAuth app powers Google login and all three Google connectors:
|
||||
|
||||
- **Google Drive** — import Drive files into your knowledge base via the Documents sidebar's **Import** menu
|
||||
- **Gmail** — the agent can search, read, draft, and send emails
|
||||
- **Google Calendar** — the agent can search and manage your events
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info">
|
||||
The redirect URIs below use `http://localhost:3929` — the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a Google Cloud Project
|
||||
|
||||
1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select an existing project or create a new one
|
||||
|
||||
## Step 2: Enable the APIs
|
||||
|
||||
1. Go to **APIs & Services** > **Library**
|
||||
2. Search for and enable:
|
||||
- **People API** (required for Google OAuth itself)
|
||||
- **Google Drive API** (for the Drive connector)
|
||||
- **Gmail API** (for the Gmail connector)
|
||||
- **Google Calendar API** (for the Calendar connector)
|
||||
|
||||
You only need to enable the APIs for the connectors you plan to use — the People API is always required.
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure the OAuth Consent Screen
|
||||
|
||||
1. Go to **APIs & Services** > **OAuth consent screen**
|
||||
2. Select **External** user type (or Internal if using Google Workspace)
|
||||
3. Fill in the required information:
|
||||
- **App name**: `SurfSense`
|
||||
- **User support email**: Your email address
|
||||
- **Developer contact information**: Your email address
|
||||
4. Click **Save and Continue**
|
||||
|
||||
|
||||
|
||||
### Add Scopes
|
||||
|
||||
Click **Add or Remove Scopes** and add:
|
||||
|
||||
| Scope | Used by |
|
||||
|-------|---------|
|
||||
| `openid`, `.../auth/userinfo.email`, `.../auth/userinfo.profile` | All (basic OAuth) |
|
||||
| `https://www.googleapis.com/auth/drive` | Drive connector |
|
||||
| `https://www.googleapis.com/auth/gmail.modify` | Gmail connector |
|
||||
| `https://www.googleapis.com/auth/calendar.events` | Calendar connector |
|
||||
|
||||
<Callout type="info">
|
||||
The write-capable scopes (`drive`, `gmail.modify`, `calendar.events`) are what let the agent create files, send emails, and manage events — always with your confirmation in chat. If you only want read access, use `drive.readonly`, `gmail.readonly`, and `calendar.readonly` instead; the write tools then won't work.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Create the OAuth Client
|
||||
|
||||
1. Go to **APIs & Services** > **Credentials**
|
||||
2. Click **Create Credentials** > **OAuth client ID**
|
||||
3. Select **Web application** as the application type
|
||||
4. Enter **Name**: `SurfSense`
|
||||
5. Under **Authorized redirect URIs**, add one URI per connector you plan to use:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/google/drive/connector/callback
|
||||
http://localhost:3929/api/v1/auth/google/gmail/connector/callback
|
||||
http://localhost:3929/api/v1/auth/google/calendar/connector/callback
|
||||
```
|
||||
|
||||
6. Click **Create**
|
||||
|
||||
|
||||
|
||||
## Step 5: Add the Credentials to SurfSense
|
||||
|
||||
Copy the **Client ID** and **Client Secret** from the confirmation dialog, then add them to your `.env` file (see the Google section of `.env.example` for the exact variable names — the same client ID and secret are shared by Google login and all three connectors, plus one redirect URI variable per connector).
|
||||
|
||||
|
||||
|
||||
Restart SurfSense and the Google connectors are ready to connect:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
101
surfsense_web/content/docs/connectors/external/index.mdx
vendored
Normal file
101
surfsense_web/content/docs/connectors/external/index.mdx
vendored
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: External Connectors
|
||||
description: Connect third-party services like Notion, Slack, Google, GitHub, and Obsidian
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
|
||||
External connectors link SurfSense to third-party services. Open the **Connectors** dialog in your workspace, pick a service, and connect — via OAuth, an API token, a webhook, or a companion plugin, depending on the service. You can connect multiple accounts of the same service.
|
||||
|
||||
Most of them act as **live tools for the AI agent** — when you chat, the agent can search your Notion pages, read Slack threads, or create Jira issues in real time. File sources (Google Drive, OneDrive, Dropbox) instead show up in the Documents sidebar's **Import** menu, where you pick files to index into your knowledge base.
|
||||
|
||||
## One-click connectors (no setup)
|
||||
|
||||
These work out of the box on every deployment — SurfSense connects to the service's hosted MCP server and the service issues credentials automatically. Just click **Connect**:
|
||||
|
||||
| Connector | What the agent can do |
|
||||
|-----------|----------------------|
|
||||
| **Notion** | Search, read, create, and update pages |
|
||||
| **Linear** | Search, read, and manage issues and projects |
|
||||
| **Jira** | Search issues with JQL, browse projects, create and edit issues |
|
||||
| **Confluence** | Search and read spaces, create and update pages |
|
||||
| **ClickUp** | Search and read tasks |
|
||||
|
||||
Write actions (creating a page, editing an issue) always ask for your confirmation in chat before they run.
|
||||
|
||||
## Connectors that need OAuth credentials (self-hosted)
|
||||
|
||||
For these, a self-hosted deployment needs its own OAuth app registered with the provider. Create the app once, put the credentials in your `.env` (each variable is documented in `.env.example`), restart, and the **Connect** button works for everyone on your instance:
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="Google (Drive, Gmail, Calendar)"
|
||||
description="One Google Cloud OAuth app powers all three connectors"
|
||||
href="/docs/connectors/external/google"
|
||||
/>
|
||||
<Card
|
||||
title="Slack"
|
||||
description="Search and read channels and threads"
|
||||
href="/docs/connectors/external/slack"
|
||||
/>
|
||||
<Card
|
||||
title="Airtable"
|
||||
description="Browse bases, tables, and records"
|
||||
href="/docs/connectors/external/airtable"
|
||||
/>
|
||||
<Card
|
||||
title="Microsoft OneDrive"
|
||||
description="Import your OneDrive files into the knowledge base"
|
||||
href="/docs/connectors/external/onedrive"
|
||||
/>
|
||||
<Card
|
||||
title="Dropbox"
|
||||
description="Import your Dropbox files into the knowledge base"
|
||||
href="/docs/connectors/external/dropbox"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
<Callout type="info">
|
||||
On SurfSense Cloud these are already configured — just click **Connect**. The setup guides above only apply to self-hosted deployments.
|
||||
</Callout>
|
||||
|
||||
## Token, webhook, and plugin connectors
|
||||
|
||||
These you configure yourself with an API token, a webhook, or a companion plugin:
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="GitHub"
|
||||
description="Index repositories into your knowledge base"
|
||||
href="/docs/connectors/external/github"
|
||||
/>
|
||||
<Card
|
||||
title="BookStack"
|
||||
description="Index your BookStack documentation"
|
||||
href="/docs/connectors/external/bookstack"
|
||||
/>
|
||||
<Card
|
||||
title="Circleback"
|
||||
description="Receive meeting notes and transcripts via webhook"
|
||||
href="/docs/connectors/external/circleback"
|
||||
/>
|
||||
<Card
|
||||
title="Obsidian"
|
||||
description="Sync your vault with the SurfSense Obsidian plugin"
|
||||
href="/docs/connectors/external/obsidian"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
There's also a generic **Custom MCP** connector in the catalog that lets you plug any MCP server into the agent — including API-key-based services like Tavily or Linkup.
|
||||
|
||||
## Importing files from Drive, OneDrive, and Dropbox
|
||||
|
||||
Google Drive, OneDrive, and Dropbox are file sources, so they don't appear in the connector catalog. Instead, open the **Documents** sidebar, click **Import**, and pick the service. After authorizing, browse and select the files you want — they're indexed into your knowledge base and kept searchable alongside your uploads and notes.
|
||||
|
||||
## Managing connections
|
||||
|
||||
Everything happens in the **Connectors** dialog:
|
||||
|
||||
- **Active** tab — see connected accounts, live status, and document counts.
|
||||
- **Reconnect** — if a token expires, the connector card prompts you to re-authorize.
|
||||
- **Disconnect** — removes the connection. For knowledge-base connectors this also removes the documents it indexed.
|
||||
15
surfsense_web/content/docs/connectors/external/meta.json
vendored
Normal file
15
surfsense_web/content/docs/connectors/external/meta.json
vendored
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
{
|
||||
"title": "External Connectors",
|
||||
"pages": [
|
||||
"google",
|
||||
"slack",
|
||||
"airtable",
|
||||
"onedrive",
|
||||
"dropbox",
|
||||
"github",
|
||||
"bookstack",
|
||||
"circleback",
|
||||
"obsidian"
|
||||
],
|
||||
"defaultOpen": false
|
||||
}
|
||||
73
surfsense_web/content/docs/connectors/external/obsidian.mdx
vendored
Normal file
73
surfsense_web/content/docs/connectors/external/obsidian.mdx
vendored
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: Obsidian
|
||||
description: Sync your Obsidian vault with the SurfSense plugin
|
||||
---
|
||||
|
||||
# Obsidian Plugin Setup Guide
|
||||
|
||||
SurfSense integrates with Obsidian through the SurfSense Obsidian plugin.
|
||||
|
||||
## How it works
|
||||
|
||||
The plugin runs inside your Obsidian app and pushes note updates to SurfSense over HTTPS.
|
||||
This works for cloud and self-hosted deployments, including desktop and mobile clients.
|
||||
|
||||
## What gets indexed
|
||||
|
||||
| Content Type | Description |
|
||||
|--------------|-------------|
|
||||
| Markdown files | Note content (`.md`) |
|
||||
| Frontmatter | YAML metadata like title, tags, aliases, dates |
|
||||
| Wiki links | Linked notes (`[[note]]`) |
|
||||
| Tags | Inline and frontmatter tags |
|
||||
| Vault metadata | Vault and path metadata used for deep links and sync state |
|
||||
|
||||
## Quick start
|
||||
|
||||
1. Open **Connectors** in SurfSense and choose **Obsidian**.
|
||||
2. Install the plugin (recommended via BRAT) using the steps below.
|
||||
3. In Obsidian, open **Settings → SurfSense**.
|
||||
4. Paste your SurfSense API token from the user settings section.
|
||||
5. Paste your Server URL in the plugin setting: either your SurfSense main domain (if `/api/v1` rewrites are enabled) or your direct backend URL.
|
||||
6. Choose the Workspace in the plugin, then the first sync should run automatically.
|
||||
7. Confirm the connector appears as **Obsidian - <vault>** in SurfSense.
|
||||
|
||||
## Install via BRAT (recommended)
|
||||
|
||||
1. In Obsidian, open **Settings → Community plugins** and install **[BRAT](obsidian://show-plugin?id=obsidian42-brat)**.
|
||||
2. Open BRAT settings and click **Add beta plugin** button.
|
||||
3. Paste the repository: `https://github.com/MODSetter/SurfSense/`.
|
||||
4. Select the latest plugin version, then click "Add plugin".
|
||||
5. Open **Settings → SurfSense** to finish setup.
|
||||
|
||||
## Migrating from the legacy connector
|
||||
|
||||
If you previously used the legacy Obsidian connector architecture, migrate to the plugin flow:
|
||||
|
||||
1. Delete the old legacy Obsidian connector from SurfSense.
|
||||
2. Install and configure the SurfSense Obsidian plugin using the quick start above.
|
||||
3. Run the first plugin sync and verify the new **Obsidian - <vault>** connector is active.
|
||||
|
||||
<Callout type="warn">
|
||||
Deleting the legacy connector also deletes all documents that were indexed by that connector. Always finish and verify plugin sync before deleting the old connector.
|
||||
</Callout>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Plugin connects but no files appear**
|
||||
- Verify the plugin is pointed to the correct Workspace.
|
||||
- Trigger a manual sync from the plugin settings.
|
||||
- Confirm your API token is valid and not expired.
|
||||
|
||||
**Self-hosted URL issues**
|
||||
- Use a public or LAN backend URL that your Obsidian device can reach.
|
||||
- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.
|
||||
|
||||
**Unauthorized / 401 errors**
|
||||
- Regenerate and paste a fresh API token from SurfSense.
|
||||
- Ensure the token belongs to the same account and workspace you are syncing into.
|
||||
|
||||
**Cannot reach server URL**
|
||||
- Check that the backend URL is reachable from the Obsidian device.
|
||||
- For self-hosted setups, verify firewall and reverse proxy rules.
|
||||
- Avoid using localhost unless SurfSense and Obsidian run on the same machine.
|
||||
78
surfsense_web/content/docs/connectors/external/onedrive.mdx
vendored
Normal file
78
surfsense_web/content/docs/connectors/external/onedrive.mdx
vendored
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Microsoft OneDrive
|
||||
description: Import your OneDrive files into the SurfSense knowledge base
|
||||
---
|
||||
|
||||
The OneDrive connector lets you pick files from OneDrive and index them into your knowledge base. It lives in the Documents sidebar's **Import** menu, not the connector catalog.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just use **Import → OneDrive**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create an Azure App Registration
|
||||
|
||||
1. Navigate to [portal.azure.com](https://portal.azure.com)
|
||||
2. Search for **"App registrations"** and open it
|
||||
3. Click **"+ New registration"** and fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **Supported account types** | **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts"** |
|
||||
| **Redirect URI** | Platform: `Web`, URI: `http://localhost:3929/api/v1/auth/onedrive/connector/callback` |
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
4. Click **"Register"**
|
||||
|
||||
## Step 2: Get the Application (Client) ID
|
||||
|
||||
On the app's **Overview** page, copy the **Application (client) ID** — this is your Client ID.
|
||||
|
||||
## Step 3: Create a Client Secret
|
||||
|
||||
1. Under **Manage**, click **"Certificates & secrets"**
|
||||
2. On the **"Client secrets"** tab, click **"+ New client secret"**
|
||||
3. Enter a description (e.g., `SurfSense`) and pick an expiration period
|
||||
4. Click **"Add"**
|
||||
5. **Important**: Copy the secret **Value** immediately — it will not be shown again!
|
||||
|
||||
## Step 4: Configure API Permissions
|
||||
|
||||
1. Under **Manage**, click **"API permissions"** > **"+ Add a permission"**
|
||||
2. Select **"Microsoft Graph"** > **"Delegated permissions"**
|
||||
3. Add all of the following:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `Files.Read.All` | Read all files the user can access |
|
||||
| `Files.ReadWrite.All` | Read and write all files the user can access |
|
||||
| `offline_access` | Maintain access to granted data |
|
||||
| `User.Read` | Sign in and read user profile |
|
||||
|
||||
4. Click **"Add permissions"**
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
## Step 5: Add the Credentials to SurfSense
|
||||
|
||||
Add the credentials to your `.env` file:
|
||||
|
||||
```bash
|
||||
MICROSOFT_CLIENT_ID=your_microsoft_client_id
|
||||
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open **Documents → Import → OneDrive**, and authorize:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
98
surfsense_web/content/docs/connectors/external/slack.mdx
vendored
Normal file
98
surfsense_web/content/docs/connectors/external/slack.mdx
vendored
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
title: Slack
|
||||
description: Let the SurfSense agent search and read your Slack workspace
|
||||
---
|
||||
|
||||
The Slack connector connects SurfSense to Slack's hosted MCP server, giving the agent live tools to search channels and read threads on your behalf. Nothing is indexed in the background — the agent queries Slack in real time when you ask.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a New Slack App
|
||||
|
||||
1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
|
||||
2. Click **"Create New App"**
|
||||
3. Select **"From scratch"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Name App & Choose Workspace
|
||||
|
||||
1. Enter **App Name**: `SurfSense`
|
||||
2. Select the workspace to develop your app in
|
||||
3. Click **"Create App"**
|
||||
|
||||
<Callout type="warn">
|
||||
You won't be able to change the workspace later. The workspace will control the app even if you leave it.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 3: Get App Credentials
|
||||
|
||||
On the **Basic Information** page:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret** (click Show to reveal)
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure the Redirect URL
|
||||
|
||||
1. In the left sidebar, click **"OAuth & Permissions"**
|
||||
2. Under **Redirect URLs**, click **"Add New Redirect URL"**
|
||||
3. Enter your SurfSense callback URL:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/mcp/slack/connector/callback
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain. Note that Slack requires HTTPS redirect URLs for production apps.
|
||||
</Callout>
|
||||
|
||||
4. Click **"Add"**, then **"Save URLs"**
|
||||
|
||||
|
||||
|
||||
## Step 5: Configure User Token Scopes
|
||||
|
||||
On the same **OAuth & Permissions** page, scroll to **Scopes**. The connector acts on behalf of the connecting user, so add these under **User Token Scopes**:
|
||||
|
||||
| OAuth Scope | Description |
|
||||
|-------------|-------------|
|
||||
| `search:read.public` | Search public channels |
|
||||
| `search:read.private` | Search private channels the user is in |
|
||||
| `search:read.mpim` | Search group direct messages |
|
||||
| `search:read.im` | Search direct messages |
|
||||
| `channels:history` | Read messages in public channels |
|
||||
| `groups:history` | Read messages in private channels |
|
||||
| `mpim:history` | Read group direct messages |
|
||||
| `im:history` | Read direct messages |
|
||||
|
||||
## Step 6: Enable Public Distribution
|
||||
|
||||
1. In the left sidebar, click **"Manage Distribution"**
|
||||
2. Under **Share Your App with Other Workspaces**, enable distribution so users can authorize the app in their own workspaces
|
||||
|
||||
|
||||
|
||||
## Step 7: Add the Credentials to SurfSense
|
||||
|
||||
Add the Client ID and Client Secret to your `.env` file:
|
||||
|
||||
```bash
|
||||
SLACK_CLIENT_ID=your_slack_client_id
|
||||
SLACK_CLIENT_SECRET=your_slack_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open the **Connectors** dialog, and click **Connect** on Slack:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app credentials publicly.
|
||||
</Callout>
|
||||
Loading…
Add table
Add a link
Reference in a new issue