使用说明
黑曜石MCP服务器
🔗 用于黑曜石集成的模型上下文协议(MCP)服务器
使AI助手能够通过安全、标准化的协议读取、搜索黑曜石金库并与之交互。
特性
- 🔒 安全访问保险库 带路径验证
- 📝 Markdown文件读取 具有元数据提取功能
- 🔍 搜索功能 跨vault内容
- ⚡ 高性能 高效的文件处理
- 🛡️ 安全第一 带输入验证的设计
快速开始
# Install dependencies
npm install
# Set up your vault path
cp .env.example .env
# Edit .env with your vault path
# Start the server
npm run dev
安装
先决条件
- Node.js 18.0.0或更高版本
- 现有的黑曜石拱顶
设置
-
克隆存储库:
git clone https://github.com/SimplyAISolution/Obsidian-MCP-Server.git cd Obsidian-MCP-Server -
安装依赖项:
npm install -
配置环境:
cp .env.example .env编辑
.env并设置vault路径:VAULT_PATH=/path/to/your/obsidian/vault -
构建项目:
npm run build
用法
发展模式
npm run dev
生产模式
npm run build
npm start
运行测试
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
代码质量
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Type checking
npm run typecheck
配置
服务器可以通过环境变量进行配置:
| 变量 | 描述 | 默认值 |
|---|---|---|
VAULT_PATH |
黑曜石保险库路径 | 必填 |
SERVER_PORT |
服务器端口号 | 3000 |
LOG_LEVEL |
日志记录级别(debug, info, warn, error) |
info |
MAX_FILE_SIZE |
最大文件大小(字节) | 10485760 (10 MB) |
ALLOWED_EXTENSIONS |
以逗号分隔的允许文件扩展名列表 | .md,.txt,.json |
api参考
资源
列出资源
{
"method": "resources/list",
"params": {}
}
读取资源
{
"method": "resources/read",
"params": {
"uri": "obsidian://path/to/file.md"
}
}
安全
- 路径横向保护:所有文件路径都经过验证,以防止目录遍历攻击
- 文件扩展名筛选:只能访问允许的文件扩展名
- 文件大小限制:拒绝大文件以防止资源耗尽
- 输入验证:所有输入都使用Zod模式进行验证
发展
项目结构
src/
├── handlers/ # Request handlers
│ └── vault.ts # Vault-specific handlers
├── utils/ # Utility functions
│ ├── logger.ts # Logging utility
│ └── security.ts # Security utilities
├── types/ # Type definitions
│ └── config.ts # Configuration types
├── config.ts # Configuration management
├── server.ts # MCP server implementation
└── index.ts # Main entry point
tests/
├── unit/ # Unit tests
├── integration/ # Integration tests
└── fixtures/ # Test fixtures
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
如果您遇到任何问题或有疑问:
路线图
- []高级搜索功能
- []文件写入功能
- []插件集成
- []批量操作
- []实时文件监视
- []增强的元数据提取
