使用说明
黑曜石锈MCP
用Rust构建的用于黑曜石知识库管理的高性能MCP（模型上下文协议）服务器。
特性
- 📂 文件树索引 -获取完整的保险库结构和标签概述
- 🔍 智能搜索 -通过标签、确切名称或模糊关键字匹配查询笔记
- 📝 笔记管理 -通过自动生成正面内容来读取、写入和删除笔记
- 🔄 添加或覆盖 -为现有文件选择附加模式（默认）或覆盖模式
- 📁 子目录支持 -在嵌套目录中组织笔记（例如。，
projects/easytier,journal/2026-03) - 🛡️ 输入验证 -目录白名单、文件名净化、路径遍历保护
- 🏷️ 标签系统 -用标签和别名组织笔记
- ⚡ 高性能 -采用Rust构建，速度和可靠性高
安装
cargo build --release
迁移（v0.3中断更改）
MCP表面暴露 仅 help 和 executeCommand.删除了传统的扁平工具：
| 旧工具 | v0.3替换 |
|---|---|
write_note_tips |
executeCommand → obsidian.guide |
query_note |
executeCommand → obsidian.search |
write_note |
executeCommand → obsidian.write |
read_note |
executeCommand → obsidian.read |
note_index_tree |
executeCommand → obsidian.index |
delete_note |
executeCommand → obsidian.delete |
用法（CLI模型--v0.3）
MCP服务器公开 只有两个工具 要保存客户端令牌，请执行以下操作：
| 工具 | 目的 |
|---|---|
help |
命令手册（简短目录或详细用法） |
executeCommand |
运行已注册 obsidian.* 命令 |
典型流程： help → obsidian.guide → obsidian.search → obsidian.write
help
{}
{ "topic": "obsidian.write", "detail": true }
executeCommand
{
"command": "obsidian.search",
"args": { "tags": ["docker"], "keyword": "nginx" }
}
{
"command": "obsidian.write",
"args": {
"directory": "tech",
"filename": "nginx-guide",
"tags": ["nginx"],
"aliases": ["Nginx Guide"],
"status": "active",
"content": "markdown body",
"append": true
}
}
已注册的命令(obsidian.*)
| 命令 | 描述 |
|---|---|
obsidian.guide |
保险库写作指南（首次写作前致电） |
obsidian.search |
按标签/关键字/确切名称搜索(include_index 可选） |
obsidian.write |
创建或附加注释(append 默认 true) |
obsidian.read |
按路径阅读笔记（高级） |
obsidian.index |
完整文件树+标签统计（高级） |
obsidian.delete |
删除注释（参见 help 随着 detail) |
看 docs/arch.md 对于建筑和 docs/todo.md 路线图。
配置
选项1：环境变量（推荐）
设置 OBSIDIAN_VAULT_ROOT 指向黑曜石保险库的环境变量：
# Linux/macOS
export OBSIDIAN_VAULT_ROOT="/path/to/your/vault"
# Windows (cmd)
set OBSIDIAN_VAULT_ROOT=D:\notes\Fromsko
# Windows (PowerShell)
$env:OBSIDIAN_VAULT_ROOT="D:\notes\Fromsko"
选项2：硬编码路径
编辑 VAULT_ROOT 恒常 src/config.rs:
pub const VAULT_ROOT: &str = r"D:\notes\Fromsko";
选项3:MCP客户端配置（建议用于MCP客户端）
直接在MCP客户端配置中配置保管库路径：
{
"fromsko-note": {
"command": "/path/to/obsidian-mcp",
"disabled": false,
"env": {
"OBSIDIAN_VAULT_ROOT": "/path/to/your/vault"
}
}
}
替换 /path/to/obsidian-mcp 使用编译二进制文件的实际路径，以及 /path/to/your/vault 与你的黑曜石拱顶路径。
备注：当将此MCP服务器与Claude Desktop、Cursor或其他MCP兼容工具等客户端一起使用时，这是推荐的方法。
配置
| 变量 | 描述 |
|---|---|
OBSIDIAN_VAULT_ROOT |
Vault根目录（默认 .) |
OBSIDIAN_CONFIG |
JSON配置文件的路径 |
OBSIDIAN_VALID_DIRS |
逗号分隔的顶级目录白名单 |
OBSIDIAN_VAULT_BACKEND |
local 或 cloud |
OBSIDIAN_CLOUD_URL |
云API基础URL（写入/删除时同步） |
看 docs/obsidian-mcp.example.json 和 docs/STRUCTURE.md.
有效目录
默认顶级目录（通过配置覆盖）：
注释可以组织在以下顶级目录中（支持任何深度的嵌套子目录）：
tech-技术说明ai-AI/ML相关说明projects-项目文件methods-方法和流程career-职业发展ideas-想法和头脑风暴cheatsheet-快速参考指南journal-日报
项目结构
看 docs/STRUCTURE.md 完整布局。摘要：
src/
config/ # AppConfig (env + JSON)
validation/ # Path/directory rules
vault/ # LocalVault + CloudVault
note/ # frontmatter, index, semantic search
service/ # ObsidianService
command/ # registry, help, dispatch
mcp/ # MCP: help + executeCommand
docs/
arch.md, STRUCTURE.md, write-note-tips.md
tests/
service_integration.rs, mcp_stdio.rs, registry.rs
测试
cargo test # unit + integration + MCP stdio
截图
代理集成
注释示例
许可证
麻省理工学院-见 许可证 文件以获取详细信息。
