JinDaGe - obsidian-local-rest-api-mcp MCP Details

article

README

🚀 Obsidian Local REST API MCP Server

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

🚀 快速开始

前提条件

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（对于非Valet设置，可使用 http://localhost:8000）
export OBSIDIAN_API_KEY="your-api-key"          # 可选的Bearer令牌

运行服务器

# 开发模式，支持自动重新加载
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"
      }
    }
  }
}

带有MCP扩展的VS Code

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

✨ 主要特性

🧠 AI原生设计理念

此MCP服务器按照AI原生原则进行了重新设计，而非简单的API到工具映射。它不暴露低级的CRUD操作，而是提供高级的、面向任务的工具，使大语言模型（LLM）能够更有效地进行推理。

前后对比：变革之处

| 旧方法（基于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": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

对AI的好处：单个工具处理所有写入场景，消除歧义

`delete_item`

用途：删除任何文件或目录

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

AI原生笔记操作

`create_or_update_note`

用途：智能的插入或更新操作，如果笔记不存在则创建，如果存在则更新

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

对AI的好处：消除了“这个笔记是否存在？”的决策树

`get_daily_note`

用途：使用常见的命名模式智能检索每日笔记

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

对AI的好处：抽象了文件系统细节和命名约定

`get_recent_notes`

用途：获取最近修改的笔记

{"limit": 5}

对AI的好处：匹配自然的“我最近处理了哪些内容？”查询

高级搜索和发现

`search_vault`

用途：支持多范围搜索和高级过滤

{
  "query": "machine learning",
  "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 等）的向后兼容性。

🔧 技术细节

架构

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

错误处理

服务器包含全面的错误处理机制：

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
- 确认它在配置的端口上可访问
- 检查是否需要身份验证

常见问题

“Command not found”：确保已安装Node.js/npm，并且npx可用
“Connection refused”：Obsidian Local REST API未运行或URL错误
Laravel Valet .test域名：如果使用Laravel Valet，确保项目目录名称与.test域名匹配（例如，obsidian-local-rest-api.test 对应 /obsidian-local-rest-api/ 项目目录）
“Unauthorized”：检查是否需要API密钥，并确保配置正确
“Timeout”：在客户端配置中增加超时时间，或检查网络连接

Cherry Studio配置

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

名称：obsidian-vault（或您喜欢的任何名称）
类型：Standard Input/Output (stdio)
命令：npx
参数：obsidian-local-rest-api-mcp
环境变量：
- OBSIDIAN_API_URL：您的API URL（例如，对于Laravel Valet，使用 http://obsidian-local-rest-api.test）
- OBSIDIAN_API_KEY：如果需要身份验证，提供可选的API密钥

🤝 贡献

分叉仓库
创建功能分支
使用适当的TypeScript类型进行更改
使用您的Obsidian保险库进行测试
提交拉取请求

📄 许可证

本项目采用MIT许可证。