AI导哈

Obsidian本地REST API MCP服务器

一个AI原生的MCP服务器，通过本地REST API为Obsidian库提供智能、任务导向的工具。

  • by j-shelfwood
  • TypeScript
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 j-shelfwood/obsidian-local-rest-api-mcp

使用说明

黑名单本地REST API MCP服务器

一个AI-Native MCP（模型上下文协议）服务器，提供智能的、面向任务的工具，用于通过本地REST API与黑社会保险库交互。

🧠 AI原生设计理念

此MCP服务器已按照AI基本原则进行了重新设计，而不是简单的API到ol映射。它没有公开低级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

目的：读取vault中任何文件的内容

{"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"}  // or "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等等。

先决条件

  • Node.js 18+或Bun运行时
  • 黑名单本地REST API 在本地运行（默认值：http://obsidian-local-rest-api.test)

安装

使用npx（推荐）

npx obsidian-local-rest-api-mcp

来源

# Clone the repository
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# Install dependencies with bun
bun install

# Build the project
bun run build

配置

为API连接设置环境变量：

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # Default URL (or http://localhost:8000 for non-Valet setups)
export OBSIDIAN_API_KEY="your-api-key"          # Optional bearer token

用法

运行服务器

# Development mode with auto-reload
bun run dev

# Production mode
bun run start

# Or run directly
node build/index.js

MCP客户端配置

克劳德桌面

添加到您的 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代码

使用随附的 .vscode/mcp.json 配置文件。

发展

# Watch mode for development
bun run dev

# Build TypeScript
bun run build

# Type checking
bun run tsc --noEmit

建筑

  • 黑曜石ApiClient -REST API端点的HTTP客户端包装
  • 黑曜石McpServer -使用工具处理程序实现MCP服务器
  • 配置 -基于环境的配置和验证

错误处理

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

  • API连接失败
  • 无效的工具参数
  • 网络超时
  • 身份验证错误

错误以MCP工具调用响应的形式返回，并带有描述性消息。

调试

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

export DEBUG=1
export NODE_ENV=development

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

故障排除

MCP服务器无法启动

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

  1. 直接测试服务器:

    npx obsidian-local-rest-api-mcp --version

    应输出版本号。

  2. 测试MCP协议:

    # Run our test script
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);
"

    应显示初始化响应。

  3. 检查环境变量:

    • 确保 OBSIDIAN_API_URL 指向正在运行的Obsidian本地REST API
    • 直接测试API： curl http://obsidian-local-rest-api.test/api/files （或您配置的API URL）

  4. 验证Obsidian本地REST API:

    • 安装并运行 黑名单本地REST API
    • 确认它可以在配置的端口上访问
    • 检查是否需要身份验证

常见问题

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

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

Laravel代客泊车测试域名：如果使用Laravel Valet，请确保您的项目目录名与.test域匹配（例如。， obsidian-local-rest-api.test 对于一个项目 /obsidian-local-rest-api/)

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

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

樱桃工作室配置

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

  • 名字: obsidian-vault （或您喜欢的任何名称）
  • 类型: Standard Input/Output (stdio)
  • 命令: npx
  • 参数: obsidian-local-rest-api-mcp
  • 环境变量:
    • OBSIDIAN_API_URL：您的API URL（例如。， http://obsidian-local-rest-api.test Laravel代客泊车）
    • OBSIDIAN_API_KEY：可选API密钥（如果需要身份验证）
  • 环境变量:
    • OBSIDIAN_API_URL: http://obsidian-local-rest-api.test （或您的API URL）
    • OBSIDIAN_API_KEY: your-api-key （如果需要）

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 使用正确的TypeScript类型进行更改
  4. 用你的黑曜石保险库测试
  5. 提交拉取请求

许可证

麻省理工学院

相关 MCP