[integrations] Enhanced MCP server with alpha tool suite

docs/01-getting-started.md

@@ -239,9 +239,7 @@ You'll land on the **"Publishable and secret API keys"** tab. Copy these into yo
 - 🔖 **Secret key** — Scroll down to the **"Secret keys"** section on the same page. You'll see a `default` key. Click the copy button to copy it. (You can also click **"+ New secret key"** to create a dedicated one named `open-brain` — this makes it easier to revoke later without affecting other services, but using the default is fine too.)
 
 > [!WARNING]
-> Treat the Secret key like a password. Anyone with it has full access to your data. The "Publishable key" at the top of the page is safe to expose publicly — you don't need it for this setup.
->
-> You may also see a **"Legacy anon, service_role API keys"** tab — those are the old-style JWT keys. You don't need them. Everything in this guide uses the new key format.
+> Treat the Secret key like a password. Anyone with it has full access to your data. The "Publishable key" at the top of the page is safe to expose publicly — you don't need it for this setup. You may also see a **"Legacy anon, service_role API keys"** tab — those are the old-style JWT keys. You don't need them. Everything in this guide uses the new key format.
 
 ✅ **Done when:** Your credential tracker has both **Project URL** and **Secret key** filled in.
 
@@ -289,6 +287,8 @@ Copy the output — it'll look something like `a3f8b2c1d4e5...` (64 characters).
 > [!WARNING]
 > Copy and paste the command for **your operating system only**. The Mac command won't work on Windows and vice versa.
 
+<!-- -->
+
 > [!IMPORTANT]
 > This is your **one access key for all of Open Brain** — core setup and every extension you add later. Save it somewhere permanent. Never generate a new one unless you want to replace it for ALL deployed functions.
 
@@ -419,9 +419,12 @@ supabase secrets set OPENROUTER_API_KEY=your-openrouter-key-here
 > [!CAUTION]
 > Make sure the access key you set here **exactly matches** what you saved in your credential tracker. If they don't match, you'll get 401 errors when connecting your AI.
 
+<!-- -->
+
 > **If you ever rotate your OpenRouter key:** you must re-run the `supabase secrets set` command above with the new key, AND update any local `.env` files that reference it. The edge function reads from Supabase secrets at runtime — updating the key on openrouter.ai alone won't propagate here. See the [FAQ on key rotation](03-faq.md#api-key-rotation) for the full checklist.
 
 ### Create the Function
+
 ![6.6](https://img.shields.io/badge/6.6-Download_the_Server_Files-555?style=for-the-badge&labelColor=1E88E5)
 
 Three commands, run them one at a time in order:

docs/03-faq.md

@@ -173,6 +173,7 @@ When you generate a new key on openrouter.ai/keys, the old key is revoked immedi
 **Places your OpenRouter key lives (update ALL of them):**
 
 1. **Supabase Edge Function secrets** — This is the most common one to miss. Your MCP server reads the key from here at runtime.
+
    ```bash
    supabase secrets set OPENROUTER_API_KEY=sk-or-v1-your-new-key
    ```

docs/05-tool-audit.md

@@ -81,6 +81,7 @@ Once you've identified bloat, here are the patterns for consolidating.
 Instead of 5 separate tools per table, expose one tool with an `action` parameter:
 
 **Before (5 tools):**
+
 ```
 create_recipe
 get_recipe
@@ -90,6 +91,7 @@ list_recipes
 ```
 
 **After (1 tool):**
+
 ```
 manage_recipe
   action: "create" | "read" | "update" | "delete" | "list"
@@ -107,6 +109,7 @@ manage_recipe
 A gentler consolidation that preserves clear intent:
 
 **Before (5 tools):**
+
 ```
 create_recipe
 get_recipe
@@ -116,6 +119,7 @@ search_recipes
 ```
 
 **After (2 tools):**
+
 ```
 save_recipe       — creates or updates (upsert pattern)
 query_recipes      — search, filter, get by ID, list all
@@ -132,6 +136,7 @@ This maps to how people actually talk to their AI: "save this" or "find that." T
 For tables with similar schemas (all your Open Brain extension tables follow the same `user_id` + timestamps + domain fields pattern), you can go further:
 
 **Before (20+ tools across 4 extensions):**
+
 ```
 add_household_item, search_household_items, get_item_details,
 add_vendor, list_vendors,
@@ -140,6 +145,7 @@ search_maintenance_history, add_family_member, ...
 ```
 
 **After (2–3 tools):**
+
 ```
 save_entity
   entity_type: "household_item" | "vendor" | "maintenance_task" | ...
@@ -177,6 +183,7 @@ Merging tools reduces count within a server. Scoping splits tools across servers
 Most Open Brain users' workflows fall into three modes:
 
 #### Capture server (write-heavy)
+
 **When you use it:** Quick capture moments — jotting down a thought, logging a contact interaction, saving a recipe.
 
 **Tools to include:**
@@ -189,6 +196,7 @@ Most Open Brain users' workflows fall into three modes:
 **Context cost:** ~5–8 tools, ~1,500–3,000 tokens.
 
 #### Query server (read-heavy)
+
 **When you use it:** Research, recall, weekly reviews, planning sessions — any time you're pulling information out rather than putting it in.
 
 **Tools to include:**
@@ -202,6 +210,7 @@ Most Open Brain users' workflows fall into three modes:
 **Context cost:** ~8–12 tools, ~3,000–5,000 tokens.
 
 #### Admin server (rarely used)
+
 **When you use it:** Occasional maintenance — bulk updates, deletions, schema changes, data cleanup.
 
 **Tools to include:**

integrations/enhanced-mcp/README.md

@@ -0,0 +1,145 @@
+# Enhanced MCP Server
+
+> Production-grade remote MCP server expanding the Open Brain tool surface from 4 to 14 tools with enhanced search, CRUD, enrichment, sensitivity detection, and operational monitoring.
+
+## What It Does
+
+This integration deploys a second MCP server alongside the stock Open Brain server. It adds semantic and full-text search modes, content dedup via SHA-256 fingerprinting, automatic LLM-powered metadata classification, sensitivity detection (restricted content is blocked from cloud capture), and operational monitoring tools that light up when optional schemas are installed.
+
+The original `server/` connector remains untouched. You can run both side by side and disable the original when you are ready.
+
+## Prerequisites
+
+- Working Open Brain setup ([guide](../../docs/01-getting-started.md))
+- **Enhanced Thoughts schema applied** — install `schemas/enhanced-thoughts` first (adds type, importance, sensitivity columns and utility RPCs)
+- OpenRouter API key (same one from the Getting Started guide)
+- Supabase CLI installed for deployment
+- Optional: `schemas/smart-ingest` (unlocks `ops_capture_status` tool)
+- Optional: `schemas/knowledge-graph` (unlocks `graph_search`, `entity_detail`, `ops_source_monitor` tools)
+
+## Credential Tracker
+
+Copy this block into a text editor and fill it in as you go.
+
+```text
+ENHANCED MCP SERVER -- CREDENTIAL TRACKER
+------------------------------------------
+
+FROM YOUR OPEN BRAIN SETUP
+  Project URL:           ____________
+  Service role key:      ____________
+  MCP access key:        ____________
+  OpenRouter API key:    ____________
+
+OPTIONAL (for multi-provider fallback)
+  OpenAI API key:        ____________
+  Anthropic API key:     ____________
+
+------------------------------------------
+```
+
+## Steps
+
+### 1. Deploy the Edge Function
+
+Copy the `integrations/enhanced-mcp/` folder into your Supabase project's `supabase/functions/` directory, then deploy:
+
+```bash
+supabase functions deploy enhanced-mcp --no-verify-jwt
+```
+
+### 2. Set Environment Variables
+
+Add your secrets to the deployed function:
+
+```bash
+supabase secrets set \
+  MCP_ACCESS_KEY="your-access-key" \
+  OPENROUTER_API_KEY="your-openrouter-key"
+```
+
+Optional multi-provider fallback (for metadata classification resilience):
+
+```bash
+supabase secrets set \
+  OPENAI_API_KEY="your-openai-key" \
+  ANTHROPIC_API_KEY="your-anthropic-key"
+```
+
+### 3. Add as a Remote MCP Connector
+
+In Claude Desktop (or any MCP-compatible client), add a new remote connector:
+
+- **Name:** `Open Brain Enhanced`
+- **URL:** `https://<your-project-ref>.supabase.co/functions/v1/enhanced-mcp`
+- **Header:** `x-brain-key: <your-mcp-access-key>`
+
+You can also pass the key as a query parameter: `?key=<your-mcp-access-key>`.
+
+### 4. Test Core Tools
+
+Verify the enhanced server is working by testing these tools in your AI client:
+
+1. **`capture_thought`** — Save a test thought: "Testing the enhanced MCP server setup"
+2. **`search_thoughts`** — Search for "testing" to find the thought you just captured
+3. **`thought_stats`** — View your brain's type and topic distribution
+4. **`list_thoughts`** — Browse recent thoughts with filters
+
+### 5. Enable Schema-Backed Tools (Optional)
+
+If you have installed optional schemas, these tools activate automatically:
+
+| Tool | Required Schema | What It Does |
+|------|----------------|--------------|
+| `ops_capture_status` | `schemas/smart-ingest` | Ingestion job health monitoring |
+| `graph_search` | `schemas/knowledge-graph` | Search entities by name or type |
+| `entity_detail` | `schemas/knowledge-graph` | Full entity profile with connections |
+| `ops_source_monitor` | Ops monitoring views | Per-source ingestion monitoring |
+
+If a required schema is not installed, the tool returns a clear message explaining which schema to install.
+
+## Expected Outcome
+
+After completing the steps above, you should have 14 tools available in your AI client under the "Open Brain Enhanced" connector. Running `capture_thought` should save a thought with automatic type classification, topic extraction, and sensitivity detection. Running `search_thoughts` should return results with similarity scores. Running `thought_stats` should show your brain's statistics using server-side aggregation.
+
+If you also have the original `server/` connector active, you will temporarily see both tool sets. Once you have verified the enhanced server works, you can disable the original connector to reduce tool count.
+
+## Tool Reference
+
+| # | Tool | Description | Schema Required |
+|---|------|-------------|-----------------|
+| 1 | `search_thoughts` | Semantic vector or full-text search with date and metadata filters | Enhanced Thoughts |
+| 2 | `list_thoughts` | Paginated browsing with type, source, date filters and sorting | Enhanced Thoughts |
+| 3 | `get_thought` | Fetch a single thought by ID with full metadata | Enhanced Thoughts |
+| 4 | `update_thought` | Update content with automatic re-embedding and re-classification | Enhanced Thoughts |
+| 5 | `delete_thought` | Permanently delete a thought by ID | Enhanced Thoughts |
+| 6 | `capture_thought` | Capture with dedup, sensitivity detection, and LLM classification | Enhanced Thoughts |
+| 7 | `thought_stats` | Type and topic statistics via server-side aggregation | Enhanced Thoughts |
+| 8 | `search_thoughts_text` | Direct full-text search (faster for exact phrase matching) | Enhanced Thoughts |
+| 9 | `count_thoughts` | Fast filtered count without returning content | Enhanced Thoughts |
+| 10 | `related_thoughts` | Find thoughts connected by shared topics or people | Enhanced Thoughts |
+| 11 | `ops_capture_status` | Ingestion health: job status, error rates, recent failures | Smart Ingest |
+| 12 | `graph_search` | Search knowledge graph entities with thought counts | Knowledge Graph |
+| 13 | `entity_detail` | Full entity profile: aliases, linked thoughts, relationship edges | Knowledge Graph |
+| 14 | `ops_source_monitor` | Per-source ingestion volume, errors, and failure samples | Ops Views |
+
+## Troubleshooting
+
+**Issue: "Invalid or missing access key" error**
+Solution: Ensure your `MCP_ACCESS_KEY` secret is set in Supabase and matches the key in your connector configuration. The key can be passed via the `x-brain-key` header or `?key=` query parameter.
+
+**Issue: "No embedding API key configured" error**
+Solution: At least one of `OPENROUTER_API_KEY` or `OPENAI_API_KEY` must be set. OpenRouter is the default and recommended provider for OB1.
+
+**Issue: Schema-backed tools return "install required schema" messages**
+Solution: This is expected behavior. These tools gracefully degrade when their backing tables are not present. Install the referenced schema contribution and the tools will activate automatically.
+
+**Issue: "match_thoughts" or "brain_stats_aggregate" RPC not found**
+Solution: The Enhanced Thoughts schema (`schemas/enhanced-thoughts`) must be applied before deploying this server. It adds the required RPCs and columns.
+
+**Issue: Metadata classification returns fallback results**
+Solution: Check that your LLM provider API key is valid and has sufficient quota. The server tries OpenRouter first, then falls back to OpenAI and Anthropic if configured. If all providers fail, it uses safe defaults.
+
+## Tool Surface Area
+
+This integration adds up to 14 tools to your AI's context. If you are managing multiple connectors, review the [MCP Tool Audit & Optimization Guide](../../docs/05-tool-audit.md) for strategies on keeping your tool count manageable as your Open Brain grows.