优化黑曜石MCP

法文版本： README.fr.md 操作指南：操作.md 开发指南（FR）：操作.fr.md

用于黑曜石的MCP（模型上下文协议）服务器，具有共享的本地缓存、集成的任务工具和由智能连接支持的语义搜索。

太长，读不下去了

npm install
npm run build
node dist/stdio-proxy.js

建议用于Codex：将MCP配置指向 dist/stdio-proxy.js，不直接 dist/index.js.

先决条件

Node.js>=22.7.5
黑曜石桌面
插件：

- 本地REST API（REST工具需要）：https://github.com/coddingtonbear/obsidian-local-rest-api - 智能连接（语义搜索所需）：https://github.com/brianpetro/obsidian-smart-connections - 基础桥（REST）（需要 .base 工具，捆绑在这个仓库中） - 黑曜石任务插件（规范任务行为所需）

对于语义搜索，请确保您的vault具有 .smart-env 文件夹

安装

来源：

git clone https://github.com/optimikelabs/optimike-obsidian-mcp.git
cd optimike-obsidian-mcp
npm install
npm run build

运行推荐的本地MCP入口点：

node dist/stdio-proxy.js

为什么

将黑曜石连接到MCP代理（Codex、IDE等）
暴露黑曜石REST工具（读/写、前台、标签、搜索）
通过智能连接提供本地矢量搜索(.smart-env)
保留一个持久的本地后端，而不是在每次stdio运行时重新生成繁重的状态

亮点

完整的MCP工具集（注释、封面、标签、全局搜索等）
集成任务工具： list_all_tasks 和 query_tasks
局部语义搜索 smart_semantic_search
运行时可观察性工具： obsidian_runtime_status 和 obsidian_runtime_maintenance
只读降级模式 obsidian_read_note 和 obsidian_list_notes 当Obsidian REST关闭时
用于保管库内容、任务缓存和语义清单数据的共享SQLite存储
嵌入器无关：查询嵌入与vault模型对齐
Ollama/OpenAI支持（环境覆盖）；Xenova/Transfers被禁用，直到其易受攻击的ONNX/protobuf链可以安全地重新引入

架构（概述）

黑曜石 +插件（本地REST API、Bases Bridge、智能连接）
优化黑曜石MCP （此服务器）
MCP代理 （食品法典、IDE等）

服务器充当桥在代理和黑曜石之间，添加了一个“基础”层 .base 文件，并在本地持久化共享运行时状态，因此Codex可以在运行中保持快速稳定。

基础桥（REST）——为什么以及如何实现

Obsidian没有用于基础的本地API(.base).\ 这 基础桥（REST） 插件通过添加专用REST端点来填补空白。

Bases Bridge暴露的端点

官方前缀（推荐）：

GET /extensions/obsidian-bases-bridge/bases\

列出所有可用的基地。

GET /extensions/obsidian-bases-bridge/bases/:id/schema\

返回架构（属性、公式、视图）。

POST /extensions/obsidian-bases-bridge/bases/:id/query\

查询库（过滤器、排序、分页、求值）。

POST /extensions/obsidian-bases-bridge/bases/:id/upsert\

散装前体出现故障。

POST /extensions/obsidian-bases-bridge/bases\

创建/验证 .base 文件。

GET /extensions/obsidian-bases-bridge/bases/:id/config\

阅读基础YAML。

PUT /extensions/obsidian-bases-bridge/bases/:id/config\

更新基本YAML。

传统别名（MCP compat）：

GET /bases
GET /bases/:id/schema
POST /bases/:id/query
POST /bases/:id/upsert
POST /bases
GET /bases/:id/config
PUT /bases/:id/config

发动机/评估

当 evaluate: true，桥返回：

source: "engine"：自动缓存+公式计算（无桥视图）
source: "fallback"：如果发动机关闭，则进行部分盘上评估

MCP基础工具

此服务器公开“基础”MCP工具：

bases_list ：列表基
bases_get_schema ：获取架构
bases_query ：带筛选器/排序的分页查询
bases_upsert_rows ：批量前台更新
bases_get_config / bases_upsert_config ：读/写YAML
bases_create ：创建/验证a .base

最终运行时模型

该仓库支持两种本地运行时模式：

stdio proxy （推荐用于Codex）：一个轻量级的stdio进程，在需要时自动启动本地Streamable HTTP后端
http backend：拥有大量缓存/预热工作的实际长期后端进程

后端将vault内容保存到共享SQLite存储中，并在RAM中仅保留一个有界的热集。默认情况下，缓存位于：

/.obsidian/optimike-mcp/shared-cache.sqlite

同一数据库还存储：

file_cache 用于注释内容
task_file_cache 用于解析任务数据
semantic_manifest 和 semantic_vectors 用于语义元数据

如果 OBSIDIAN_VAULT 如果未设置，服务器将回退到从中推断出的父vault SMART_ENV_DIR，然后转到项目根目录。

有用的环境覆盖：

OBSIDIAN_SHARED_CACHE_DB_PATH 移动共享SQLite文件
OBSIDIAN_CONTENT_HOT_CACHE_LIMIT 调整内存中的有界热集
OBSIDIAN_CACHE_SOURCE=auto|filesystem|rest 选择缓存刷新源(auto 如果可用，则首选本地vault路径）
OBSIDIAN_CACHE_CONCURRENCY 绑定本地文件系统刷新工作
MCP_WRITE_MODE=readonly|guarded|full 加强服务器端写入安全(full 是默认值；集 guarded 或 readonly 明确地强化主机）
MCP_GUARDED_MAX_WRITE_CHARS 和 MCP_GUARDED_MAX_BATCH_OPERATIONS 调整保护模式限制

此运行时直接从主MCP公开Tasks表面，因此Codex不再需要第二个专用的 optimike-obsidian-tasks-mcp 使用此服务器时输入。热语义刷新现在首先从SQLite加载，而不是重新读取整个 .smart-env 每次的路。

有用的脚本：

npm run build
npm run start:proxy
npm run start:http

直接运行后端时的健康端点：

curl http://127.0.0.1:3010/healthz

延长健康/维护：

GET /healthz?integrity=1 添加SQLite完整性检查
MCP工具 obsidian_runtime_status 返回进程、缓存、语义和降级模式状态
MCP工具 obsidian_runtime_maintenance 支持：

- integrity_check - run_maintenance - refresh_vault_cache - refresh_semantic_cache - refresh_tasks_cache - refresh_all

运行时写入安全：

readonly 阻止除仅验证操作之外的所有写入工具
guarded 允许有界显式写入，并阻止破坏性操作，如删除、覆盖、取消设置frontmatter、广泛正则表达式替换所有和大批量
full 是默认设置，对受信任的本地环境保持不受限制的写入行为

代理上下文控件：

obsidian_list_notes 支持 responseMode="compact", limit，以及 cursor
obsidian_global_search 支持 responseMode="compact" 同时保持现有页面/页面大小分页
list_all_tasks 和 query_tasks 支持 responseMode="compact"|"detailed", responseLimit，以及 cursor
通过以下方式读取已识别的音符仍然保持完全的保真度 obsidian_read_note

典型检查：

curl http://127.0.0.1:3010/healthz
curl http://127.0.0.1:3010/healthz?integrity=1

最小Codex配置

在 ~/.codex/config.toml:

[mcp_servers.optimike-obsidian-mcp-stdio]
command = "node"
args = ["/path/to/optimike-obsidian-mcp/dist/stdio-proxy.js"]

tool_timeout_sec = 900

[mcp_servers.optimike-obsidian-mcp-stdio.env]
MCP_HTTP_HOST = "127.0.0.1"
MCP_HTTP_PORT = "3010"
MCP_PROXY_START_TIMEOUT_MS = "20000"
OBSIDIAN_VAULT = "/path/to/"

# Smart Connections
SMART_ENV_DIR = "/path/to//.smart-env"
ENABLE_QUERY_EMBEDDING = "true"

# Recommended: auto (do not set)
# QUERY_EMBEDDER = "auto"

# Obsidian REST (if Local REST API plugin is active)
OBSIDIAN_BASE_URL = "http://localhost:27123"
OBSIDIAN_API_KEY  = ""

# Startup behavior (optional, recommended for faster startup in WSL setups)
# OBSIDIAN_STARTUP_BLOCKING=false starts MCP immediately and runs health check in background.
OBSIDIAN_STARTUP_MAX_RETRIES = "2"
OBSIDIAN_STARTUP_RETRY_DELAY_MS = "1200"
OBSIDIAN_STARTUP_BLOCKING = "false"

# Shared cache tuning (optional)
# OBSIDIAN_SHARED_CACHE_DB_PATH = "/path/to//.obsidian/optimike-mcp/shared-cache.sqlite"
# OBSIDIAN_CONTENT_HOT_CACHE_LIMIT = "64"

笔记：

将此配置保留在本地 ~/.codex/config.toml （不要提交个人机器路径）。
在文档中使用逻辑占位符(/path/to/...)并且仅在本地配置中保留真实路径。
dist/index.js 仍然是后端入口点，但Codex应该指向 dist/stdio-proxy.js.

Obsidian本地REST API设置

本地REST API插件回购： https://github.com/coddingtonbear/obsidian-local-rest-api

黑曜石：

安装并启用 本地REST API
启用HTTP服务器
复制API密钥
集 OBSIDIAN_BASE_URL 和 OBSIDIAN_API_KEY 在您的MCP环境中

例子：

export OBSIDIAN_BASE_URL=http://127.0.0.1:27123
export OBSIDIAN_API_KEY=

安全

保持 OBSIDIAN_API_KEY 私人和地方。
请勿将Obsidian REST API公开到公共互联网。
保持 OBSIDIAN_API_KEY 和 OPENAI_API_KEY 在环境变量中，未提交的配置文件。

Windows上的WSL2+黑社会（本地REST API）

如果Obsidian在Windows上运行，而Codex在WSL2中运行：

127.0.0.1 从WSL点到WSL，而不是Windows
使用Windows主机IP（WSL网关） OBSIDIAN_BASE_URL

例子：

GW=$(ip route | awk '/default/ {print $3; exit}')
export OBSIDIAN_BASE_URL=http://$GW:27123

如果使用Windows端口代理，请相应地调整端口。

主MCP表面

主MCP现在包括：

注释工具：读取、列表、更新、搜索替换、标签、frontmatter
基础工具：列表、模式、查询、创建、追加配置、追加行
任务工具： list_all_tasks, query_tasks
语义工具： smart_semantic_search, smart_search, smart-search
运行时工具： obsidian_runtime_status, obsidian_runtime_maintenance

任务集成

主MCP现在直接拥有Tasks表面。

这意味着：

Codex不需要单独的 optimike-obsidian-tasks-mcp 进入更多
list_all_tasks 和 query_tasks 由此主服务器公开
解析后的任务数据被持久化 task_file_cache 在共享SQLite数据库内

任务支持的依赖关系：

黑曜石金库入口
共享缓存数据库
黑曜石任务插件配置文件位于：

/.obsidian/plugins/obsidian-tasks-plugin/data.json

它是如何工作的：

注释内容已编入索引 file_cache
任务解析重用该内容，而不是从头开始重新扫描vault
解析后的任务存储在 task_file_cache
list_all_tasks 和 query_tasks 重用该持久层

这为您提供了一个MCP表面、一个运行时和一个持久的本地数据路径。

必需且有用的黑曜石插件

根据您使用的MCP表面，需要：

本地REST API：MCP使用的黑眼圈API。
基础桥（REST）: .base 通过REST提供支持。
智能连接：矢量索引和 .smart-env 用于语义搜索。

语义搜索（智能连接）

工具： smart_semantic_search （别名： smart_search, smart-search).

例子：

{ "query": "publication X threads", "top_k": 10, "with_snippets": false }

服务器：

读取 .smart-env/multi/*.ajson
选择主导维度
使用与vault相同的模型嵌入查询
在SQLite中持久化语义清单，以实现更快的热刷新
通过加载快照和预热查询嵌入器在启动时预热语义搜索
回报 timings_ms, vector_count，以及 filtered_count 用于操作诊断

重要提示：

语义查询执行仍然需要一个可访问的查询嵌入器提供程序
如果金库是用Ollama嵌入物构建的，则无法访问的Ollama实例将产生明显的错误，而不是无声的挂起
集 SEMANTIC_SEARCH_PREWARM=false 禁用启动预热

这意味着：

语义元数据路径现在是持久和可观察的
最终查询仍然取决于请求时的实时嵌入提供者

提供者（可选覆盖）

Ollama（当地）

export QUERY_EMBEDDER=ollama
export QUERY_EMBEDDER_MODEL=snowflake-arctic-embed2
export OLLAMA_BASE_URL=http://127.0.0.1:11434

Xenova/变压器

本地Xenova提供程序目前已禁用，因为其ONNX/protobuf依赖链受到npm审计漏洞的影响。在本地使用Ollama，或在云模式下使用OpenAI。

OpenAI（云）

export QUERY_EMBEDDER=openai
export QUERY_EMBEDDER_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
# export OPENAI_EMBEDDING_DIMENSIONS=1024

MCP共享：可移植性

对于共享MCP设置，避免硬编码 OLLAMA_BASE_URL 在保险库内。保持自动模式，让每个用户通过env变量进行覆盖。

遗留任务报告

optimike-obsidian-tasks-mcp 仍然可以作为遗留的独立仓库存在，但Codex在使用此主服务器时不再需要它。主MCP现在是规范曲面。

WSL+Ollama窗户（推荐）

如果Obsidian也在Windows和Ollama上运行：

集 OLLAMA_HOST=0.0.0.0:11434 在Windows上
重启Ollama
WSL测试：

GW=$(ip route | awk '/default/ {print $3; exit}')
curl http://$GW:11434/api/tags

然后，如果需要：

export OLLAMA_BASE_URL=http://$GW:11434

学分

由...创建优化（迈克尔·阿胡安苏）
技术基础灵感来自 cyanheads/obsidian-mcp-server

许可证

看 LICENSE.

Optimike Obsidian MCP

快速接入

详细介绍