Smart Connections CLI & MCP Server

Command-line tool and MCP (Model Context Protocol) server for Smart Connections - find semantic connections in your Obsidian vaults.

Features

• 🔍 Find Connections - Discover notes semantically similar to a specific note

• 🔎 Semantic Search - Perform text-based searches across your vault

• 📊 Stats - View embedding statistics and vault coverage

• 📤 Multiple Outputs - Plain text or JSON format

• 🚀 Standalone - Works without Obsidian running

• 🤖 MCP Server - Model Context Protocol server for AI agent integration

Requirements

• Node.js >= 18.0.0

• Smart Connections plugin installed and vault indexed in Obsidian

Installation

CLI Installation

# Install globally
npm install -g @yejianye/smart-connections-mcp

After installing globally, you can use the smart-cli command:

export OBSIDIAN_VAULT=/path/to/your/vault
smart-cli connection "path/to/note.md"
smart-cli lookup "AI Coding"
smart-cli stats

MCP Server Installation

Install the MCP server for AI agent integration (e.g., with Claude Desktop):

Option 1: Using Claude MCP CLI

claude mcp add ob-smart-connections -e OBSIDIAN_VAULT=/path/to/your/vault  @yejianye/smart-connections-mcp

Option 2: Manual Configuration

Add the following json to your MCP client config (for example, claude_desktop_config.json):

{
  "mcpServers": {
    "smart-connections": {
      "command": "npx",
      "args": ["-y", "@yejianye/smart-connections-mcp"],
      "env": {
        "OBSIDIAN_VAULT": "/path/to/your/vault"
      }
    }
  }
}

Usage

Set Vault Path

# Set via environment variable (recommended)
export OBSIDIAN_VAULT=/path/to/your/vault

# Or use --vault flag with each command
smart-cli --vault=/path/to/vault <command>

Find Connections

Find notes semantically similar to a specific note:

smart-cli connection "ML/Neural Networks.md"

# JSON output
smart-cli connection "Projects/Project A.md" --format=json

# Limit results
smart-cli connection "Daily/2024-01-15.md" --limit=5

Example Output:

Found 5 connection(s):

[0.85] Machine Learning Basics
[0.78] Deep Learning
[0.72] AI Applications
[0.68] Data Science
[0.65] Python Programming

View Statistics

Show vault embedding statistics:

smart-cli stats

# JSON output
smart-cli stats --format=json

Example Output:

Smart Connections Vault Statistics
===================================

Sources:
  Total entries: 1234
  Files: 1100
  Blocks: 134

Embeddings:
  With embeddings: 1200
  Without embeddings: 34
  Coverage: 97.2%

Model Info:
  Embedding model(s): TaylorAI/bge-micro-v2
  Vector dimension: 384
  Estimated size: 1.85 MB

Settings:
  Min characters: 200
  File exclusions: Untitled
  Folder exclusions: (none)
  Exclude blocks: false

Validate Data

Check Smart Connections data integrity:

smart-cli validate

Example Output:

Validating Smart Connections data...

✓ Vault path is valid
✓ Smart Connections data found
✓ Data file is valid JSON
✓ Plugin settings found
✓ All embeddings are valid
✓ No orphaned files detected

==================================================
Validation Summary
==================================================
Checks passed: 6
Issues: 0
Warnings: 0

✅ All checks passed!

Semantic Search

Perform text-based search across your vault:

smart-cli lookup "machine learning concepts"

# With options
smart-cli lookup "React hooks best practices" --limit=10 --skip-blocks

# JSON output
smart-cli lookup "project management" --format=json

MCP Tools

The MCP server provides the following tools for AI agents:

Available MCP Tools

connection Tool

Find notes semantically similar to a specified note.

{
  "name": "connection",
  "arguments": {
    "note_path": "projects/my-project.md",
    "limit": 10
  }
}

lookup Tool

Perform semantic search using query text.

{
  "name": "lookup",
  "arguments": {
    "query": "machine learning algorithms",
    "limit": 15
  }
}

stats Tool

Get vault embedding statistics.

{
  "name": "stats",
  "arguments": {}
}

validate Tool

Validate Smart Connections data integrity.

{
  "name": "validate",
  "arguments": {}
}

MCP Configuration

Configure vault access via:

• Environment Variable: OBSIDIAN_VAULT=/path/to/vault (set during installation)

• Tool Arguments: Pass vault_path parameter to each tool call

How It Works

The CLI and MCP server read embedding data generated by the Smart Connections Obsidian plugin:

1. Data Source: Reads .smart-env/smart_sources.json (single-file) or .smart-env/multi/ (multi-file AJSON) from your vault

2. Settings: Respects plugin configuration from .obsidian/plugins/smart-connections/data.json

3. Search Algorithm: Uses cosine similarity to rank connections

4. MCP Protocol: Exposes functionality through standard Model Context Protocol for AI agents

5. No Dependencies: Standalone tools - work without the full smart-* package ecosystem

Development

# Clone the repository
git clone https://github.com/smart-connections/cli.git
cd cli

# Install dependencies
npm install

# Run locally
npm start -- connection "path/to/note.md"

# Run MCP server
npm run mcp

# Run tests
npm test

Troubleshooting

"Smart sources data not found"

Make sure:

1. Smart Connections plugin is installed in Obsidian

2. You've opened the vault in Obsidian and let it index

3. Either .smart-env/smart_sources.json or .smart-env/multi/ directory exists in your vault

"Vault path not specified"

Either:

• Set OBSIDIAN_VAULT environment variable

• Use --vault flag: smart-cli --vault=/path/to/vault command

"Source not found or not embedded"

The note may:

• Not exist in the vault

• Be too short (less than min_chars setting)

• Be excluded by file/folder exclusion settings

• Not have been indexed yet

Run smart-cli validate to diagnose issues.

License

MIT

Links

• Smart Connections Plugin

• Smart Connections Website

• Report Issues