obsidian-cli-mcp 0.1.0__py3-none-any.whl

obsidian_cli_mcp/__init__.py

@@ -0,0 +1,31 @@
+import asyncio
+import sys
+
+from .client import ObsidianClient
+from .exceptions import ObsidianCLIError, ObsidianError, ObsidianNotFoundError
+from .server import create_server
+
+__all__ = [
+    "ObsidianCLIError",
+    "ObsidianClient",
+    "ObsidianError",
+    "ObsidianNotFoundError",
+    "create_server",
+    "main",
+]
+
+
+async def _run_server() -> None:
+    try:
+        server = create_server()
+        await server.run_stdio_async()
+    except ObsidianNotFoundError as e:
+        print(f"Error starting obsidian-mcp: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        pass
+
+
+def main() -> None:
+    """CLI 入口点，启动 MCP Stdio 通信服务。"""
+    asyncio.run(_run_server())

obsidian_cli_mcp/cli.py

@@ -0,0 +1,38 @@
+import asyncio
+from dataclasses import dataclass
+
+
+@dataclass
+class CommandExecutionResult:
+    returncode: int | None
+    stdout: str
+    stderr: str
+
+
+async def run_cli_command(
+    program: str, args: list[str], *, timeout: int = 30
+) -> CommandExecutionResult:
+    """运行 CLI 子进程命令并等待输出。"""
+    try:
+        process = await asyncio.create_subprocess_exec(
+            program,
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+
+        return CommandExecutionResult(
+            returncode=process.returncode,
+            stdout=stdout.decode("utf-8", errors="replace").strip(),
+            stderr=stderr.decode("utf-8", errors="replace").strip(),
+        )
+    except TimeoutError:
+        process.kill()
+        await process.wait()
+        return CommandExecutionResult(
+            returncode=-1,
+            stdout="",
+            stderr=f"Command timed out after {timeout} seconds",
+        )

obsidian_cli_mcp/client.py

@@ -0,0 +1,111 @@
+import json
+import os
+import shutil
+from typing import Any
+
+from .cli import CommandExecutionResult, run_cli_command
+from .exceptions import ObsidianCLIError, ObsidianNotFoundError
+
+# 允许保留空字符串的参数（如清空属性值、创建空白内容等）
+ALLOW_EMPTY_VALUE_KEYS = {"content", "value"}
+
+
+class ObsidianClient:
+    """Obsidian CLI 异步客户端。负责参数序列化、环境变量回退、执行控制与结果解析。"""
+
+    def __init__(
+        self,
+        vault: str | None = None,
+        cli_path: str | None = None,
+        timeout: int = 30,
+    ) -> None:
+        self.vault = vault or os.getenv("OBSIDIAN_VAULT")
+        resolved_cli = (
+            cli_path or os.getenv("OBSIDIAN_CLI_PATH") or shutil.which("obsidian")
+        )
+        if not resolved_cli:
+            raise ObsidianNotFoundError(
+                "Obsidian CLI executable not found. Please install Obsidian CLI or set OBSIDIAN_CLI_PATH."
+            )
+        self.cli_path = resolved_cli
+        self.timeout = timeout
+
+    def _build_args(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        vault: str | None = None,
+    ) -> list[str]:
+        """将 Python 字典转换为 Obsidian CLI 参数列表。
+
+        规则：
+        - True: 转换为裸 flag（例如 verbose=True -> 'verbose'）
+        - False / None: 忽略该参数
+        - 纯空白字符串（若非 content/value 白名单）: 忽略该参数，防止意外触发 CLI 对活跃文件的回退行为
+        - 其余类型: 转换为 key=value 字符串
+        """
+        args = [command]
+        merged_params = dict(params or {})
+
+        # 确定目标 vault：参数指定 > 实例/环境变量默认 > 不传（回退到活跃库）
+        target_vault = vault if vault is not None else self.vault
+        if target_vault and target_vault.strip() and "vault" not in merged_params:
+            merged_params["vault"] = target_vault.strip()
+
+        for key, val in merged_params.items():
+            if val is None or val is False:
+                continue
+            if val is True:
+                args.append(key)
+            elif (
+                isinstance(val, str)
+                and not val.strip()
+                and key not in ALLOW_EMPTY_VALUE_KEYS
+            ):
+                continue
+            else:
+                args.append(f"{key}={val}")
+
+        return args
+
+    async def execute(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        parse_json: bool = False,
+        vault: str | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        """执行 Obsidian CLI 命令并返回文本或解析后的 JSON。"""
+        cli_args = self._build_args(command, params, vault=vault)
+        res: CommandExecutionResult = await run_cli_command(
+            self.cli_path, cli_args, timeout=timeout or self.timeout
+        )
+
+        # 检查错误：非零退出码或 stdout 以 Error: 开头
+        if res.returncode != 0:
+            err_msg = (
+                res.stderr
+                or res.stdout
+                or f"Command '{command}' failed with exit code {res.returncode}"
+            )
+            raise ObsidianCLIError(
+                err_msg, returncode=res.returncode, stderr=res.stderr, stdout=res.stdout
+            )
+
+        if res.stdout.startswith("Error:"):
+            raise ObsidianCLIError(
+                res.stdout,
+                returncode=res.returncode,
+                stderr=res.stderr,
+                stdout=res.stdout,
+            )
+
+        if parse_json:
+            try:
+                return json.loads(res.stdout)
+            except json.JSONDecodeError:
+                return res.stdout
+
+        return res.stdout

obsidian_cli_mcp/exceptions.py

@@ -0,0 +1,22 @@
+class ObsidianError(Exception):
+    """Base exception for obsidian-mcp."""
+
+
+class ObsidianNotFoundError(ObsidianError):
+    """Raised when obsidian CLI executable is not found."""
+
+
+class ObsidianCLIError(ObsidianError):
+    """Raised when obsidian CLI command execution fails."""
+
+    def __init__(
+        self,
+        message: str,
+        returncode: int | None = None,
+        stderr: str = "",
+        stdout: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.returncode = returncode
+        self.stderr = stderr
+        self.stdout = stdout

obsidian_cli_mcp/server.py

@@ -0,0 +1,20 @@
+from mcp.server.mcpserver import MCPServer
+
+from .client import ObsidianClient
+from .tools import register_tools
+
+
+def create_server(
+    vault: str | None = None,
+    cli_path: str | None = None,
+    timeout: int = 30,
+) -> MCPServer:
+    """创建并配置 Obsidian MCP 服务器实例。"""
+    client = ObsidianClient(vault=vault, cli_path=cli_path, timeout=timeout)
+    server = MCPServer(
+        name="obsidian-cli-mcp",
+        version="0.1.0",
+        instructions="Obsidian CLI MCP server providing full control over Obsidian vaults.",
+    )
+    register_tools(server, client)
+    return server