smart-connections

Smart Connections MCP Server

一个以安全为首要考量的 Smart Connections MCP 服务。只读。路径经过验证。可审计。

将 Smart Connections 的嵌入向量提供给 Claude Code 和其他 MCP 客户端，用于对你的 Obsidian 知识库进行语义搜索。

为什么要开发这个项目

我们需要通过 Claude Code 对 Obsidian 知识库进行语义搜索。现有方案存在一些问题：

• 没有路径验证 - 用户输入被直接传递给文件操作
• 拥有写入权限 - 有些方案会提供我们不需要的修改工具
• 依赖项庞大 - 对于本质上只是向量运算的功能，却依赖 PyTorch/transformers

本实现具有以下特点：

• 依赖项精简 - MCP SDK + Transformers.js（用于文本搜索）
• 安全机制默认拒绝访问 - 使用 realpath 验证路径并检测符号链接
• 可审计 - 精简的 TypeScript 代码库，便于实际阅读

功能

• 文本搜索 - 使用纯文本查询，而不仅限于笔记路径
• 语义搜索，使用 Smart Connections 嵌入向量
• 本地推理 - 使用 Transformers.js（与 Smart Connections 使用相同的模型）
• 只读 - 不执行写入操作或 shell 命令
• 安全 - 严格验证路径，并限制响应大小
• 离线可用 - 无需运行 Obsidian

安全模型

属性	保证
路径限制	所有文件访问都针对知识库根目录进行验证
防止路径遍历	阻止 ../ 和符号链接攻击
只读	不提供写入操作
限制响应大小	限制结果数量（50 条）和内容长度（10KB）
默认拒绝访问	出错时拒绝访问，绝不绕过验证
审计日志	记录带有上下文信息的安全事件

安装

前置条件

• Node.js 18+
• 已安装 Smart Connections 插件的 Obsidian
• 已生成嵌入向量（在 Obsidian 中打开知识库，并等待 Smart Connections 完成索引）

设置

git clone https://github.com/gogogadgetbytes/smart-connections-mcp
cd smart-connections-mcp
npm install
npm run build

配置 Claude Code

将以下内容添加到 Claude Code 配置中：

claude mcp add smart-connections \
  -e VAULT_PATH="/path/to/your/obsidian/vault" \
  -- node /path/to/smart-connections-mcp/dist/index.js

或者手动添加到 ~/.claude.json：

{
  "mcpServers": {
    "smart-connections": {
      "command": "node",
      "args": ["/path/to/smart-connections-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

重启 Claude Code 以加载该服务。

用法

配置完成后，Claude Code 可以使用以下工具：

按文本搜索

"Search my vault for notes about backup strategies"
→ Uses search_by_text tool

搜索相似笔记

"Find notes similar to Topics/Claude_Code.md"
→ Uses search_similar tool

获取笔记内容

"Show me the content of Topics/Obsidian.md"
→ Uses get_note tool

列出已索引笔记

"What notes are indexed in my vault?"
→ Uses list_indexed tool

工具

工具	描述
search_by_text	使用自由文本进行搜索（在本地计算嵌入向量）
search_similar	查找与指定笔记在语义上相似的笔记
search_by_embedding	使用原始嵌入向量进行搜索
get_note	获取指定笔记的内容（会验证路径）
get_model_info	获取嵌入模型配置
list_indexed	列出所有已索引的笔记

配置

变量	必填	描述
VAULT_PATH	是	Obsidian 知识库的绝对路径

局限性

• 单个知识库 - 每个 MCP 服务实例只能配置一个知识库
• 索引来自 Smart Connections - 笔记嵌入向量由插件生成；文本查询则在本地生成嵌入向量
• 无写入权限 - 这是有意设计的；请使用 Obsidian 编辑
• 首次运行时下载模型 - 约 50MB 的模型会缓存在 ~/.cache/huggingface/

开发

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

参与贡献

请参阅 CONTRIBUTING.md。欢迎提交以安全为重点的 PR。

安全

如需报告安全漏洞，请发送邮件至 [email protected]。请勿公开提交安全问题。

许可证

MIT - 参见 LICENSE

致谢

• Brian Petro 开发的 Smart Connections
• Anthropic 提供的 Model Context Protocol