🚀 Obsidian语义MCP服务器
Obsidian语义MCP服务器是一个专为Obsidian设计的语义化、AI优化的MCP服务器,它将20种工具整合为5种智能操作,并提供上下文工作流提示。
🚀 快速开始
试用我们的新原生插件!
这个MCP服务器让我们在将AI与Obsidian集成方面积累了宝贵经验。我们运用这些见解创建了**Obsidian MCP插件**,它具备以下优势:
- 原生集成:直接在Obsidian内运行(无需外部依赖!)
- 性能更优:直接访问保险库,无需REST API开销
- 安装简便:像安装任何Obsidian插件一样简单 - 无需API密钥或外部服务器
- 功能增强:可完全访问Obsidian的内部API和搜索功能
- 可靠性更高:不再有连接问题或超时情况
👉 获取Obsidian MCP插件
前提条件
安装
npm install -g obsidian-semantic-mcp
或者直接使用npx(推荐):
npx obsidian-semantic-mcp
在npm上查看:https://www.npmjs.com/package/obsidian-semantic-mcp
快速上手
- 安装Obsidian插件:
- 打开Obsidian设置 → 社区插件
- 浏览并搜索“Local REST API”
- 安装Adam Coddington开发的本地REST API插件
- 启用该插件
- 在插件设置中,复制您的API密钥(配置时需要用到)
- 配置Claude桌面:
npx命令会自动用于Claude桌面配置。将以下内容添加到您的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
- 获取引导建议
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": "- [ ] 新任务"
}
}
大文档片段检索
系统在读取文件时会自动使用智能片段检索,在保持相关性的同时显著减少令牌消耗:
{
"operation": "vault",
"action": "read",
"params": {
"path": "large-document.md"
}
}
返回相关片段而非整个文件:
{
"result": {
"content": [
{
"id": "file:large-document.md:frag0",
"content": "最相关的部分...",
"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": "项目路线图时间表",
"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": "文件未找到: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')"
}
]
}
}
📦 安装指南
npm install -g obsidian-semantic-mcp
或者直接使用npx(推荐):
npx obsidian-semantic-mcp
查看npm页面:https://www.npmjs.com/package/obsidian-semantic-mcp
💻 使用示例
基础用法
{
"operation": "vault",
"action": "read",
"params": {
"path": "daily-notes/2024-01-15.md"
}
}
高级用法
{
"operation": "edit",
"action": "patch",
"params": {
"path": "projects/todo.md",
"operation": "append",
"targetType": "heading",
"target": "## In Progress",
"content": "- [ ] 新任务"
}
}
📚 详细文档
环境变量
服务器会自动从.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": "每日笔记::今日",
"content": "- 新增任务"
}
🔧 技术细节
架构
语义系统由以下部分组成:
- 语义路由器 (
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插件集成