obsidian-agent-cli-app 0.1.0__py3-none-any.whl

obsidian_agent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

obsidian_agent/cli.py

@@ -0,0 +1,54 @@
+"""Command-line entry point for obsidian-agent, built on Typer for
+clean --help output and a lower-boilerplate command structure."""
+
+import asyncio
+
+import typer
+
+from .config import CONFIG_FILE, load_config
+from .doctor import run_doctor
+from .loop import main_loop
+
+app = typer.Typer(
+    name="obsidian-agent",
+    help="Chat with your Obsidian vault via an MCP-connected AI agent.",
+    add_completion=True,
+    no_args_is_help=False,
+)
+
+
+@app.command()
+def chat():
+    """Start an interactive chat session (default command)."""
+    config = load_config()
+    asyncio.run(main_loop(config))
+
+
+@app.command()
+def doctor():
+    """Check that obsidian-mcp is installed and can reach your vault."""
+    config = load_config()
+    run_doctor(config)
+
+
+@app.command()
+def config(reset: bool = typer.Option(False, "--reset", help="Re-run first-time setup.")):
+    """View or reset your configuration."""
+    if reset:
+        load_config(force_setup=True)
+        return
+    typer.echo(f"Config file: {CONFIG_FILE}")
+    if CONFIG_FILE.exists():
+        typer.echo(CONFIG_FILE.read_text())
+    else:
+        typer.echo("No config yet — run 'obsidian-agent config --reset' to create one.")
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    if ctx.invoked_subcommand is None:
+        chat()
+
+
+if __name__ == "__main__":
+    app()

obsidian_agent/config.py

@@ -0,0 +1,60 @@
+"""User configuration: a one-time interactive setup, stored under the
+platform's standard config directory, with env-var overrides for power
+users."""
+
+import os
+import tomllib
+from pathlib import Path
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "obsidian-agent"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+DEFAULT_MODEL = "meta-llama/llama-3.1-8b-instruct"
+
+
+def _write_config(config: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        for key, value in config.items():
+            f.write(f'{key} = "{value}"\n')
+    print(f"Saved config to {CONFIG_FILE}")
+
+
+def run_first_time_setup() -> dict:
+    print("First-time setup for obsidian-agent.\n")
+    api_key = input("Enter your OpenRouter API key: ").strip()
+    vault_path = input("Enter the absolute path to your Obsidian vault: ").strip()
+    model = input(f"Model to use [{DEFAULT_MODEL}]: ").strip() or DEFAULT_MODEL
+
+    config = {
+        "openrouter_api_key": api_key,
+        "vault_path": vault_path,
+        "model": model,
+    }
+    _write_config(config)
+    return config
+
+
+def load_config(force_setup: bool = False) -> dict:
+    if force_setup or not CONFIG_FILE.exists():
+        config = run_first_time_setup()
+    else:
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+
+    # Env vars always win, for power users / CI / testing.
+    config["openrouter_api_key"] = os.environ.get(
+        "OPENROUTER_API_KEY", config.get("openrouter_api_key")
+    )
+    config["vault_path"] = os.environ.get(
+        "OBSIDIAN_VAULT_PATH", config.get("vault_path")
+    )
+    config["model"] = os.environ.get("AGENT_MODEL", config.get("model", DEFAULT_MODEL))
+
+    missing = [k for k in ("openrouter_api_key", "vault_path") if not config.get(k)]
+    if missing:
+        raise ValueError(
+            f"Missing required config: {', '.join(missing)}. "
+            f"Run 'obsidian-agent config --reset' to set up again."
+        )
+    return config

obsidian_agent/core.py

@@ -0,0 +1,55 @@
+"""Shared building blocks: MCP session helpers, tool-schema conversion,
+and the OpenRouter/OpenAI client. Both the chat loop and the doctor
+command build on this."""
+
+import os
+from mcp import StdioServerParameters
+from openai import OpenAI
+
+SYSTEM_PROMPT = (
+    "You are a helpful assistant with access to the user's Obsidian vault. "
+    "Always read a note before updating it so you don't overwrite existing "
+    "content by accident, unless the user clearly asks you to replace it."
+)
+
+
+def build_llm_client(api_key: str) -> OpenAI:
+    return OpenAI(
+        api_key=api_key,
+        base_url="https://openrouter.ai/api/v1",
+    )
+
+
+def build_server_params(vault_path: str) -> StdioServerParameters:
+    return StdioServerParameters(
+        command="obsidian-mcp",
+        args=[],
+        env={
+            **os.environ,
+            "OBSIDIAN_VAULT_PATH": vault_path,
+            # Quiet the server's own logging; we only want MCP protocol
+            # traffic on stdio, not its log lines colliding with our UI.
+            "OBSIDIAN_LOG_LEVEL": "ERROR",
+        },
+    )
+
+
+def convert_mcp_tool_to_openai(tool) -> dict:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.inputSchema,
+        },
+    }
+
+
+async def execute_tool_call(tool_name: str, arguments: dict, session) -> str:
+    try:
+        result = await session.call_tool(tool_name, arguments=arguments)
+        if result.content and len(result.content) > 0:
+            return result.content[0].text
+        return "Tool executed but returned no content."
+    except Exception as e:
+        return f"Error calling tool: {e}"

obsidian_agent/doctor.py

@@ -0,0 +1,67 @@
+"""Sanity checks: is obsidian-mcp installed, and can we actually reach
+tools on the configured vault. This is test_obsidian_mcp.py, promoted to
+a real subcommand with rich output."""
+
+import asyncio
+import json
+import os
+import shutil
+
+from mcp import ClientSession
+from mcp.client.stdio import stdio_client
+
+from . import ui
+from .core import build_server_params
+
+
+def check_obsidian_mcp_installed() -> bool:
+    found = shutil.which("obsidian-mcp") is not None
+    if not found:
+        ui.console.print("[bold red]✗[/] obsidian-mcp was not found on your PATH.")
+        ui.console.print("  Install it with: [cyan]pip install obsidian-mcp[/]")
+    else:
+        ui.console.print("[bold green]✓[/] obsidian-mcp found on PATH.")
+    return found
+
+
+async def check_vault_connection(vault_path: str):
+    server_params = build_server_params(vault_path)
+    ui.console.print(f"[dim]Connecting to vault:[/] {vault_path}")
+
+    # Same stderr redirect as loop.py — keep obsidian-mcp's own log
+    # lines from cluttering the doctor output.
+    with open(os.devnull, "w") as devnull:
+        async with stdio_client(server_params, errlog=devnull) as (read_stream, write_stream):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+
+                tools_result = await session.list_tools()
+                ui.console.print(f"[bold green]✓[/] Connected. {len(tools_result.tools)} tools available:")
+                for tool in tools_result.tools:
+                    desc = (tool.description or "").strip().splitlines()
+                    desc = desc[0] if desc else ""
+                    ui.console.print(f"  [cyan]{tool.name}[/]  [dim]{desc}[/]")
+
+                ui.console.print("\n[dim]Listing notes in vault root...[/]")
+                result = await session.call_tool("list_notes_tool", arguments={"recursive": True})
+                content = result.content[0].text if result.content else "No data"
+                try:
+                    data = json.loads(content)
+                    items = data.get("items", [])
+                    ui.console.print(f"[bold green]✓[/] Found {data.get('total', len(items))} notes. First 10:")
+                    for note in items[:10]:
+                        ui.console.print(f"  [dim]-[/] {note.get('path')}")
+                except json.JSONDecodeError:
+                    ui.console.print("[yellow]Raw response:[/]", content)
+
+
+def run_doctor(config: dict):
+    ui.console.rule("[bold cyan]obsidian-agent doctor")
+    if not check_obsidian_mcp_installed():
+        raise SystemExit(1)
+    try:
+        asyncio.run(check_vault_connection(config["vault_path"]))
+    except Exception as e:
+        ui.print_error(f"Could not connect to vault: {e}")
+        raise SystemExit(1)
+    ui.console.print("\n[bold green]All checks passed.[/]")

obsidian_agent/loop.py

@@ -0,0 +1,148 @@
+"""The agentic chat loop: keeps calling tools until the model responds
+with plain text instead of another tool call, instead of stopping after
+one round. Now with streaming output and slash commands."""
+
+import json
+import os
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession
+from mcp.client.stdio import stdio_client
+
+from . import ui
+from .core import (
+    SYSTEM_PROMPT,
+    build_llm_client,
+    build_server_params,
+    convert_mcp_tool_to_openai,
+    execute_tool_call,
+)
+
+MAX_STEPS = 8
+EXTRA_HEADERS = {
+    "HTTP-Referer": "http://localhost:8080",
+    "X-Title": "Obsidian Agent",
+}
+
+
+async def run_turn(client_llm, model, messages, tools, session, max_steps=MAX_STEPS):
+    """Keep calling tools, feeding results back to the model, until it
+    responds with plain text instead of another tool call, or the step
+    budget runs out."""
+    for _ in range(max_steps):
+        with ui.thinking_spinner():
+            response = client_llm.chat.completions.create(
+                model=model,
+                messages=messages,
+                tools=tools,
+                tool_choice="auto",
+                temperature=0.7,
+                extra_headers=EXTRA_HEADERS,
+            )
+        msg = response.choices[0].message
+        messages.append(msg.to_dict())
+
+        if not msg.tool_calls:
+            return msg.content
+
+        for tool_call in msg.tool_calls:
+            try:
+                args = json.loads(tool_call.function.arguments)
+            except json.JSONDecodeError:
+                result_text = "Error: malformed tool arguments"
+                args = {}
+            else:
+                ui.print_tool_call(tool_call.function.name, args)
+                result_text = await execute_tool_call(
+                    tool_call.function.name, args, session
+                )
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": result_text,
+                }
+            )
+
+    return "Stopped after too many steps — the task may be more complex than expected."
+
+
+def handle_slash_command(command: str, messages: list, tools: list, system_prompt: str) -> bool:
+    """Returns True if the input was a slash command (and was handled)."""
+    if command == "/help":
+        ui.print_help()
+        return True
+    if command == "/tools":
+        ui.print_tools(tools)
+        return True
+    if command == "/clear":
+        messages.clear()
+        messages.append({"role": "system", "content": system_prompt})
+        ui.console.print("[dim]Conversation cleared.[/]\n")
+        return True
+    return False
+
+
+async def main_loop(config: dict):
+    vault_path = config["vault_path"]
+    model = config["model"]
+    api_key = config["openrouter_api_key"]
+
+    client_llm = build_llm_client(api_key)
+    server_params = build_server_params(vault_path)
+
+    # AsyncExitStack keeps the stdio subprocess and MCP session alive for
+    # the whole chat loop. Returning a session from inside a narrower
+    # "async with" block would close the connection the moment that
+    # function returns — every tool call after that would silently fail.
+    async with AsyncExitStack() as stack:
+        with ui.console.status("[dim]starting obsidian-mcp...[/]"):
+            # Redirect the subprocess's stderr to devnull so its own log
+            # lines (fastmcp INFO logs, authlib deprecation warnings)
+            # don't interleave with our Rich output. A plain sync file
+            # object is fine here — errlog just needs to be file-like.
+            devnull = stack.enter_context(open(os.devnull, "w"))
+            read_stream, write_stream = await stack.enter_async_context(
+                stdio_client(server_params, errlog=devnull)
+            )
+            session = await stack.enter_async_context(
+                ClientSession(read_stream, write_stream)
+            )
+            await session.initialize()
+            tools_result = await session.list_tools()
+
+        if not tools_result.tools:
+            ui.print_error("No tools available from obsidian-mcp. Exiting.")
+            return
+
+        openai_tools = [convert_mcp_tool_to_openai(t) for t in tools_result.tools]
+        messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+        ui.print_banner(vault_path, model)
+
+        while True:
+            try:
+                ui.print_turn_separator()
+                user_input = ui.prompt_user()
+            except (EOFError, KeyboardInterrupt):
+                ui.console.print("\n[dim]Goodbye.[/]")
+                break
+
+            stripped = user_input.strip()
+            if not stripped:
+                continue
+            if stripped.lower() in ("exit", "quit", "/exit", "/quit"):
+                ui.console.print("[dim]Goodbye.[/]")
+                break
+            if stripped.startswith("/"):
+                if handle_slash_command(stripped, messages, openai_tools, SYSTEM_PROMPT):
+                    continue
+
+            messages.append({"role": "user", "content": user_input})
+
+            try:
+                reply = await run_turn(client_llm, model, messages, openai_tools, session)
+                messages.append({"role": "assistant", "content": reply})
+                ui.print_agent_reply(reply)
+            except Exception as e:
+                ui.print_error(str(e))

obsidian_agent/ui.py

@@ -0,0 +1,80 @@
+"""Terminal presentation layer: banner, spinners, markdown rendering,
+colored tool-call output. Kept separate from the agent logic so the
+core loop doesn't need to know or care how things are displayed."""
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.spinner import Spinner
+from rich.live import Live
+from rich.text import Text
+from rich.rule import Rule
+
+console = Console()
+
+BANNER = r"""
+[bold cyan] ██████╗ ██████╗ ███████╗██╗██████╗ ██╗ █████╗ ███╗   ██╗[/]
+[bold cyan]██╔═══██╗██╔══██╗██╔════╝██║██╔══██╗██║██╔══██╗████╗  ██║[/]
+[bold cyan]██║   ██║██████╔╝███████╗██║██║  ██║██║███████║██╔██╗ ██║[/]
+[bold cyan]██║   ██║██╔══██╗╚════██║██║██║  ██║██║██╔══██║██║╚██╗██║[/]
+[bold cyan]╚██████╔╝██████╔╝███████║██║██████╔╝██║██║  ██║██║ ╚████║[/]
+[bold cyan] ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝[/]
+[dim]                          a g e n t[/]
+"""
+
+
+def print_banner(vault_path: str, model: str):
+    console.print(BANNER)
+    console.print(f"[dim]vault:[/] {vault_path}")
+    console.print(f"[dim]model:[/] {model}")
+    console.print("[dim]Type a message, or /help for commands.[/]\n")
+
+
+def print_help():
+    console.print(
+        Panel.fit(
+            "[bold]/help[/]   show this message\n"
+            "[bold]/tools[/]  list available vault tools\n"
+            "[bold]/clear[/]  clear the conversation history\n"
+            "[bold]/exit[/]   quit  [dim](also: exit, quit, Ctrl+D)[/]",
+            title="commands",
+            border_style="cyan",
+        )
+    )
+
+
+def print_tools(tools: list):
+    lines = []
+    for t in tools:
+        name = t["function"]["name"]
+        desc = (t["function"]["description"] or "").strip().splitlines()
+        desc = desc[0] if desc else ""
+        lines.append(f"[bold cyan]{name}[/]  [dim]{desc}[/]")
+    console.print(Panel.fit("\n".join(lines), title=f"{len(tools)} tools available", border_style="cyan"))
+
+
+def print_tool_call(name: str, arguments: dict):
+    args_str = ", ".join(f"{k}={v!r}" for k, v in arguments.items())
+    console.print(f"  [dim]→ using[/] [bold yellow]{name}[/]([dim]{args_str}[/])")
+
+
+def print_agent_reply(text: str):
+    console.print()
+    console.print("[bold magenta]◆ agent[/]")
+    console.print(Markdown(text or "*(no response)*"), style="")
+    console.print()
+
+
+def print_error(message: str):
+    console.print(f"[bold red]Error:[/] {message}")
+
+
+def thinking_spinner():
+    """Returns a context-manager Live spinner; use with `with thinking_spinner():`."""
+    return Live(Spinner("dots", text=Text(" thinking...", style="dim")), console=console, refresh_per_second=10, transient=True)
+
+def print_turn_separator():
+    console.print(Rule(style="dim"))
+
+def prompt_user() -> str:
+    return console.input("[bold cyan]❯[/] ")

obsidian_agent_cli_app-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: obsidian-agent-cli-app
+Version: 0.1.0
+Summary: A conversational AI agent for your Obsidian vault, connected via MCP.
+License: MIT
+License-File: LICENCE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp==2.8.1
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: obsidian-mcp>=2.1.6
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic<2.12,>=2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# obsidian-agent
+
+A conversational AI agent for your Obsidian vault. Ask it to find notes,
+summarize what you wrote last week, fix broken links, tag things, or
+edit a note — it figures out which vault operations to run and does it,
+chaining multiple steps together when needed.
+
+Built on [MCP](https://modelcontextprotocol.io) (the same protocol Claude
+Desktop uses for tool access) and [OpenRouter](https://openrouter.ai) for
+the LLM, so you can point it at whichever model you like.
+
+## Requirements
+
+- Python 3.11+
+- An [OpenRouter](https://openrouter.ai/keys) API key (free tier available)
+- An Obsidian vault on your local filesystem
+
+## Install
+
+```bash
+pip install git+https://github.com/ZedoMak/obsidian-agent.git
+```
+
+This pulls in `obsidian-mcp` (the vault-access server) automatically —
+no separate install step needed.
+
+## First run
+
+```bash
+obsidian-agent
+```
+
+You'll be asked three things once, and never again:
+
+- your OpenRouter API key
+- the absolute path to your vault
+- which model to use (defaults to a free-tier model if you're not sure)
+
+This gets saved to `~/.config/obsidian-agent/config.toml`. Change it later
+with `obsidian-agent config --reset`, or override any single value with an
+environment variable: `OPENROUTER_API_KEY`, `OBSIDIAN_VAULT_PATH`, `AGENT_MODEL`.
+
+## Usage
+
+```bash
+obsidian-agent          # start chatting with your vault
+obsidian-agent doctor   # troubleshooting: checks obsidian-mcp is installed
+                         # and can actually reach your vault
+obsidian-agent config   # view current config
+```
+
+Inside a chat session:
+
+| Command  | Does                                          |
+| -------- | --------------------------------------------- |
+| `/help`  | list commands                                 |
+| `/tools` | list every vault operation the agent can call |
+| `/clear` | wipe conversation history, start fresh        |
+| `/exit`  | quit (also: `exit`, `quit`, Ctrl+D)           |
+
+## What it can actually do
+
+Anything the underlying `obsidian-mcp` server exposes — reading, creating,
+editing, and deleting notes; searching by text, tag, date, or regex;
+managing tags; finding backlinks and broken links; listing orphaned notes.
+Run `/tools` inside a session to see the live list for your installed version.
+
+The agent always reads a note before editing it, so it won't blindly
+overwrite content — this is a system-level instruction, not something you
+need to ask for each time.
+
+## Troubleshooting
+
+**`obsidian-mcp was not found on your PATH`**
+Run `obsidian-agent doctor` — it'll tell you exactly what's missing and how
+to fix it.
+
+**Something else broke**
+This project pins a few dependency versions deliberately
+(`fastmcp==2.8.1`, `pydantic<2.12`) because of real breaking changes
+upstream. If you're hacking on the source directly rather than using
+`pip install`, don't loosen those pins without checking `obsidian-agent doctor`
+still passes afterward.
+
+## Contributing
+
+Issues and PRs welcome. This is a young project — expect rough edges.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

obsidian_agent_cli_app-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+obsidian_agent/__init__.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+obsidian_agent/cli.py,sha256=IqyJtBUWFMQNWrNQcwmdU4okaM_V914bitZoxye3JkQ,1356
+obsidian_agent/config.py,sha256=H0iqS1rvqKLZkDOPWUh_I8zyLiHMG72k_Moeqopg6As,2016
+obsidian_agent/core.py,sha256=EnG8sgCAAMv9ZmSgq0caBbkK_dBZqy7pV8NTOHJsw_0,1713
+obsidian_agent/doctor.py,sha256=qH4sTBs5h0Rm89UK5wPvDCsjGkTAR4Pg3KCTFvTxOgY,2856
+obsidian_agent/loop.py,sha256=KMIatOJ2WzpJHiAo3XvlegXVksm41J0PUEXFJWbzu4A,5378
+obsidian_agent/ui.py,sha256=ELMfuG4IlT0StN4jCziZJibbJuDw4oK8KIpRYlCd-NI,3422
+obsidian_agent_cli_app-0.1.0.dist-info/METADATA,sha256=NMnAq83pkgOiofFttQr6qqtjEj-nxNrNlQMsP8gm7a4,3525
+obsidian_agent_cli_app-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+obsidian_agent_cli_app-0.1.0.dist-info/entry_points.txt,sha256=OGzPSLDZvRQGVmdqu9RJtD2wUvB7QdKgdZsdCNSYReg,58
+obsidian_agent_cli_app-0.1.0.dist-info/licenses/LICENCE,sha256=hZMBcHPqgQ9qHgCSKl9_HKpzVpV_HRS8D-G05n9PbP8,1064
+obsidian_agent_cli_app-0.1.0.dist-info/RECORD,,

obsidian_agent_cli_app-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

obsidian_agent_cli_app-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+obsidian-agent = obsidian_agent.cli:app

obsidian_agent_cli_app-0.1.0.dist-info/licenses/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZedoMak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.