# Smart Connections MCP Server

A Model Context Protocol (MCP) server that provides semantic search and knowledge graph capabilities for Obsidian vaults using Smart Connections embeddings.

> **Fork note:** this is a fork maintained by [A Portland Career](https://aportlandcareer.com) for its second-brain pilot kit, based on the original [`smart-connections-mcp` by Daniel Glickman](https://github.com/msdanyg/smart-connections-mcp) (MIT). It adds true semantic `search_notes` (embeds the query with the vault's model instead of literal keyword matching); see "Query embedding" below. Original copyright and MIT license preserved in `LICENSE`.

## Overview

This MCP server allows Claude (and other MCP clients) to:
- **Search semantically** through your Obsidian notes using pre-computed embeddings
- **Find similar notes** based on content similarity
- **Build connection graphs** showing how notes are related
- **Query by embedding vectors** for advanced use cases
- **Access note content** with block-level granularity

## Features

### 🔍 Semantic Search
Uses the embeddings generated by Obsidian's Smart Connections plugin to perform fast, accurate semantic searches across your entire vault.

### 🕸️ Connection Graphs
Builds multi-level connection graphs showing how notes are related through semantic similarity, helping discover hidden relationships in your knowledge base.

### 📊 Vector Similarity
Direct access to embedding-based similarity calculations using cosine similarity on 384-dimensional vectors (TaylorAI/bge-micro-v2 model).

### 📝 Content Access
Retrieve full note content or specific sections/blocks with intelligent extraction based on Smart Connections block mappings.

## Installation

### Prerequisites

- Node.js 18 or higher
- An Obsidian vault with Smart Connections plugin installed and embeddings generated
- Claude Desktop (or another MCP client)

### Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/bookbran/smart-connections-mcp.git
   cd smart-connections-mcp
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the TypeScript project:**
   ```bash
   npm run build
   ```

4. **Configure Claude Desktop:**

   Edit your Claude Desktop configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   Add the following to the `mcpServers` section:

   ```json
   {
     "mcpServers": {
       "smart-connections": {
         "command": "node",
         "args": [
           "/ABSOLUTE/PATH/TO/smart-connections-mcp/dist/index.js"
         ],
         "env": {
           "SMART_VAULT_PATH": "/ABSOLUTE/PATH/TO/YOUR/OBSIDIAN/VAULT"
         }
       }
     }
   }
   ```

   **Important**: Replace the paths with your actual paths:
   - Update the `args` path to point to your built `index.js` file
   - Update `SMART_VAULT_PATH` to your Obsidian vault path

5. **Restart Claude Desktop**

   The MCP server will automatically start when Claude Desktop launches.

## Available Tools

### 1. `get_similar_notes`

Find notes semantically similar to a given note.

**Parameters:**
- `note_path` (string, required): Path to the note (e.g., "Note.md" or "Folder/Note.md")
- `threshold` (number, optional): Similarity threshold 0-1, default 0.5
- `limit` (number, optional): Maximum results, default 10

**Example:**
```typescript
{
  "note_path": "MyNote.md",
  "threshold": 0.7,
  "limit": 5
}
```

**Returns:**
```json
[
  {
    "path": "RelatedNote.md",
    "similarity": 0.85,
    "blocks": ["#Overview", "#Key Points", "#Details"]
  }
]
```

### 2. `get_connection_graph`

Build a multi-level connection graph showing how notes are semantically connected.

**Parameters:**
- `note_path` (string, required): Starting note path
- `depth` (number, optional): Graph depth (levels), default 2
- `threshold` (number, optional): Similarity threshold 0-1, default 0.6
- `max_per_level` (number, optional): Max connections per level, default 5

**Example:**
```typescript
{
  "note_path": "MyNote.md",
  "depth": 2,
  "threshold": 0.7
}
```

**Returns:**
```json
{
  "path": "MyNote.md",
  "depth": 0,
  "similarity": 1.0,
  "connections": [
    {
      "path": "RelatedNote.md",
      "depth": 1,
      "similarity": 0.82,
      "connections": [...]
    }
  ]
}
```

### 3. `search_notes`

Semantic search by text query. Embeds the query with the **same** model used for the vault's note embeddings (bge-micro-v2) and ranks notes by cosine similarity, so it matches by meaning rather than exact words. Falls back to a multi-term keyword search if the embedding model can't be loaded (e.g. fully offline before the model has ever been cached).

> **First-query note:** the query-embedding model is downloaded from the Hugging Face hub on the **first** `search_notes` call of a server session (needs network once, ~30s), then cached under `node_modules/@huggingface/transformers/.cache` so every later call is offline and fast (~4ms). See "Query embedding" under Technical Details.

**Parameters:**
- `query` (string, required): Search query text
- `limit` (number, optional): Maximum results, default 10
- `threshold` (number, optional): Similarity threshold 0-1, default 0.4 (typical relevant matches score ~0.4-0.75; lower to widen recall)

**Example:**
```typescript
{
  "query": "project management",
  "limit": 5
}
```

### 4. `get_embedding_neighbors`

Find nearest neighbors for a given embedding vector (advanced use).

**Parameters:**
- `embedding_vector` (number[], required): 384-dimensional vector
- `k` (number, optional): Number of neighbors, default 10
- `threshold` (number, optional): Similarity threshold 0-1, default 0.5

### 5. `get_note_content`

Retrieve full note content with optional block extraction.

**Parameters:**
- `note_path` (string, required): Path to the note
- `include_blocks` (string[], optional): Specific block headings to extract

**Example:**
```typescript
{
  "note_path": "MyNote.md",
  "include_blocks": ["#Introduction", "#Main Points"]
}
```

**Returns:**
```json
{
  "content": "# Full note content...",
  "blocks": {
    "#Introduction": "Content of this section...",
    "#Main Points": "Content of this section..."
  }
}
```

### 6. `get_stats`

Get statistics about the knowledge base.

**Parameters:** None

**Returns:**
```json
{
  "totalNotes": 137,
  "totalBlocks": 1842,
  "embeddingDimension": 384,
  "modelKey": "TaylorAI/bge-micro-v2"
}
```

## Usage Examples

Once configured, you can ask Claude to use these tools naturally:

- **"Find notes similar to my project planning document"**
- **"Show me a connection graph starting from my main research note"**
- **"Search my notes for information about [your topic]"**
- **"What's in my note about [topic]?"**
- **"Give me stats about my knowledge base"**

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Claude Desktop                         │
│                    (MCP Client)                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ MCP Protocol (stdio)
                          │
┌─────────────────────────▼───────────────────────────────────┐
│              Smart Connections MCP Server                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  index.ts (MCP Server + Tool Handlers)             │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  search-engine.ts (Semantic Search Logic)          │   │
│  │  - getSimilarNotes()                               │   │
│  │  - getConnectionGraph()                            │   │
│  │  - searchByQuery()                                 │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  smart-connections-loader.ts (Data Access)         │   │
│  │  - Load .smart-env/smart_env.json                  │   │
│  │  - Load .smart-env/multi/*.ajson embeddings        │   │
│  │  - Read note content from vault                    │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  embedding-utils.ts (Vector Math)                  │   │
│  │  - cosineSimilarity()                              │   │
│  │  - findNearestNeighbors()                          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ File System Access
                          │
┌─────────────────────────▼───────────────────────────────────┐
│            Obsidian Vault + .smart-env/                     │
│  - smart_env.json (config)                                  │
│  - multi/*.ajson (embeddings for 137 notes)                 │
│  - *.md (markdown note files)                               │
└─────────────────────────────────────────────────────────────┘
```

## Technical Details

### Embedding Model
- **Model**: TaylorAI/bge-micro-v2
- **Dimensions**: 384
- **Similarity Metric**: Cosine similarity

### Query embedding (`search_notes`)
`get_similar_notes` / `get_connection_graph` compare notes against each other using the vectors Smart Connections already stored, so they need no model at runtime. `search_notes` is different: it must turn an arbitrary text query into a vector to compare against those stored vectors. It does this with `@huggingface/transformers` (transformers.js), loading the **same** model the vault is configured for (read from `smart_env.json`, e.g. `TaylorAI/bge-micro-v2`) so the query and note vectors live in the same space.

- The model repo is tried in order: the vault's configured `model_key`, then `SC_EMBED_MODEL` (env override), then `TaylorAI/bge-micro-v2`, then `Xenova/bge-micro-v2`.
- ONNX weights download from the Hugging Face hub on first use and are cached under `node_modules/@huggingface/transformers/.cache`. First `search_notes` call: ~30s; subsequent calls: ~4ms, offline.
- If no model can be loaded (offline with an empty cache), `search_notes` transparently falls back to a multi-term keyword search so it still returns useful results.
- Override the model with the `SC_EMBED_MODEL` env var if your vault uses a different embedding model. It must be a bge-micro-v2-family model, or the query vectors won't match the stored note vectors.

### Data Format
The server reads from Obsidian's Smart Connections `.smart-env/` directory:
- `smart_env.json`: Configuration and model settings
- `multi/*.ajson`: Per-note embeddings and block mappings

### Performance
- **Load time**: ~2-5 seconds for 137 notes
- **Search**: Near-instant (<50ms) using pre-computed embeddings
- **Memory**: ~20-30MB for embeddings + note index

## Development

### Build
```bash
npm run build
```

### Watch Mode
```bash
npm run watch
```

### Run Locally
```bash
export SMART_VAULT_PATH="/path/to/your/vault"
npm run dev
```

### Project Structure
```
smart-connections-mcp/
├── src/
│   ├── index.ts                    # MCP server & tool handlers
│   ├── search-engine.ts            # Semantic search logic
│   ├── smart-connections-loader.ts # Data loading
│   ├── embedding-utils.ts          # Vector math utilities
│   └── types.ts                    # TypeScript type definitions
├── dist/                           # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

## Troubleshooting

### "Smart Connections directory not found"
- Ensure your vault has the Smart Connections plugin installed
- Verify embeddings have been generated (check `.smart-env/multi/` directory)
- Check that `SMART_VAULT_PATH` points to the correct vault

### "Configuration file not found"
- Run Smart Connections in Obsidian at least once to generate configuration
- Check for `.smart-env/smart_env.json` in your vault

### "No embeddings found for note"
- Some notes may not have embeddings if they're too short (< 200 chars)
- Re-run Smart Connections embedding generation in Obsidian

### Server not appearing in Claude Desktop
- Verify the configuration file syntax (JSON must be valid)
- Check the file paths are absolute paths, not relative
- Restart Claude Desktop completely
- Check Claude Desktop logs for error messages

## License

MIT

## Author

- Original: Daniel Glickman ([msdanyg/smart-connections-mcp](https://github.com/msdanyg/smart-connections-mcp))
- Fork maintained by: A Portland Career (semantic `search_notes` + pilot-kit integration)

## Acknowledgments

- Built for use with [Obsidian](https://obsidian.md/)
- Integrates with [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) plugin
- Uses [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic