Obsidian Semantic Mcp

笔记 TypeScript

🚀 Obsidian语义MCP服务器

Obsidian语义MCP服务器是一个针对Obsidian进行语义优化和AI优化的MCP服务器，它将20种工具整合为5种智能操作，并提供上下文工作流提示，能有效提升AI代理对Obsidian操作的理解和使用效率。

🚀 快速开始

尝试我们的新原生插件！

这个MCP服务器让我们在将AI与Obsidian集成方面积累了宝贵经验。我们运用这些见解创建了 Obsidian MCP插件，它具有以下优势：

原生集成：直接在Obsidian内运行（无需外部依赖！）
性能更优：直接访问保险库，无REST API开销
设置更易：像安装任何Obsidian插件一样简单 - 无需API密钥或外部服务器
功能增强：可完全访问Obsidian的内部API和搜索功能
可靠性提高：不再有连接问题或超时情况

👉 获取Obsidian MCP插件

前提条件

计算机上已安装 Obsidian
Obsidian保险库中已安装本地REST API 插件
已安装 Claude桌面版应用程序

安装

npm install -g obsidian-semantic-mcp

或者直接使用npx（推荐）：

npx obsidian-semantic-mcp

在npm上查看：https://www.npmjs.com/package/obsidian-semantic-mcp

快速上手

安装Obsidian插件：
- 打开Obsidian设置 → 社区插件
- 浏览并搜索 "本地REST API"
- 安装Adam Coddington开发的本地REST API 插件
- 启用该插件
- 在插件设置中，复制你的API密钥（配置时需要用到）

配置Claude桌面版：在Claude桌面版配置中会自动使用npx命令。将以下内容添加到Claude桌面版配置中（在macOS上，通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "obsidian-semantic-mcp"],
"env": {
"OBSIDIAN_API_KEY": "your-api-key-here",
"OBSIDIAN_API_URL": "https://127.0.0.1:27124",
"OBSIDIAN_VAULT_NAME": "your-vault-name"
}
}
}
}

✨ 主要特性

关键优势

简化界面：用5种语义操作取代21种以上的单个工具
上下文工作流：智能提示引导AI代理进行下一个合理操作
状态跟踪：基于令牌的系统可防止无效操作
错误恢复：操作失败时提供智能恢复提示
模糊匹配：强大的文本编辑功能，可处理微小差异
片段检索：自动从大文件中返回相关部分，以节省令牌

为何采用语义操作？

传统的MCP服务器提供了许多细粒度的工具（20多种），这可能会让AI代理不知所措，并导致工具选择效率低下。我们的语义方法具有以下特点：

根据意图将20种工具整合为5种语义操作
提供上下文工作流提示，引导下一步操作
使用令牌跟踪状态（受Petri网启发），防止不合理的建议
操作失败时提供恢复提示

5种语义操作

vault - 文件和文件夹操作
- 操作：list、read、create、update、delete、search、fragments
edit - 智能内容编辑
- 操作：window（模糊匹配）、append、patch、at_line、from_buffer
view - 内容查看和导航
- 操作：window（带上下文）、open_in_obsidian
workflow - 获取引导建议
- 操作：suggest
system - 系统操作
- 操作：info、commands、fetch_web
- 注意：fetch_web 用于获取网页内容并将其转换为markdown格式（仅使用 url 参数）

示例用法

无需在 get_vault_file、get_active_file、read_file_content 等操作中进行选择，你只需使用：

{
"operation": "vault",
"action": "read",
"params": {
"path": "daily-notes/2024-01-15.md"
}
}

响应中会包含智能工作流提示：

{
"result": { /* 文件内容 */ },
"workflow": {
"message": "读取文件：daily-notes/2024-01-15.md",
"suggested_next": [
{
"description": "编辑此文件",
"command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
"reason": "对内容进行更改"
},
{
"description": "跟随链接笔记",
"command": "vault(action='read', path='{linked_file}')",
"reason": "探索相关知识"
}
]
}
}

状态感知建议

系统会跟踪上下文令牌，以提供相关建议：

读取包含 [[链接]] 的文件后，建议跟随这些链接
编辑失败后，提供缓冲区恢复选项
搜索后，建议细化搜索或读取搜索结果

高级功能

内容缓冲

window 编辑操作在尝试编辑之前会自动缓冲新内容。如果编辑失败或你想对其进行细化，可以从缓冲区中检索：

{
"operation": "edit",
"action": "from_buffer",
"params": {
"path": "notes/meeting.md"
}
}

模糊窗口编辑

语义编辑器使用模糊匹配来查找和替换内容：

{
"operation": "edit",
"action": "window",
"params": {
"path": "daily/2024-01-15.md",
"oldText": "meting notes",  // 拼写错误会进行模糊匹配
"newText": "meeting notes",
"fuzzyThreshold": 0.8
}
}

智能PATCH操作

针对特定的文档结构进行操作：

{
"operation": "edit",
"action": "patch",
"params": {
"path": "projects/todo.md",
"operation": "append",
"targetType": "heading",
"target": "## In Progress",
"content": "- [ ] New task"
}
}

大文档的片段检索

系统在读取文件时会自动使用智能片段检索，在保持相关性的同时显著减少令牌消耗：

{
"operation": "vault",
"action": "read",
"params": {
"path": "large-document.md"
}
}

返回相关片段而非整个文件：

{
"result": {
"content": [
{
"id": "file:large-document.md:frag0",
"content": "Most relevant section...",
"score": 0.95,
"lineStart": 145,
"lineEnd": 167
}
],
"fragmentMetadata": {
"totalFragments": 5,
"strategy": "adaptive",
"originalContentLength": 135662
}
}
}

片段搜索策略：

adaptive - TF-IDF关键字匹配（短查询的默认策略）
proximity - 查找查询词相邻出现的片段
semantic - 将文档分割成有意义的部分

你可以在整个保险库中显式搜索片段：

{
"operation": "vault",
"action": "fragments",
"params": {
"query": "project roadmap timeline",
"maxFragments": 10,
"strategy": "proximity"
}
}

需要时，可使用以下方式检索完整文件：

{
"operation": "vault",
"action": "read",
"params": {
"path": "document.md",
"returnFullFile": true
}
}

工作流示例

每日笔记工作流

创建今日笔记 → 2. 添加模板 → 3. 链接昨日笔记

研究工作流

搜索主题 → 2. 读取结果 → 3. 创建综合笔记 → 4. 链接来源

重构工作流

查找所有提及 → 2. 更新链接 → 3. 重命名/合并笔记

配置

语义工作流提示在 src/config/workflows.json 中定义，可以根据你的工作流偏好进行自定义。

片段检索配置

片段检索系统在读取文件时会自动激活，以节省令牌。你可以控制此行为：

默认行为：读取文件时返回最多5个相关片段
完整文件访问：使用 returnFullFile: true 参数获取完整内容
策略选择：系统会根据查询长度自动选择，也可以手动指定：
- adaptive 用于关键字匹配（1 - 2个单词的查询）
- proximity 用于查找相关术语相邻出现的情况（3 - 5个单词的查询）
- semantic 用于概念性分块（较长的查询）

错误恢复

操作失败时，语义界面会提供智能恢复提示：

{
"error": {
"code": "FILE_NOT_FOUND",
"message": "File not found: daily/2024-01-15.md",
"recovery_hints": [
{
"description": "创建此文件",
"command": "vault(action='create', path='daily/2024-01-15.md')"
},
{
"description": "搜索类似文件",
"command": "vault(action='search', query='2024-01-15')"
}
]
}
}

🔧 技术细节

环境变量

如果存在 .env 文件，服务器会自动从该文件中加载环境变量。变量的设置优先级如下：

现有环境变量（优先级最高）
当前工作目录中的 .env 文件
服务器目录中的 .env 文件

必需变量：

OBSIDIAN_API_KEY - 来自本地REST API插件的API密钥

可选变量：

OBSIDIAN_API_URL - API URL（默认：https://localhost:27124）
- 支持HTTP（端口27123）和HTTPS（端口27124）
- HTTPS使用自签名证书，会自动被接受
OBSIDIAN_VAULT_NAME - 用于上下文的保险库名称

示例 .env 文件：

OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_VAULT_NAME=MyVault

PATCH操作

PATCH操作（patch_active_file 和 patch_vault_file）允许进行复杂的内容操作：

目标类型：
- heading - 使用 "Heading 1::Subheading" 等路径针对特定标题下的内容
- block - 针对特定的块引用
- frontmatter - 针对前置元数据字段
操作：
- append - 在目标之后添加内容
- prepend - 在目标之前添加内容
- replace - 替换目标内容

示例：在特定标题下追加内容：

{
"operation": "append",
"targetType": "heading",
"target": "Daily Notes::Today",
"content": "- New task added"
}

架构

语义系统由以下部分组成：

语义路由器 (src/semantic/router.ts) - 将操作路由到处理程序
状态令牌 (src/semantic/state-tokens.ts) - 跟踪上下文状态
工作流配置 (src/config/workflows.json) - 定义提示和建议
核心实用工具 (src/utils/) - 共享功能，如文件读取和模糊匹配

测试

项目包含了针对语义系统的全面Jest测试：

npm test                    # 运行所有测试
npm test semantic-router    # 测试路由逻辑
npm test semantic-tools     # 测试集成

📄 许可证

本项目采用MIT许可证。

已知问题

搜索功能：由于Obsidian本地REST API插件的API限制，在大型保险库中进行搜索操作时，搜索可能偶尔会超时。

贡献

欢迎贡献代码！感兴趣的领域包括：

在 workflows.json 中添加更多工作流模式
新增语义操作
增强状态跟踪功能
与Obsidian插件集成

0 条评论
分类：笔记