Smart Connections MCP Server

智能连接MCP服务器

通过模型上下文协议（MCP）将您的黑曜石智能连接矢量数据库暴露给克劳德代码。

这有什么作用

而不是使用基于文本的 Grep，Claude Code现在可以执行 语义搜索 穿过你的保险库：

• 语义研究：按含义而非关键字查找注释
• find_related：获取相关笔记（如智能连接侧栏）
• get_text_blocks：获取RAG查询的最佳上下文

建筑

Smart Connections Plugin
    ↓ (creates)
.smart-env/multi/*.ajson
    ↓ (reads)
This MCP Server
    ↓ (exposes via)
MCP Protocol
    ↓ (consumed by)
Claude Code

安装

快速安装（推荐）

cd ~/smart-connections-mcp
./install.sh

脚本将：

• ✅ 安装UV包管理器（如果需要）
• ✅ 创建虚拟环境
• ✅ 安装所有依赖项
• ✅ 自动检测您的黑曜石保险库
• ✅ 配置 ~/.mcp.json
• ✅ 验证安装

手动安装

Click to expand manual installation steps

1.安装UV

curl -LsSf https://astral.sh/uv/install.sh | sh

2.创建虚拟环境并安装依赖项

cd ~/smart-connections-mcp
uv venv
uv pip install -r requirements.txt

重要依赖关系：

• mcp>=1.0.0 -官方模型上下文协议SDK
• sentence-transformers>=2.2.0 -用于语义搜索
• numpy=2.0.0 和 transformers>=4.30.0 -ML依赖关系

3.配置克劳德代码

增添 ~/.mcp.json:

{
  "mcpServers": {
    "smart-connections": {
      "command": "/Users/YOUR_USERNAME/smart-connections-mcp/.venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/smart-connections-mcp/server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

注： 使用虚拟环境Python，而不是系统Python！

4.验证安装

claude mcp list

预期产量：

smart-connections: .venv/bin/python server.py - ✓ Connected

迁移到新机器

看 部署.md 获取详细的迁移指南。

快速迁移：

# On new machine
git clone https://github.com/dan6684/smart-connections-mcp.git ~/smart-connections-mcp
cd ~/smart-connections-mcp
./install.sh

重要提示： 将此MCP服务器保存在 独立存储库 从你的黑曜石金库。看 部署.md 了解基本原理和最佳实践。

故障排除

如果您看到超时问题，请参阅 故障排除.md.

使用示例

语义搜索

老路（Grep）：

Grep pattern: "self-compassion"
→ Only finds notes with exact word "self-compassion"

新方法（语义搜索）：

semantic_search(query: "recognizing self-worth and releasing shame")
→ Finds: Ann Shulgin note ("I am a treasure")
        BM playa note ("I am beautiful, playa saved me")
        Therapy notes (related concepts)

查找相关注释

如智能连接侧栏：

find_related(file_path: "DailyNotes/2025-10-25.md")
→ Returns top 10 semantically similar notes

获取RAG的上下文

为复杂查询构建上下文：

get_context_blocks(query: "transformation through embodiment")
→ Returns actual text blocks most relevant to query
→ Claude can use these for grounded answers

运作原理

1. 读取现有嵌入 从 .smart-env/multi/*.ajson
2. 无需重新索引 -使用智能连接的工作
3. 相同型号 （BGE-micro-v2）用于查询编码
4. 余弦相似度 对结果进行排名
5. 返回JSON 具有文件路径、相似性得分、元数据

提供的工具

semantic_search

semantic_search(
    query: str,           # Natural language query
    limit: int = 10,      # Max results
    min_similarity: float = 0.3  # Threshold
)

退货：

{
  "query": "self-compassion",
  "results_count": 5,
  "results": [
    {
      "path": "DailyNotes/2025-08-29.md",
      "similarity": 0.87,
      "key": "smart_sources:DailyNotes/2025-08-29.md",
      "metadata": {"tags": ["#Dream", "#grateful"]}
    }
  ]
}

find_related

find_related(
    file_path: str,      # e.g., "DailyNotes/2025-10-25.md"
    limit: int = 10
)

get_context_blocks

get_context_blocks(
    query: str,
    max_blocks: int = 5
)

返回RAG的实际文本内容（不仅仅是路径）。

演出

• 初始载荷： 约2-3秒（加载3249个嵌入件）
• 查询时间： ~100-200ms（所有嵌入的余弦相似性）
• 内存： ~50MB（缓存嵌入）

故障排除

看 故障排除.md 详细的调试指南。

常见问题

服务器超时 claude mcp list

症状： 连接挂起，30+秒后无响应

修复：

1. 确保使用虚拟环境Python（而不是系统Python）
2. 验证NumPy版本是否小于2.0.0： uv pip list | grep numpy
3. 检查服务器是否手动启动：

   OBSIDIAN_VAULT_PATH="/path/to/vault" .venv/bin/python server.py

导入错误

错误： ImportError: numpy.core.multiarray failed to import

修复： 使用NumPy 1.x重新安装：

uv pip install "numpy<2.0.0" --force-reinstall

未返回任何结果

• 检查 .smart-env/multi/ 有.ajson文件
• 验证Obsidian中是否启用了智能连接
• 降低 min_similarity 阈值（尝试0.2而不是0.3）

错误的结果

• 智能连接可能需要重新索引
• 检查嵌入模型匹配（BGE-micro-v2）
• 重新启动服务器以重新加载嵌入

发展

更新嵌入：

• 智能连接自动更新 .smart-env/
• MCP服务器启动时读取（重新启动以刷新）
• 未来：添加文件监视器以自动重新加载

添加新工具： 编辑 handle_request() 在 server.py

许可证

MIT-免费用于个人PKM工作流程