黑曜石语义MCP服务器
🎉 激动人心的消息！ 我们从这个项目中学到了一切，并创造了更好的东西！看看新的 黑曜石MCP插件 -一个直接在vault中运行的原生黑曜石插件，具有改进的性能、简化的设置和增强的功能。我们鼓励您尝试一下！
面向Obsidian的语义、人工智能优化的MCP服务器，将20个工具整合为5个智能操作，并带有上下文工作流提示。
______________________________________________________________________
🚀 试试我们的新原生插件！
这个MCP服务器教会了我们关于AI与黑曜石集成的宝贵经验。我们应用这些见解来创建 黑曜石MCP插件，它提供：
- 本机集成：直接在黑曜石内部运行（无外部依赖！）
- 更好的性能：在没有REST API开销的情况下直接访问保险库
- 设置更简单：像任何黑社会插件一样安装-没有API密钥或外部服务器
- 增强功能：完全访问黑曜石的内部API和搜索功能
- 提高了可靠性：不再有连接问题或超时
______________________________________________________________________
先决条件
- 黑曜石 已安装在您的计算机上
- 本地REST API 安装在黑曜石保险库中的插件
- 克劳德桌面版 应用
安装
npm install -g obsidian-semantic-mcp或者直接与npx一起使用（推荐）：
npx obsidian-semantic-mcp在npm上查看：https://www.npmjs.com/package/obsidian-semantic-mcp
快速开始
- 安装黑曜石插件：
- 打开黑曜石设置→ 社区插件 - 浏览并搜索“本地REST API” - 安装 本地REST API Adam Coddington的插件 - 启用插件 - 在插件设置中，复制您的API密钥（您需要此密钥进行配置）
- 配置Claude桌面：
npx命令在Claude Desktop配置中自动使用。将此添加到您的Claude Desktop配置中（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"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"
}
}
}
}特性
该服务器将传统的MCP工具整合到一个AI优化的语义界面中，使AI代理更容易有效地理解和使用黑曜石操作。
关键利益
- 简化的界面：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": { /* file content */ },
"workflow": {
"message": "Read file: daily-notes/2024-01-15.md",
"suggested_next": [
{
"description": "Edit this file",
"command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
"reason": "Make changes to content"
},
{
"description": "Follow linked notes",
"command": "vault(action='read', path='{linked_file}')",
"reason": "Explore connected knowledge"
}
]
}
}国家意识建议
系统跟踪上下文令牌以提供相关建议：
- 读取文件后
[[links]]，它建议遵循它们 - 编辑失败后，它提供缓冲区恢复选项
- 搜索后，它建议优化或阅读结果
高级功能
内容缓冲
这 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", // typo will be fuzzy matched
"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
}
}
}片段搜索策略：
- 自适应的 -TF-IDF关键字匹配（默认用于短查询）
- 接近 -查找查询词紧密排列的片段
- 语义 -将文档分为有意义的部分
您可以在vault中明确搜索碎片：
{
"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": "Create this file",
"command": "vault(action='create', path='daily/2024-01-15.md')"
},
{
"description": "Search for similar files",
"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=MyVaultPATCH操作
PATCH操作(patch_active_file 和 patch_vault_file)允许复杂的内容操作：
- 目标类型：
- heading：使用“标题1:：副标题”等路径在特定标题下定位内容 - block：目标特定块引用 - frontmatter：目标前沿领域
- 操作：
- append：在目标后添加内容 - prepend：在目标之前添加内容 - replace：替换目标内容
示例：在特定标题下附加内容：
{
"operation": "append",
"targetType": "heading",
"target": "Daily Notes::Today",
"content": "- New task added"
}发展
# Clone and install
git clone https://github.com/aaronsb/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
npm install
# Development mode
npm run dev
# Testing
npm test # Run all tests
npm run test:coverage # With coverage report
# Build
npm run build # Build the server
npm run build:full # Test + Build
# Start
npm start # Start the server建筑
语义系统由以下部分组成：
- 语义路由器 (
src/semantic/router.ts)-将操作发送给处理人员 - 州代币 (
src/semantic/state-tokens.ts)-跟踪上下文状态 - 工作流配置 (
src/config/workflows.json)-定义提示和建议 - 核心工具 (
src/utils/)-共享功能，如文件读取和模糊匹配
测试
该项目包括语义系统的全面Jest测试：
npm test # Run all tests
npm test semantic-router # Test routing logic
npm test semantic-tools # Test integration已知问题
- 搜索功能：由于Obsidian本地REST API插件中的API限制，搜索操作可能偶尔会在大型保管库上超时。
贡献
欢迎投稿！感兴趣的领域：
- 中的其他工作流模式
workflows.json - 新的语义操作
- 增强状态跟踪
- 与黑曜石插件集成
许可证
麻省理工学院