内容
# MCP Obsidian
MCP（模型上下文协议）服务器，用于通过Obsidian的本地REST API与其交互。
## 先决条件
- [Bun](https://bun.sh/) 运行时
- [Obsidian](https://obsidian.md/)，并安装和配置了 [本地REST API插件](https://github.com/coddingtonbear/obsidian-local-rest-api)
## 安装
1. 克隆此仓库：
```bash
git clone https://github.com/beshkenadze/mcp-obsidian.git
cd mcp-obsidian
```
2. 安装依赖：
```bash
make install
# 或
bun install
```
3. 从OpenAPI规范生成TypeScript类型：
```bash
make generate-types
# 或
bun run generate-types
```
### 作为软件包安装
您可以直接从npm安装软件包：
```bash
# 从npm安装（无需身份验证）
npm install @beshkenadze/mcp-obsidian
# 或
yarn add @beshkenadze/mcp-obsidian
# 或
bun add @beshkenadze/mcp-obsidian
```
或者，您可以从GitHub Packages安装（需要GitHub身份验证）：
```bash
# 添加到 .npmrc
@beshkenadze:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=您的GitHub令牌
# 然后安装
npm install @beshkenadze/mcp-obsidian
# 或
yarn add @beshkenadze/mcp-obsidian
# 或
bun add @beshkenadze/mcp-obsidian
```
## 开发
### 发布流程
该项目使用 [semantic-release](https://semantic-release.gitbook.io/semantic-release/) 来自动化版本管理和软件包发布。工作流程：
1. 提交必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式
- `feat: add new feature` - 触发小版本发布
- `fix: resolve bug` - 触发补丁版本发布
- `feat!:` 或 `fix!:` 或 `refactor!:` 等 - 触发大版本发布
- `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` - 不触发发布
2. 当提交到主分支时，发布工作流程：
- 根据提交消息确定下一个版本号
- 更新 `package.json` 以包含新版本号
- 从提交中生成发布说明
- 创建带有说明的GitHub发布
- 发布到 npm Registry 和 GitHub Packages
- 更新存储库以包含版本更改
您也可以使用GitHub Actions工作流程调度手动触发发布。
## 配置
MCP服务器使用环境变量进行配置：
- `PORT`：MCP服务器监听的端口（默认：3000）
- `OBSIDIAN_BASE_URL`：Obsidian本地REST API的URL（默认：https://127.0.0.1:27124）
- `OBSIDIAN_API_KEY`：您的Obsidian本地REST API密钥（必填）
- `SERVER_TYPE`：要使用的服务器实现 - 'bun' 或 'express'（默认：'bun'）
您可以在项目根目录的 `.env` 文件中设置这些变量：
```bash
PORT=3000
OBSIDIAN_BASE_URL=https://127.0.0.1:27124
OBSIDIAN_API_KEY=您的API密钥
SERVER_TYPE=bun # 选项：bun，express
```
## Docker支持
您可以使用Docker运行MCP Obsidian服务器，并使用不同的传输模式。
### 构建Docker镜像
使用提供的Dockerfile构建Docker镜像：
```bash
docker build -t mcp-obsidian .
```
### 使用Docker运行
使用适当的環境变量运行Docker容器：
```bash
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
beshkenadze/mcp-obsidian
```
注意：使用 `host.docker.internal` 代替 `127.0.0.1` 以从Docker容器中访问运行在主机上的Obsidian。
#### 可用的传输模式
Docker镜像支持不同的传输模式：
##### 1. HTTP模式（默认）
默认模式通过HTTP提供MCP服务器：
```bash
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
beshkenadze/mcp-obsidian
```
##### 2. SSE模式
使用SSE传输运行：
```bash
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=sse \
beshkenadze/mcp-obsidian
```
##### 3. stdio模式
使用stdio传输运行（适用于与其他MCP客户端集成）：
```bash
docker run -i \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidian
```
注意：使用stdio模式时，您必须使用 `-i` 标志启用交互模式。
### 使用Docker与Supergateway
使用Docker容器与Supergateway：
```bash
# 拉取公共Docker镜像（无需身份验证）
docker pull beshkenadze/mcp-obsidian
# 使用stdio传输运行MCP服务器
docker run -i \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidian | \
npx -y @supercorp/supergateway
```
这将Docker容器的stdio输出管道到Supergateway。
## 用法
### 运行MCP服务器
启动MCP服务器：
```bash
make start
# 或
bun run start
```
服务器将在 `http://localhost:3000`（或您配置的端口）可用。
### 服务器实现
MCP服务器支持两种不同的服务器实现：
1. **Bun服务器**（默认）：在Bun环境中使用Bun的原生HTTP服务器实现，以获得最佳性能。
2. **Express服务器**：在Node.js环境中使用Express.js，以获得与Node.js生态系统的更广泛兼容性。
您可以通过设置 `SERVER_TYPE` 环境变量在实现之间切换：
```bash
# 对于Bun服务器（默认）
SERVER_TYPE=bun bun run start
# 对于Express服务器
SERVER_TYPE=express bun run start
```
两种实现提供相同的功能和API端点。双实现方法允许：
- 在不同环境中进行测试
- 与Bun和Node.js部署兼容
- 比较不同服务器架构之间的性能
### 测试
运行单元测试：
```bash
make test
# 或
bun run test
```
运行所有测试，包括集成测试：
```bash
make test-all
# 或
bun run test:all
```
仅运行集成测试（需要运行的Obsidian实例与本地REST API）：
```bash
make test-integration
# 或
bun run test:integration
```
测试套件包括：
- 模拟ObsidianClient和McpServer组件的单元测试
- 测试与Obsidian实际通信的集成测试
注意：应用程序自动禁用SSL证书验证，以使用Obsidian的本地REST API的自签名证书。这在本地开发中是安全的，但在将API暴露给外部网络时应谨慎使用。
### 代码检查
该项目使用 [oxlint](https://oxc.rs/docs/guide/usage/linter)，一个快速的基于Rust的JavaScript/TypeScript代码检查工具。
运行代码检查以检查问题：
```bash
make lint
# 或
bun run lint
```
修复可自动修复的问题：
```bash
make lint-fix
# 或
bun run lint:fix
```
### 可用的MCP工具
MCP服务器公开以下工具：
- `obsidian_get_status`：从Obsidian获取状态信息
- `obsidian_get_active_file`：获取当前活动文件的内容
- `obsidian_update_active_file`：更新当前活动文件的内容
- `obsidian_append_to_active_file`：追加内容到当前活动文件
- `obsidian_patch_active_file`：相对于标题、块或前言修改活动文件
- `obsidian_delete_active_file`：删除当前活动文件
- `obsidian_list_files`：列出目录中的文件
- `obsidian_get_file`：获取文件的内容
- `obsidian_create_or_update_file`：创建新文件或更新现有文件
- `obsidian_append_to_file`：追加内容到文件
- `obsidian_patch_file`：相对于标题、块或前言修改文件
- `obsidian_delete_file`：删除文件
- `obsidian_get_periodic_note`：获取指定期间的当前定期笔记
- `obsidian_update_periodic_note`：更新定期笔记的内容
- `obsidian_append_to_periodic_note`：追加内容到定期笔记
- `obsidian_delete_periodic_note`：删除定期笔记
- `obsidian_patch_periodic_note`：相对于标题、块或前言修改定期笔记
- `obsidian_search`：使用简单文本查询搜索Vault中的内容
- `obsidian_advanced_search`：使用JsonLogic或Dataview查询进行高级搜索
- `obsidian_open_document`：在Obsidian中打开文档
- `obsidian_list_commands`：列出Obsidian中可用的命令
- `obsidian_execute_command`：在Obsidian中执行命令
## 使用SSE支持运行
MCP服务器支持服务器发送事件（SSE）用于与Web客户端的实时通信。有多种方法可以使用SSE支持运行服务器：
### 1. 使用内置SSE模式
使用SSE传输运行服务器：
```bash
make start-sse
# 或
bun run start:sse
# 或使用Docker
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=sse \
beshkenadze/mcp-obsidian
```
这使用 [Supergateway](https://github.com/supercorp-ai/supergateway) 实现SSE并在配置的端口上监听。
### 2. 直接使用Supergateway
您也可以使用专用supergateway脚本运行服务器：
```bash
# 使用supergateway运行
bun run start:supergateway
# 或使用Docker
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidian
```
两种选项提供：
- SSE端点位于：`http://localhost:3000/sse`
- 消息端点位于：`http://localhost:3000/message`
- 跨源请求支持CORS
- 健康端点位于：`http://localhost:3000/healthz`
- 与各种MCP客户端的兼容性提高
## 构建生产版本
要构建生产版本：
```bash
make build
# 或
bun run build
```
这将在 `dist` 目录中创建构建。
## 可用的Makefile命令
为了方便，该项目包含一个Makefile，具有以下命令：
- `make install` - 安装依赖
- `make build` - 构建项目
- `make lint` - 运行代码检查
- `make lint-fix` - 运行代码检查并自动修复
- `make test` - 运行单元测试
- `make test-all` - 运行所有测试
- `make test-integration` - 运行集成测试
- `make generate-types` - 生成TypeScript类型
- `make start` - 启动应用程序
- `make start-sse` - 启动应用程序，启用SSE传输
- `make precommit` - 运行预提交检查
- `make clean` - 清洁构建工件
- `make docker-build` - 构建Docker镜像
- `make docker-run` - 运行Docker容器（HTTP模式）
- `make docker-run-sse` - 运行Docker容器，启用SSE传输
- `make docker-run-stdio` - 运行Docker容器，启用stdio传输
- `make docker-run-supergateway` - 运行Docker容器，启用supergateway
- `make act-build` - 在本地测试构建GitHub Action
- `make act-lint` - 在本地测试代码检查GitHub Action
- `make act-test` - 在本地测试测试GitHub Action
- `make act-release-dry` - 在本地测试发布GitHub Action（干运行）
- `make act-release` - 在本地测试发布GitHub Action
- `make help` - 显示可用命令的帮助信息
## 作为MCP服务器使用
此软件包遵循模型上下文协议（MCP）服务器标准，可与任何MCP客户端一起使用。
### 使用npx（npm Registry - 无需身份验证）
您可以直接从npm无需身份验证使用此软件包：
```bash
npx @beshkenadze/mcp-obsidian
```
### 使用Docker（推荐匿名访问）
使用Docker无需身份验证使用MCP服务器的推荐方法是：
```bash
# 拉取公共Docker镜像（无需身份验证）
docker pull beshkenadze/mcp-obsidian
# 使用stdio传输运行MCP服务器
docker run -i \
-e OBSIDIAN_API_KEY=您的API密钥 \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidian
```
这种方法不需要GitHub令牌或身份验证，只需您的Obsidian API密钥即可。
### 设置匿名访问
要匿名使用MCP服务器：
1. **直接使用npm**：该软件包可在npm Registry上使用，无需身份验证要求。
2. **使用Docker方法**：Docker镜像可在无需身份验证的情况下公开使用。
3. 无需GitHub令牌或身份验证。
4. 您唯一需要的身份验证是您的Obsidian API密钥，用于访问Obsidian，而不是用于软件包访问。
### 在Claude Desktop中配置
要将MCP服务器与Claude Desktop一起使用，请在Claude Desktop配置中添加它：
#### 选项1：使用Docker（推荐匿名访问）
这种方法不需要GitHub身份验证：
```json
{
"mcpServers": {
"obsidian": {
"command": "docker",
"args": ["run", "-i", "beshkenadze/mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "您的API密钥",
"TRANSPORT_TYPE": "stdio"
}
}
}
}
```
#### 选项2：使用npx并使用GitHub身份验证
此方法需要GitHub身份验证：
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@beshkenadze/mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "您的API密钥",
"NPM_CONFIG_REGISTRY": "https://registry.npmjs.org",
"NPM_CONFIG__AUTH_TYPES": "legacy",
"NPM_CONFIG__AUTHTOKEN": "您的GitHub令牌",
"NPM_CONFIG__REGISTRY_SCOPES": "@beshkenadze",
"NPM_CONFIG__REGISTRIES_@BESHKENADZE": "https://npm.pkg.github.com"
}
}
}
}
```
### 在其他MCP客户端中配置
许多MCP客户端，如Continue、Cursor、LibreChat等，都支持MCP服务器。请参阅客户端文档获取特定配置详细信息。
### 安装为软件包
如果您想本地安装软件包（需要GitHub身份验证）：
```bash
# 添加到 .npmrc
@beshkenadze:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=您的GitHub令牌
# 然后安装
npm install @beshkenadze/mcp-obsidian
# 或
yarn add @beshkenadze/mcp-obsidian
# 或
bun add @beshkenadze/mcp-obsidian
```
> **注意**：对于匿名访问，请使用上述Docker方法。
## 贡献
欢迎贡献！请随时提交拉取请求。
## 许可证
本项目根据MIT许可证授权 - 有关详细信息，请参阅LICENSE文件。
连接信息
猜你喜欢
暂无推荐服务器