# 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

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

After installing globally, you can use the `smart-cli` command:
```bash
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**
```bash
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`):
```json
{
  "mcpServers": {
    "smart-connections": {
      "command": "npx",
      "args": ["-y", "@yejianye/smart-connections-mcp"],
      "env": {
        "OBSIDIAN_VAULT": "/path/to/your/vault"
      }
    }
  }
}
```

## Usage

### Set Vault Path

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

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

#### `lookup` Tool
Perform semantic search using query text.

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

#### `stats` Tool
Get vault embedding statistics.

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

#### `validate` Tool
Validate Smart Connections data integrity.

```javascript
{
  "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

```bash
# 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](https://github.com/brianpetro/obsidian-smart-connections)
- [Smart Connections Website](https://smartconnections.app)
- [Report Issues](https://github.com/yejianye/ob-smart-connections-mcp/issues)