黑曜石本地REST API MCP

Name: 黑曜石本地REST API MCP
Author: j-shelfwood

作者：j-shelfwood5 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

Obsidian Local REST API MCP 服务器

这是一个基于AI原生设计的MCP（模型上下文协议）服务器，通过本地REST API提供智能的任务导向工具，用于与Obsidian保险库进行交互。

🧠 AI原生设计理念

此MCP服务器按照AI原生原则进行了重新设计，而不是简单的API到工具映射。它不暴露低级别的CRUD操作，而是提供了高级别的任务导向工具，这些工具可以更有效地被LLMs推理。

转变前与转变后对比

旧方法（基于CRUD）	新方法（AI原生）	为什么更好
`list_files`（返回所有内容）	`list_directory(path, limit, offset)`	通过分页防止上下文溢出
`create_file` + `update_file`	`write_file(path, content, mode)`	单个工具处理创建/更新/追加
`create_note` + `update_note`	`create_or_update_note(path, content, frontmatter)`	智能插入或更新减少决策复杂性
`search_notes(query)`	`search_vault(query, scope, path_filter)`	具有高级过滤功能的精确范围搜索
(无等效项)	`get_daily_note(date)`	常用工作流的高层次抽象
(无等效项)	`get_recent_notes(limit)`	任务导向的最近文件访问
(无等效项)	`find_related_notes(path, on)`	概念关系发现

🛠 可用工具

目录及文件操作

`list_directory`

目的：使用分页列出目录内容以防止上下文溢出

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset":  0
}

AI优势：LLM可以逐步探索保险库结构而不至于上下文过载

`read_file`

目的：读取保险库中任何文件的内容

{"path": "notes/meeting-notes.md"}

`write_file`

目的：使用多种模式写入文件——替代单独的创建/更新操作

{
  "path": "notes/summary.md",
  "content": "# 会议总结\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

AI优势：单个工具处理所有写入场景，消除歧义

`delete_item`

目的：删除任何文件或目录

{"path": "old-notes/"}

AI原生笔记操作

`create_or_update_note`

目的：智能插入或更新——如果不存在则创建，如果存在则更新

{
  "path": "daily/2024-12-26",
  "content": "## 任务\n- 审查AI原生MCP设计",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

AI优势：消除“这个笔记是否存在？”的决策树

`get_daily_note`

目的：使用常见命名模式智能获取每日笔记

{"date": "today"}  // 或 "yesterday", "2024-12-26"

AI优势：抽象化文件系统细节和命名约定

`get_recent_notes`

目的：获取最近修改的笔记

{"limit": 5}

AI优势：匹配自然的“我最近在做什么？”查询

高级搜索与发现

`search_vault`

目的：多范围搜索并具有高级过滤功能

{
  "query": "机器学习",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

AI优势：精确的目标搜索减少噪音

`find_related_notes`

目的：发现笔记之间的概念关系

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

AI优势：支持基于关系的工作流程和偶然发现

向后兼容的遗留工具

该服务器保留了对现有工具如get_note、list_notes、get_metadata_keys等的向后兼容性。

预备条件

Node.js 18+ 或 Bun 运行时
在本地运行的 Obsidian Local REST API（默认：http://obsidian-local-rest-api.test）

安装

使用 npx（推荐）

npx obsidian-local-rest-api-mcp

从源代码安装

# 克隆仓库
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# 使用 bun 安装依赖
bun install

# 构建项目
bun run build

配置

设置环境变量以连接API：

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # 默认URL（或 http://localhost:8000 对于非Valet设置）
export OBSIDIAN_API_KEY="your-api-key"          # 可选的bearer token

使用

运行服务器

# 开发模式，自动重载
bun run dev

# 生产模式
bun run start

# 或直接运行
node build/index.js

MCP客户端配置

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

VS Code 与 MCP 扩展

使用包含的 .vscode/mcp.json 配置文件。

开发

# 开发监视模式
bun run dev

# 构建 TypeScript
bun run build

# 类型检查
bun run tsc --noEmit

架构

ObsidianApiClient - 包装HTTP客户端的REST API端点
ObsidianMcpServer - 具有工具处理器的MCP服务器实现
配置 - 基于环境的配置，并带有验证

错误处理

服务器包括全面的错误处理：

API连接失败
无效的工具参数
网络超时
认证错误

错误作为MCP工具调用响应返回，并附带描述性消息。

调试

通过设置环境变量启用调试日志：

export DEBUG=1
export NODE_ENV=development

服务器日志写入stderr，以避免干扰stdout上的MCP协议通信。

故障排除

MCP服务器无法启动

如果你的MCP客户端显示“启动失败”或其他类似错误：

直接测试服务器：
```
npx obsidian-local-rest-api-mcp --version
```
应输出版本号。

测试MCP协议：

# 运行我们的测试脚本
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
  child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
  setTimeout(() => child.kill(), 2000);
}, 500);
"

应显示初始化响应。

检查环境变量：
- 确保 OBSIDIAN_API_URL 指向正在运行的Obsidian Local REST API
- 直接测试API：curl http://obsidian-local-rest-api.test/api/files（或你配置的API URL）
验证Obsidian Local REST API：
- 安装并运行 Obsidian Local REST API
- 确认其可以在配置的端口上访问
- 检查是否需要认证

常见问题

“命令未找到”：确保已安装Node.js/npm且npx可用

“连接被拒绝”：Obsidian Local REST API未运行或URL错误

Laravel Valet .test 域名：如果使用Laravel Valet，请确保项目目录名称与.test域名匹配（例如，obsidian-local-rest-api.test对于位于/obsidian-local-rest-api/的项目）

“未经授权”：检查是否需要API密钥并正确配置

“超时”：增加客户端配置中的超时时间或检查网络连接

Cherry Studio 配置

对于Cherry Studio，请使用以下确切设置：

名称：obsidian-vault（或你喜欢的任何名称）
类型：标准输入/输出（stdio）
命令：npx
参数：obsidian-local-rest-api-mcp
环境变量：
- OBSIDIAN_API_URL：你的API URL（例如，http://obsidian-local-rest-api.test对于Laravel Valet）
- OBSIDIAN_API_KEY：如果需要认证，则为可选的API密钥
环境变量：
- OBSIDIAN_API_URL：http://obsidian-local-rest-api.test（或你的API URL）
- OBSIDIAN_API_KEY：your-api-key（如果需要）

贡献

分叉仓库
创建一个功能分支
使用正确的TypeScript类型进行更改
使用你的Obsidian保险库进行测试
提交拉取请求

许可证

MIT