smart-connections-mcp

🚀 智能连接MCP服务器

这是一个以安全为首要考量的智能连接MCP服务器，具备只读、路径验证和可审计等特性，能够将 智能连接 的嵌入向量暴露给Claude Code和其他 MCP 客户端，以实现对Obsidian知识库的语义搜索。

🚀 快速开始

本项目旨在为Claude Code提供对Obsidian知识库的语义搜索功能。现有的相关方案存在一些问题，例如缺乏路径验证、存在不必要的写访问以及依赖过于繁重等。而本实现方案具有依赖少、安全可靠、可审计等优点。

✨ 主要特性

• 文本搜索：支持使用纯文本进行查询，而非仅局限于笔记路径。
• 语义搜索：利用智能连接的嵌入向量实现语义搜索。
• 本地推理：使用Transformers.js（与智能连接使用相同的模型）进行本地推理。
• 只读模式：不进行写操作，不执行shell命令。
• 安全可靠：严格的路径验证，响应结果有边界限制。
• 离线使用：无需运行Obsidian即可工作。

🔒 安全模型

| 属性 | 保障 | |------|------| | 路径限制 | 所有文件访问都针对知识库根目录进行验证 | | 无遍历攻击 | 阻止 ../ 和符号链接攻击 | | 只读访问 | 不暴露写操作 | | 响应限制 | 结果数量上限为50，内容长度上限为10KB | | 故障安全 | 错误时拒绝访问，不会绕过安全机制 | | 审计日志 | 记录带有上下文的安全事件 |

📦 安装指南

前提条件

• Node.js 18及以上版本
• 安装了 智能连接 插件的Obsidian
• 已构建嵌入向量（在Obsidian中打开知识库，让智能连接进行索引）

安装步骤

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"
→ 使用 search_by_text 工具

搜索相似笔记

"Find notes similar to Topics/Claude_Code.md"
→ 使用 search_similar 工具

获取笔记内容

"Show me the content of Topics/Obsidian.md"
→ 使用 get_note 工具

列出已索引的笔记

"What notes are indexed in my vault?"
→ 使用 list_indexed 工具

🛠️ 工具列表

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

⚙️ 配置说明

| 变量 | 是否必需 | 描述 | |------|----------|------| | VAULT_PATH | 是 | Obsidian知识库的绝对路径 |

⚠️ 局限性

• 单知识库：每个MCP服务器实例只能配置一个知识库。
• 依赖智能连接索引：笔记嵌入向量来自插件，文本查询在本地进行嵌入处理。
• 无写访问：设计上不提供写访问，编辑操作请使用Obsidian。
• 首次运行下载模型：约50MB的模型会缓存到 ~/.cache/huggingface/。

🛠️ 开发指南

# 构建项目
npm run build

# 使用MCP检查器进行测试
npx @modelcontextprotocol/inspector node dist/index.js

🤝 贡献指南

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

🔐 安全问题

若要报告安全漏洞，请发送邮件至 gogogadgetcode@proton.me。请勿公开提出安全相关问题。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

🙏 鸣谢

• 智能连接 由Brian Petro开发
• 模型上下文协议 由Anthropic开发