{
  "markdown": "# Smart Connections MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)\n\nA security-first MCP server for Smart Connections. Read-only. Path-validated. Auditable.\n\nExposes [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) embeddings to Claude Code and other [MCP](https://modelcontextprotocol.io/) clients for semantic search of your Obsidian vault.\n\n## Why This Exists\n\nWe needed semantic search of our Obsidian vault from Claude Code. Existing options have problems:\n\n- **No path validation** - User input passed directly to file operations\n- **Write access** - Some expose mutation tools we don't need\n- **Heavy dependencies** - PyTorch/transformers for what's essentially vector math\n\nThis implementation:\n- **Minimal dependencies** - MCP SDK + Transformers.js (for text search)\n- **Fail-closed security** - path validation with realpath, symlink detection\n- **Auditable** - small TypeScript codebase you can actually read\n\n## Features\n\n- **Text search** - query with plain text, not just note paths\n- **Semantic search** using Smart Connections embeddings\n- **Local inference** - uses Transformers.js (same model as Smart Connections)\n- **Read-only** - no write operations, no shell execution\n- **Secure** - strict path validation, bounded responses\n- **Offline** - works without Obsidian running\n\n## Security Model\n\n| Property | Guarantee |\n|----------|-----------|\n| Path confinement | All file access validated against vault root |\n| No traversal | `../` and symlink attacks blocked |\n| Read-only | No write operations exposed |\n| Bounded responses | Capped results (50), content length (10KB) |\n| Fail closed | Errors deny access, never bypass |\n| Audit logging | Security events logged with context |\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+\n- Obsidian with [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) plugin installed\n- Embeddings built (open vault in Obsidian, let Smart Connections index)\n\n### Setup\n\n```bash\ngit clone https://github.com/gogogadgetbytes/smart-connections-mcp\ncd smart-connections-mcp\nnpm install\nnpm run build\n```\n\n### Configure Claude Code\n\nAdd to your Claude Code config:\n\n```bash\nclaude mcp add smart-connections \\\n  -e VAULT_PATH=\"/path/to/your/obsidian/vault\" \\\n  -- node /path/to/smart-connections-mcp/dist/index.js\n```\n\nOr manually add to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"smart-connections\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/smart-connections-mcp/dist/index.js\"],\n      \"env\": {\n        \"VAULT_PATH\": \"/path/to/your/obsidian/vault\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code to load the server.\n\n## Usage\n\nOnce configured, Claude Code can use these tools:\n\n### Search by Text\n\n```\n\"Search my vault for notes about backup strategies\"\n→ Uses search_by_text tool\n```\n\n### Search Similar Notes\n\n```\n\"Find notes similar to Topics/Claude_Code.md\"\n→ Uses search_similar tool\n```\n\n### Get Note Content\n\n```\n\"Show me the content of Topics/Obsidian.md\"\n→ Uses get_note tool\n```\n\n### List Indexed Notes\n\n```\n\"What notes are indexed in my vault?\"\n→ Uses list_indexed tool\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_by_text` | Search using freeform text (computes embedding locally) |\n| `search_similar` | Find notes semantically similar to a given note |\n| `search_by_embedding` | Search using a raw embedding vector |\n| `get_note` | Get content of a specific note (path validated) |\n| `get_model_info` | Get embedding model configuration |\n| `list_indexed` | List all indexed notes |\n\n## Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `VAULT_PATH` | Yes | Absolute path to Obsidian vault |\n\n## Limitations\n\n- **Single vault** - Configure one vault per MCP server instance\n- **Index from Smart Connections** - Note embeddings come from the plugin; text queries are embedded locally\n- **No write access** - By design; use Obsidian for edits\n- **First run downloads model** - ~50MB model cached in `~/.cache/huggingface/`\n\n## Development\n\n```bash\n# Build\nnpm run build\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Security-focused PRs welcome.\n\n## Security\n\nTo report security vulnerabilities, please email gogogadgetcode@proton.me. Do not open public issues for security concerns.\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n\n## Credits\n\n- [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) by Brian Petro\n- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic\n",
  "bytes": 4742,
  "sha": "d02caf65d7da1d0bb58bf3a82938ebbc0bb0c2d2261f88c83637aa88f4fb54cb",
  "repo_slug": "gogogadgetbytes/smart-connections-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gogogadgetbytes_smart_connecti_2d76e6a7/readme"
}