# MCP Hub

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/Docker-ready-0db7ed.svg)](docker/)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)

**MCP Hub** is a self-hosted AI operations platform with a unified MCP gateway, semantic tool routing, persistent vector memory, automation scheduler, multi-agent flows, and a full ReAct orchestration engine.

Connect **Claude Desktop**, **ChatGPT**, **Cursor**, **Telegram**, or any MCP client to **130+ tools** across 12 integrations — through **just 3 hub endpoints**. The AI never drowns in schemas. It searches, finds, and acts.

---

## The Core Idea

Most MCP setups dump every tool schema into the AI's context window on every call. With 10 integrations and 130+ tools, that's thousands of tokens wasted before the AI even starts thinking.

MCP Hub does it differently:

```
AI sees:           hub.integrations.list
                   hub.tools.search        ← semantic vector search
                   hub.tools.call

Behind the scenes: 130+ tools across 12 integrations
                   Local embedding model routes queries to the right tools
                   ReAct loop executes multi-step tasks autonomously
```

The AI calls `hub.tools.search("teamwork create task; add task to project")` and gets back exactly the 3-5 tools it needs. Nothing else enters the context. Token usage drops by 60-80% on complex tasks.

---

## Why MCP Hub?

| Problem | Solution |
|---------|----------|
| 130+ tool schemas bloat every LLM call | Semantic routing — AI sees only relevant tools |
| AI can't remember context between sessions | Persistent vector memory with FTS5 + embedding search |
| Each integration needs its own MCP server | Single gateway for everything |
| Token security concerns | AES-256 encrypted storage, tokens never exposed to AI |
| No visibility into what AI does | Full audit trail — every tool call logged |
| Team needs shared access | Multi-user with admin approval, per-user credentials |
| Complex deployment | Single Docker container, SQLite, zero external services |
| Repetitive tasks need automation | Built-in cron/interval/event scheduler with LLM payloads |

---

## Integrations

| Integration | Auth | Tools | What it does |
|-------------|------|------:|--------------|
| **Teamwork** | OAuth 2.0 | 47 | Projects, tasks, subtasks, dependencies, time tracking, tags, comments, board management |
| **Slack** | OAuth 2.0 | 19 | Channels, messages, DMs, user lookup, canvases |
| **Miro** | OAuth 2.0 | 18 | Boards, sticky notes, text, shapes, cards, connectors |
| **Figma** | OAuth 2.0 | 20 | CSS extraction, layout trees, images, comments, components, styles |
| **Google Calendar** | OAuth 2.0 | 7 | Calendars, events (list/get/create/update/delete), Google Meet |
| **Binance** | API Key | 11 | Market data + indicators (RSI, MACD, Bollinger), order book, spot trading, portfolio |
| **Telegram** | MTProto | 5 | Personal account — dialogs, messages, search, history, send |
| **Telegram Bot** | Bot Token | 2 | Notifications, alerts via Bot API |
| **Memory** | Built-in | 7 | Persistent AI memory with FTS5 + semantic vector search |
| **Automation** | Built-in | 11 | Interval/cron/event scheduler, run history, LLM payloads |
| **Agents** | Built-in | 21 | Multi-agent flows, graph orchestration, delegation, skills |
| **Web Search** | Built-in | 3 | Web search, page fetch, full-search with content extraction |
| **Hub** | — | 4 | Semantic discovery + tool routing |
| | | **170+** | |

---

## Semantic Tool Routing

The centerpiece of MCP Hub's architecture. Instead of loading all 130+ tool schemas on every call, a local **sentence-transformers** model runs on CPU and routes each request to the 3-5 most relevant tools.

```
User: "create a task in teamwork for the design review"

  ↓  LLM generates search phrases:
     "teamwork create task; add task to project; teamwork tasks"

  ↓  Embedding model finds:
     teamwork.tasks.bulk_create   (score: 0.94)
     teamwork.tasklists.list      (score: 0.87)
     teamwork.projects.list       (score: 0.85)

  ↓  AI calls hub.tools.call → done
```

**How it works:**
- On startup, every tool is embedded: `tool name + description + use cases + tags`
- Per request, `_expand_semantic_intents` generates 3-5 action phrases from the user query
- Cosine similarity ranks all tools → top N sent to LLM
- Result: the AI only ever sees tools it actually needs

**Token impact:** A complex 5-step automation that previously consumed ~60K tokens now uses ~20-30K. The AI still has full access to all 130+ tools — it just fetches them on demand.

---

## Memory with Vector Search

Persistent AI memory that works across conversations, automations, and agents. Now with **dual search**: FTS5 full-text + semantic embedding search.

```
Saved:   "prefer concise summaries, not bullet points"
Search:  "formatting style preference"  →  found (semantic, no exact keyword match)

Saved:   "BNB target price $700"
Search:  "my crypto goals binance"  →  found (semantic scope match)
```

**Memory item types with auto TTL:**

| Type | Lifetime | Use |
|------|----------|-----|
| `preference` | Permanent | User preferences, style settings |
| `constraint` | Permanent | Rules the AI must follow |
| `decision` | Permanent | Important decisions made |
| `project` | Permanent | Active project context |
| `contact` | Permanent | People and entities |
| `asset` | Permanent | Tracked assets, crypto positions |
| `goal` | 30 days | Objectives and targets |
| `note` | 7 days | Temporary notes (pin to keep forever) |

**Features:**
- Auto-vectorized on save — every upsert computes and stores embedding
- Hybrid search — FTS5 keywords + vector similarity, results merged and deduplicated
- `memory.summarize_context(query="...")` — semantic context pack: returns only relevant memories for the current task instead of dumping everything
- Secret detection — blocks auto-saving passwords, API keys, tokens
- Scope filtering — memories can be scoped to specific integrations (binance, teamwork, etc.)

---

## ReAct Orchestration Engine

Every chat message, automation payload, and agent run goes through the built-in ReAct loop:

```
Step 1: Understand intent, detect provider, generate semantic search phrases
Step 2: hub.tools.search → find relevant tools
Step 3: hub.tools.call → execute
Step 4: Observe result → verify → iterate if needed
Step 5: Synthesize final answer
```

**Smart behaviours built in:**
- **Identity bootstrap** — for "my tasks" requests, auto-fetches `users.me` before listing
- **Progressive tool disclosure** — new providers loaded only when actually needed
- **Repeated call guard** — prevents identical tool calls from looping
- **Send short-circuit** — for action requests, returns immediately after success
- **Web search fallback** — if a URL fetch times out, retries with next search result
- **Multi-LLM** — OpenAI, Anthropic, Google, DeepSeek — configured per user

---

## Automation Engine

Schedule any LLM workflow. The automation engine is itself accessible via MCP tools, so AI agents can create, update, and monitor their own scheduled tasks.

**Trigger types:**
- `interval` — run every N seconds (with optional `start_at` / `end_at` window for one-shot runs)
- `cron` — full cron expression with timezone (`0 8 * * *` for 08:00 daily)
- `event` — trigger on named event emitted from tools or webhooks

**Payload types:**
- `telegram_bot_message` — send a notification
- `llm_tool_agent` — full ReAct loop with any prompt and tool access
- `mcp_tool` — call a specific tool with arguments

**Practical recipes:**

```
Daily BNB market report at 08:00
  cron: "0 8 * * *"
  payload: llm_tool_agent
  prompt: "Fetch BNBUSDT 1h and 4h klines with RSI/MACD/SMA indicators.
           Read my BNB goals from memory. Generate concise analysis.
           Send to Telegram."

Weekly Teamwork summary every Monday 09:00
  cron: "0 9 * * 1"
  prompt: "List my overdue tasks and tasks due this week.
           Summarize in bullet points. Send to Slack #general."

One-shot reminder in 5 minutes
  interval_sec: 60, start_at: now+5min, end_at: start_at+90sec
  payload: telegram_bot_message
```

---

## Multi-Agent Flows

Build graphs of specialized agents that delegate to each other. Each agent has:
- Its own system prompt
- Allowed tool set (policy per integration/tool)
- Mounted skills from the global catalog
- Optional custom MCP server connections

```
Flow: "Morning Operations"

  Orchestrator Agent
  ├── delegates to → Market Agent (Binance tools only)
  ├── delegates to → Calendar Agent (Google Calendar tools only)
  └── delegates to → Notifier Agent (Telegram Bot only)
```

Flows can be triggered manually, via automation scheduler, or through MCP.

---

## Hub Protocol — How AI Clients Use It

The hub exposes 4 meta-tools that give AI clients full access to everything without schema bloat:

| Tool | When to use |
|------|-------------|
| `hub.integrations.list` | Discover which providers are connected |
| `hub.tools.search` | **Primary** — find tools by semantic intent. Query = 2-4 action phrases |
| `hub.tools.list` | Browse all tools for a specific provider |
| `hub.tools.call` | Execute a tool by exact name |

**Optimal workflow for any AI client:**

```
1. hub.tools.search(query="teamwork create task; add task to project")
   → returns: teamwork.tasks.bulk_create, teamwork.projects.list, teamwork.tasklists.list

2. hub.tools.call(provider="teamwork", tool_name="teamwork.tasks.bulk_create",
                  arguments={...})
   → done
```

**Query format for `hub.tools.search`:**
- Use 2-4 short action phrases separated by `;`
- Include provider name + action verb + entity type
- Examples:
  - `"slack send message; post to channel"`
  - `"telegram list dialogs; my chats"`
  - `"binance get ticker BNBUSDT; market price"`
  - `"memory save preference; remember this"`

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│           AI Clients                                                 │
│   Claude Desktop  │  ChatGPT  │  Cursor  │  Telegram Bot  │  Web UI │
└──────────────────────┬───────────────────────────────────────────────┘
                       │  JSON-RPC 2.0 + Bearer Token
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         MCP Hub                                      │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              Semantic Tool Router                            │    │
│  │  sentence-transformers (CPU)  ·  cosine similarity          │    │
│  │  intent expansion  ·  provider ranking  ·  tool ranking     │    │
│  └───────────────────────────┬─────────────────────────────────┘    │
│                              │                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              ReAct Orchestration Engine                      │    │
│  │  hub.tools.search  ·  hub.tools.call  ·  multi-step loop    │    │
│  │  identity bootstrap  ·  retry logic  ·  answer synthesis    │    │
│  └───────────────────────────┬─────────────────────────────────┘    │
│                              │                                       │
│  ┌──────┬──────┬──────┬──────┴──────┬──────┬──────┬──────┬───────┐  │
│  │Team- │Slack │Miro  │Figma        │Bin-  │Tele- │Mem-  │Auto-  │  │
│  │work  │      │      │             │ance  │gram  │ory   │mation │  │
│  │47    │19    │18    │20           │11    │5+2   │7     │11     │  │
│  │tools │tools │tools │tools        │tools │tools │tools │tools  │  │
│  └──────┴──────┴──────┴─────────────┴──────┴──────┴──────┴───────┘  │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  SQLite  │  FTS5  │  Vector Embeddings  │  AES-256 Tokens   │    │
│  │  Audit Log  │  OAuth 2.0 + PKCE  │  Auto Migrations        │    │
│  └─────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘
```

---

## Quick Start

### Docker (Recommended)

```bash
git clone https://github.com/Vangardo/mcp_hub.git
cd mcp_hub

cp .env.example .env
# Set: ADMIN_EMAIL, ADMIN_PASSWORD, JWT_SECRET, TOKENS_ENCRYPTION_KEY

cd docker
docker-compose up -d

# Open http://localhost:8000
```

### Local Development

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

---

## Connecting AI Clients

### Claude Desktop

Generate a **Personal Access Token** in MCP Hub → Settings → Tokens, then add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-hub": {
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PAT_TOKEN"
      }
    }
  }
}
```

### ChatGPT (Actions)

1. Click **Get GPT Config** in MCP Hub
2. Use the **OAuth** tab — ChatGPT auto-discovers endpoints via RFC 8414
3. Server URL: `https://your-domain.com/mcp`

### Cursor / Other MCP Clients

Same as Claude Desktop — Bearer token + MCP endpoint URL.

### Provider-Scoped Connections (optional)

Add `X-MCP-Provider` header to expose a single integration directly (bypasses hub meta-tools):

```json
{
  "mcpServers": {
    "mcp-hub-teamwork": {
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-MCP-Provider": "teamwork"
      }
    }
  }
}
```

---

## Security

| Feature | Details |
|---------|---------|
| **Token encryption** | AES-256 at rest for all OAuth/API tokens |
| **JWT authentication** | Configurable expiration, refresh token rotation |
| **Personal Access Tokens** | SHA-256 hashed, expiration support, last-used tracking |
| **OAuth 2.0 + PKCE** | Full RFC 8414/7591/9728 for ChatGPT integration |
| **Client Credentials** | Machine-to-machine auth for custom apps |
| **Audit logging** | Every tool call: user, provider, tool name, request, response, status |
| **Memory safety** | Pattern detection blocks auto-saving passwords, keys, secrets |
| **Admin approval** | New users require admin approval before access |
| **Per-user isolation** | Each user's credentials, memory, and connections are fully isolated |

---

## Admin Panel

Navigate to **Admin** in the top nav (admin users only):

- **Users** — Approve/reject signups, manage roles, reset passwords, view per-user connections
- **Audit Log** — Filter by user, provider, action, status, date range. Full request/response payloads
- **Settings** — Configure public URL, LLM defaults, OAuth credentials for all integrations

---

## Configuration

### Required

```bash
ADMIN_EMAIL=admin@example.com       # Auto-created on first run
ADMIN_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-min-32-chars
TOKENS_ENCRYPTION_KEY=your-32-char-encryption-key
BASE_URL=http://localhost:8000
```

### Semantic Routing (optional tuning)

```bash
SEMANTIC_TOOL_ROUTING_ENABLED=true
EMBEDDING_MODEL_NAME=intfloat/multilingual-e5-small   # Downloads on first run
SEMANTIC_TOP_PROVIDERS=3
SEMANTIC_TOP_TOOLS=5
SEMANTIC_INTENT_EXPANSION_ENABLED=true
SEMANTIC_INTENT_PHRASE_COUNT=5
```

### Integration Credentials

```bash
# Teamwork (https://developer.teamwork.com/)
TEAMWORK_CLIENT_ID=
TEAMWORK_CLIENT_SECRET=

# Slack (https://api.slack.com/apps)
SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=

# Miro (https://miro.com/app/settings/user-profile/apps)
MIRO_CLIENT_ID=
MIRO_CLIENT_SECRET=

# Figma (https://www.figma.com/developers/apps)
FIGMA_CLIENT_ID=
FIGMA_CLIENT_SECRET=

# Google Calendar (https://console.cloud.google.com/apis/credentials)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Telegram personal account (https://my.telegram.org/)
TELEGRAM_API_ID=
TELEGRAM_API_HASH=

# Binance — users connect via their own API Key in the UI
# No server-side credentials needed
```

All credentials can also be configured via **Admin > Settings** in the web UI.

---

## Tools Reference

### Hub (4 tools)

| Tool | Description |
|------|-------------|
| `hub.integrations.list` | List connected integrations with tool counts |
| `hub.tools.search` | **Semantic search** — find tools by intent phrases. Primary discovery method |
| `hub.tools.list` | List all tools for a specific provider |
| `hub.tools.call` | Execute a tool by exact name with arguments |

### Teamwork (47 tools)

<details>
<summary>Projects & People</summary>

| Tool | Description |
|------|-------------|
| `teamwork.projects.list` | List all projects |
| `teamwork.people.list` | List team members |
| `teamwork.people.me` | Get current user |
</details>

<details>
<summary>Tasks — Read</summary>

| Tool | Description |
|------|-------------|
| `teamwork.tasks.list` | List tasks with filters (status, assignee, due date, tags) |
| `teamwork.tasks.get` | Get full task details by ID |
| `teamwork.tasks.due_today` | Tasks due today |
| `teamwork.tasks.overdue` | Overdue tasks |
| `teamwork.tasks.actionable` | Unblocked tasks ready to work on |
| `teamwork.tasks.blocked` | Tasks blocked by dependencies |
</details>

<details>
<summary>Tasks — Create & Update</summary>

| Tool | Description |
|------|-------------|
| `teamwork.tasks.bulk_create` | Create up to 10 tasks with subtasks, dependencies, and tags |
| `teamwork.tasks.bulk_update` | Update up to 10 tasks at once |
| `teamwork.tasks.complete` | Mark task as complete |
</details>

<details>
<summary>Task Lists</summary>

| Tool | Description |
|------|-------------|
| `teamwork.tasklists.list` | List task lists in a project |
| `teamwork.tasklists.get` | Get list details |
| `teamwork.tasklists.create` | Create new list |
| `teamwork.tasklists.update` | Update list |
| `teamwork.tasklists.delete` | Delete list |
| `teamwork.tasklists.copy` | Copy list to another project |
| `teamwork.tasklists.move` | Move list to another project |
</details>

<details>
<summary>Subtasks & Dependencies</summary>

| Tool | Description |
|------|-------------|
| `teamwork.subtasks.create` | Create subtask under parent |
| `teamwork.subtasks.list` | List subtasks |
| `teamwork.dependencies.get` | Get predecessors & dependents |
| `teamwork.dependencies.set` | Replace all predecessors |
| `teamwork.dependencies.add` | Add one predecessor |
| `teamwork.dependencies.remove` | Remove one predecessor |
| `teamwork.dependencies.clear` | Remove all predecessors |
| `teamwork.dependencies.bulk_set` | Set dependencies for up to 10 tasks |
</details>

<details>
<summary>Time Tracking</summary>

| Tool | Description |
|------|-------------|
| `teamwork.time.log` | Log time entry |
| `teamwork.time.list` | List time entries |
| `teamwork.time.totals` | Get time totals for reporting |
</details>

<details>
<summary>Tags, Comments & Board</summary>

| Tool | Description |
|------|-------------|
| `teamwork.tags.list` | List all tags |
| `teamwork.tags.ensure` | Get or create tag by name |
| `teamwork.tags.create` | Create tag |
| `teamwork.tags.update` | Update tag |
| `teamwork.tags.delete` | Delete tag |
| `teamwork.comments.add` | Add comment to task |
| `teamwork.comments.list` | List task comments |
| `teamwork.workflows.list` | List workflow stages |
| `teamwork.stages.list` | List board columns |
| `teamwork.tasks.set_stage` | Move task to stage by ID |
| `teamwork.tasks.set_stage_by_name` | Move task to stage by name |
| `teamwork.tasks.move_to_column` | Move task to column by ID |
| `teamwork.tasks.move_to_column_by_name` | Move task to column by name |
</details>

### Slack (19 tools)

<details>
<summary>Channels & Users</summary>

| Tool | Description |
|------|-------------|
| `slack.channels.list` | List channels (public, private, or filtered) |
| `slack.users.list` | List workspace users |
| `slack.users.me` | Get current user |
| `slack.users.info` | Get user details by ID |
| `slack.users.find_by_email` | Find user by email |
</details>

<details>
<summary>Messages & DMs</summary>

| Tool | Description |
|------|-------------|
| `slack.messages.post` | Post to channel (supports threads) |
| `slack.messages.history` | Get channel message history |
| `slack.dm.list` | List 1:1 DMs |
| `slack.dm.group_list` | List group DMs |
| `slack.dm.send` | Send direct message |
| `slack.dm.history` | Get DM history |
| `slack.dm.open` | Open DM with user |
| `slack.dm.open_group` | Open group DM |
</details>

<details>
<summary>Canvases</summary>

| Tool | Description |
|------|-------------|
| `slack.canvas.create` | Create canvas with markdown |
| `slack.canvas.edit` | Edit content (append/prepend/replace) |
| `slack.canvas.delete` | Delete canvas |
| `slack.canvas.share` | Share with users/channels |
| `slack.canvas.sections_lookup` | Find sections by heading |
</details>

### Miro (18 tools)

<details>
<summary>Boards</summary>

| Tool | Description |
|------|-------------|
| `miro.boards.list` | Search/list boards |
| `miro.boards.get` | Get board details |
| `miro.boards.create` | Create board |
| `miro.boards.update` | Update board |
| `miro.boards.delete` | Delete board |
| `miro.boards.copy` | Copy board with content |
| `miro.boards.members` | List board members & roles |
| `miro.boards.share` | Share with users by email |
| `miro.users.me` | Get current user |
</details>

<details>
<summary>Items & Content</summary>

| Tool | Description |
|------|-------------|
| `miro.items.list` | List items (filter by type) |
| `miro.items.get` | Get item details |
| `miro.items.delete` | Delete item |
| `miro.sticky_notes.bulk_create` | Create up to 10 sticky notes |
| `miro.text.bulk_create` | Create up to 10 text items |
| `miro.shapes.bulk_create` | Create up to 10 shapes (20+ types) |
| `miro.cards.bulk_create` | Create up to 10 cards |
| `miro.connectors.bulk_create` | Create up to 10 connectors |
</details>

### Figma (20 tools)

<details>
<summary>Dev & Layout</summary>

| Tool | Description |
|------|-------------|
| `figma.dev.get_page` | **Main tool** — CSS-ready HTML + design tokens. Overview or CSS mode |
| `figma.files.get_layout` | Compact text tree of file structure |
| `figma.users.me` | Get current user |
| `figma.files.get_meta` | Lightweight file metadata |
| `figma.images.export` | Export nodes as PNG/SVG/JPG/PDF |
| `figma.images.get_fills` | Get image fill URLs |
| `figma.files.versions` | List file versions |
</details>

<details>
<summary>Comments, Components & Styles</summary>

| Tool | Description |
|------|-------------|
| `figma.comments.list` | List comments |
| `figma.comments.create` | Create comment |
| `figma.comments.delete` | Delete comment |
| `figma.projects.list` | List team projects |
| `figma.projects.files` | List files in project |
| `figma.components.list_team` | List published team components |
| `figma.components.list_file` | List file components |
| `figma.components.get` | Get component metadata |
| `figma.styles.list_team` | List published styles |
| `figma.styles.list_file` | List file styles |
| `figma.styles.get` | Get style metadata |
</details>

### Binance (11 tools)

<details>
<summary>Market Data</summary>

| Tool | Description |
|------|-------------|
| `binance.market.klines` | OHLCV candles + indicators (RSI 14, MACD 12/26/9, Bollinger 20/2, SMA 20). Always include `indicators` in one call. |
| `binance.market.ticker` | 24h price stats. Omit symbol for top 20 by volume |
| `binance.market.depth` | Order book with spread analysis and wall detection |
| `binance.market.top_movers` | Top gainers/losers (filters low-volume pairs) |
</details>

<details>
<summary>Account & Trading</summary>

| Tool | Description |
|------|-------------|
| `binance.account.portfolio` | Spot balances with estimated USD values |
| `binance.account.open_orders` | List unfilled orders |
| `binance.account.trade_history` | Recent executed trades |
| `binance.trade.buy` | Place BUY order (MARKET / LIMIT) |
| `binance.trade.sell` | Place SELL order (MARKET / LIMIT) |
| `binance.trade.cancel` | Cancel order by ID |
| `binance.trade.order_status` | Check order status |
</details>

### Telegram (5 + 2 tools)

**Personal account (MTProto)** — send as yourself, read history, search:

| Tool | Description |
|------|-------------|
| `telegram.users.me` | Get current user info |
| `telegram.dialogs.list` | List all chats |
| `telegram.messages.send` | Send message to peer (username, phone, or ID) |
| `telegram.messages.search` | Search messages |
| `telegram.messages.history` | Get chat history |

**Bot API** — notifications only:

| Tool | Description |
|------|-------------|
| `telegram_bot.notifications.send` | Send notification via bot (requires chat_id) |
| `telegram_bot.users.me` | Get bot identity |

### Memory (7 tools)

Built-in — always available, no connection needed.

| Tool | Description |
|------|-------------|
| `memory.summarize_context` | Load context pack by sections. Pass `query=` for semantic relevance filtering |
| `memory.search` | Hybrid search: FTS5 keywords + vector similarity, results merged |
| `memory.upsert` | Create/update item. Auto-vectorized. Deduplicates by (type + scope + title) |
| `memory.delete` | Delete by ID or title |
| `memory.pin` | Toggle pinned status (pinned items never expire) |
| `memory.set_ttl` | Set expiration in days (null = permanent) |
| `memory.evaluate_write` | Pre-save check — detects secrets, validates sensitivity, suggests TTL |

### Web Search (3 tools)

| Tool | Description |
|------|-------------|
| `web_search.search` | Search the web. Returns titles, URLs, snippets |
| `web_search.open` | Fetch and extract text from any URL |
| `web_search.full_search` | Combined: search + open top results in one call |

---

## Database

SQLite with automatic migrations on startup. Zero configuration required.

| Table | Purpose |
|-------|---------|
| `users` | Accounts, roles (admin/user), approval status |
| `connections` | OAuth tokens (AES-256 encrypted), connection metadata |
| `refresh_tokens` | JWT refresh token rotation |
| `personal_access_tokens` | PAT with SHA-256 hashing & expiration |
| `api_clients` | Client credentials for OAuth 2.0 apps |
| `audit_logs` | Full tool call audit trail |
| `chat_threads`, `chat_messages` | Web/Telegram conversation history |
| `memory_items` | AI memory with FTS5 search index |
| `memory_items_fts` | FTS5 virtual table (auto-synced via triggers) |
| `memory_item_embeddings` | Vector embeddings for semantic memory search |
| `tool_embeddings` | Vector embeddings for semantic tool routing |
| `provider_embeddings` | Vector embeddings for provider-level routing |
| `automation_tasks`, `task_triggers`, `task_runs`, `task_queue` | Scheduler engine |
| `agents`, `agent_edges`, `agent_tool_policies`, `agent_skills` | Agent graph and policies |
| `agent_flows`, `agent_flow_runs` | Flow definitions and execution history |
| `user_skill_catalog` | Global reusable skills library |

---

## API Endpoints

Interactive docs at `/docs` (Swagger) and `/redoc`.

| Endpoint | Description |
|----------|-------------|
| `POST /mcp` | MCP JSON-RPC 2.0 gateway |
| `POST /auth/login` | User login |
| `POST /auth/refresh` | Refresh access token |
| `POST /auth/personal_token` | Create Personal Access Token |
| `GET /integrations` | Integration status |
| `GET /config/mcp` | MCP config for AI clients |
| `GET /api/chat/*` | Chat threads, messages, assistant execution |
| `GET /api/tasks/*` | Automation tasks, triggers, runs |
| `GET /api/agents/*` | Agents, flows, policies, skills |
| `GET /memory` | Memory management UI |
| `GET /.well-known/oauth-authorization-server` | OAuth 2.0 metadata (RFC 8414) |

---

## Adding New Integrations

1. Create `app/integrations/your_integration/`
2. Implement `BaseIntegration` (see `app/integrations/base.py`):
   - `name`, `display_name`, `description`, `auth_type`
   - `get_tools()` → list of `ToolDefinition` with `use_cases` and `tags` for semantic routing
   - `execute_tool()` → dispatch to tool handlers
3. Register in `app/integrations/registry.py`
4. Add UI card in `app/ui/templates/integrations.html`

Tools are automatically embedded into the semantic index on next startup — no additional configuration.

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

**MCP Hub** — 130+ tools. 3 endpoints. One server. Semantic routing, vector memory, ReAct orchestration, multi-agent flows, and automation — all self-hosted.