Obsidian MCP Actor

黑曜石MCP演员

一个安全、高性能的Apify Actor，通过模型上下文协议（MCP）将黑曜石笔记工作流程与智能网络抓取自动化连接起来。使用来自任何网站的结构化数据自动丰富您的知识库。

🎯 v2.0中的新增功能

🛡️ 安全加固

• 路径遍历保护：根据vault目录验证所有文件操作
• 内容大小限制：防止最大内容大小为10MB的OOM
• 输入验证：具有明确错误类别的山宁泰URL和文件名
• Robots.txt合规性：自动尊重 robots.txt 规则

⚡ 性能和可扩展性

• 并行处理：并发图像下载（速度快3-10倍）
• 智能缓存：三种缓存策略（内存、磁盘、Apify KV）
• 指数退避：针对速率受限站点的具有抖动的智能重试逻辑
• 隐身模式：增强了剧作家规避，以保护反机器人

🏗️ 现代建筑

• 服务导向设计：模块化、可测试、可维护
• 策略模式：可插拔的刮擦引擎（Cheerio→ 剧作家后备）
• 实时监控：实时WebSocket进度查看器
• TypeScript支持：核心接口的完整类型定义

______________________________________________________________________

🔥 主要特点

______________________________________________________________________

🚀 快速开始

单个URL报废

{
  "url": "https://example.com/article",
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "folderPath": "research/articles",
  "tags": ["ai", "research"],
  "autoTag": true,
  "autoLink": true
}

带缓存的批量导入

{
  "urls": [
    "https://site1.com/post",
    "https://site2.com/guide",
    "https://site3.com/tutorial"
  ],
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "bulkMode": true,
  "usePlaywright": false,
  "cache": "disk",
  "rateLimitDelay": 2000
}

JavaScript重度网站

{
  "url": "https://react-app.example.com",
  "vaultPath": "/Users/yourname/Documents/Obsidian",
  "usePlaywright": true,
  "enableStealth": true,
  "playwrightTimeout": 45
}

______________________________________________________________________

📋 配置参考

核心设置

处理选项

性能和可靠性

\*要么 url 或 urls 必须提供

______________________________________________________________________

📁 生成的笔记格式

---
title: "Understanding Machine Learning"
url: https://example.com/ml-guide
scraped: 2024-01-15T10:30:00.000Z
tags: ["machine-learning", "ai", "research", "technology", "example"]
description: "A comprehensive guide to ML fundamentals"
author: "Jane Smith"
---

# Understanding Machine Learning

> 🔗 Source: [https://example.com/ml-guide](https://example.com/ml-guide)

> 📅 Scraped: January 15, 2024

---

## Article Content

Full content converted to Markdown...

---

## Metadata

- **Author:** Jane Smith
- **Description:** A comprehensive guide to ML fundamentals
- **Canonical:** https://example.com/ml-guide
- **Robots:** index,follow

______________________________________________________________________

🎓 高级用法

基于模板的配置

创建 templates/scraper-config.md 在您的保险库中：

---
folderPath: "research/ai-papers"
autoTag: true
autoLink: true
tags: ["ai", "paper"]
usePlaywright: false
cache: "disk"
---

# AI Paper Scraper Template

This template automatically applies settings when referenced.

用途：

{
  "url": "https://arxiv.org/abs/2401.12345",
  "vaultPath": "/path/to/vault",
  "templatePath": "templates/scraper-config"
}

缓存策略

// Memory cache (fast, ephemeral)
const cache = new MemoryCache({ maxSize: 100 });

// Disk cache (persistent across runs)
const cache = new PersistentCache({ cacheDir: './storage' });

// Apify KV store (cloud, for scheduled actors)
const cache = new PersistentScrapeCache('my-scrape-cache');

实时进度查看器

地方发展：

npm install  # Install dependencies
npm run dev  # Start MCP server with live viewer

Apify平台：

{
  "startResultsServer": true,
  "resultsServerPort": 8080
}

然后访问 http://localhost:8080 在您的浏览器中。

______________________________________________________________________

🤖 MCP服务器集成

Actor向Claude/LLM公开了5个工具：

# Install globally
npm install -g obsidian-mcp-actor

# Add to Claude config
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-actor",
      "args": ["mcp-server"]
    }
  }
}

可用工具：

1. scrape_website -删除任何URL
2. extract_tags -分析标签内容
3. validate_content -检查刮擦质量
4. convert_html_to_markdown -转换内容
5. save_note -保存到黑曜石保险库

AI工作流示例：

“克劳德，从黑客新闻中抓取最新的5篇文章，按主题标记它们，并保存到我的 trending 带有内部链接的文件夹。"

______________________________________________________________________

🔧 开发设置

# Clone repository
git clone https://github.com/yourusername/obsidian-mcp-actor.git
cd obsidian-mcp-actor

# Install dependencies
npm install

# Run TypeScript compilation
npm run build

# Run tests
npm test

# Start MCP server locally
npm run mcp-server

项目结构

obsidian-mcp-actor/
├── src/
│   ├── main.js                      # Apify Actor entry point
│   ├── mcp-server.js               # MCP server entry point
│   └── lib/
│       ├── processor/              # Core business logic
│       │   ├── UnifiedScraper.js
│       │   ├── MarkdownConverter.js
│       │   ├── TagExtractor.js
│       │   └── ActorService.js
│       ├── scraper/                # Scraping strategies
│       │   ├── CheerioStrategy.js
│       │   └── PlaywrightStrategy.js
│       ├── vault/                  # Obsidian operations
│       │   ├── NoteManager.js
│       │   └── LinkManager.js
│       ├── cache/                  # Caching implementations
│       │   ├── MemoryCache.js
│       │   ├── PersistentCache.js
│       │   └── PersistentScrapeCache.js
│       ├── utils/                  # Utilities
│       │   ├── url.js
│       │   ├── errors.js
│       │   ├── retry.js
│       │   └── stealth.js
│       └── server/                 # WebSocket server
│           └── ResultsServer.js
├── test/                           # Unit and integration tests
├── input_schema.json               # Apify input schema
├── output_schema.json              # Apify output schema
└── package.json

______________________________________________________________________

🧪 测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test test/UnifiedScraper.test.js

测试覆盖目标：

• 核心抓取逻辑：>90%
• 安全验证：100%
• 保险库操作：>85%

______________________________________________________________________

📦 部署

Apify平台

1. 推到Apify：

apify push

1. 配置环境变量：

APIFY_MEMORY_MBYTES=4096
APIFY_BUILD_TIMEOUT_SECS=300

1. 计划运行：

apify schedule create my-schedule \
  --actor-id your-actor-id \
  --cron "0 9 * * *" \
  --input-json '{"urls": [...], "vaultPath": "/data"}'

自托管

# Docker
docker build -t obsidian-mcp-actor .
docker run -v /path/to/vault:/data -p 8080:8080 obsidian-mcp-actor

______________________________________________________________________

🔄 从v1.x迁移

突破性变化

对于大多数用户：无需更改。 公共API保持相同。

如果你扩展了内部：

• 遗留功能 helpers.js 已弃用，但功能正常
• 从特定模块导入新功能：

  // Old (still works)
  import { scrapeWebsite } from './helpers.js';

  // New (recommended)
  import { UnifiedScraper } from './lib/processor/UnifiedScraper.js';
  const scraper = new UnifiedScraper({ usePlaywright: true });

新缓存API

// Old
const cache = new ScrapeCache();

// New
const cache = new MemoryCache({ maxSize: 100, ttl: 3600000 });

更新的文件结构

从以下位置移动自定义代码 main.js 到 lib/processor/ActorService.js 为了模块化。

______________________________________________________________________

📚 用例

______________________________________________________________________

📊 性能基准

*M1 Mac上的基准测试，10个并发工作者*

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

开发指南

• 为新功能编写测试
• 遵循现有的代码风格（ESLint配置）
• 更新TypeScript类型
• 使用JSDoc记录公共API
• 安全第一：验证所有输入

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 内置于 克劳利 和 剧作家
• 受到黑曜石社区自动化需求的启发
• MCP协议 Anthropic

______________________________________________________________________

由以下材料制成❤️ 面向研究人员、知识工作者和自动化爱好者

*将您的黑曜石金库转化为自我更新的知识库。*