@fazer-ai/mcp-obsidian 1.0.14 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Markus Pfundstein
+
+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.

package/README.md

@@ -12,166 +12,146 @@
 
 | Tool name | Description |
 |-----------|-------------|
-| **status** | Returns basic details about the Obsidian Local REST API server and your authentication status |
-| **delete_active** | Deletes the note that is currently active in the Obsidian UI |
-| **get_active** | Retrieves the full content of the active note (Markdown or JSON view) |
-| **patch_active** | Inserts, replaces or prepends content in the active note relative to a heading, block reference, or front-matter field |
-| **post_active** | Appends Markdown to the end of the active note |
-| **put_active** | Replaces the entire body of the active note |
-| **get_commands** | Lists every command available in Obsidian’s command palette |
-| **execute_command** | Executes a specific Obsidian command by its ID |
-| **open_file** | Opens the given file inside Obsidian (creates it if missing); optional flag to open in a new leaf |
-| **delete_periodic** | Deletes the current daily / weekly / monthly / quarterly / yearly note for the requested period |
-| **get_periodic** | Returns the content of the current periodic note for the requested period |
-| **patch_periodic** | Inserts / replaces content in a periodic note relative to a heading, block reference, or front-matter field |
-| **post_periodic** | Appends Markdown to the periodic note (creates it if it doesn’t exist) |
-| **put_periodic** | Replaces the entire body of a periodic note |
-| **search_dataview** | Runs a Dataview-DQL query across the vault and returns matching rows |
-| **search_json_logic** | Runs a JsonLogic query against structured note metadata |
-| **simple_search** | Performs a plain-text fuzzy search with optional surrounding context |
-| **list_vault_root** | Lists all files and directories at the **root** of your vault |
-| **list_vault_directory** | Lists files and directories inside a **specific folder** of the vault |
-| **delete_file** | Deletes a specific file (or directory) in the vault |
-| **get_file** | Retrieves the content of a file in the vault (Markdown or JSON view) |
-| **patch_file** | Inserts / replaces content in an arbitrary file relative to a heading, block reference, or front-matter field |
-| **post_file** | Appends Markdown to a file (creates it if it doesn’t exist) |
-| **put_file** | Creates a new file or replaces the entire body of an existing file |
-
-*See [Local REST API specifications](https://coddingtonbear.github.io/obsidian-local-rest-api) for more details.*
+| **obsidian_status** | Returns basic details about the Obsidian Local REST API server and your authentication status |
+| **obsidian_delete_active** | Deletes the note that is currently active in the Obsidian UI |
+| **obsidian_get_active** | Retrieves the full content of the active note (Markdown or JSON view) |
+| **obsidian_patch_active** | Inserts, replaces or prepends content in the active note relative to a heading, block reference, or front-matter field |
+| **obsidian_post_active** | Appends Markdown to the end of the active note |
+| **obsidian_put_active** | Replaces the entire body of the active note |
+| **obsidian_get_commands** | Lists every command available in Obsidian’s command palette |
+| **obsidian_execute_command** | Executes a specific Obsidian command by its ID |
+| **obsidian_open_file** | Opens the given file inside Obsidian (creates it if missing); optional flag to open in a new leaf |
+| **obsidian_delete_periodic** | Deletes the current daily / weekly / monthly / quarterly / yearly note for the requested period |
+| **obsidian_get_periodic** | Returns the content of the current periodic note for the requested period |
+| **obsidian_patch_periodic** | Inserts / replaces content in a periodic note relative to a heading, block reference, or front-matter field |
+| **obsidian_post_periodic** | Appends Markdown to the periodic note (creates it if it doesn’t exist) |
+| **obsidian_put_periodic** | Replaces the entire body of a periodic note |
+| **obsidian_search_dataview** | Runs a Dataview-DQL query across the vault and returns matching rows |
+| **obsidian_search_json_logic** | Runs a JsonLogic query against structured note metadata |
+| **obsidian_simple_search** | Performs a plain-text fuzzy search with optional surrounding context |
+| **obsidian_list_vault_root** | Lists all files and directories at the **root** of your vault |
+| **obsidian_list_vault_directory** | Lists files and directories inside a **specific folder** of the vault |
+| **obsidian_delete_file** | Deletes a specific file (or directory) in the vault |
+| **obsidian_get_file** | Retrieves the content of a file in the vault (Markdown or JSON view) |
+| **obsidian_patch_file** | Inserts / replaces content in an arbitrary file relative to a heading, block reference, or front-matter field |
+| **obsidian_post_file** | Appends Markdown to a file (creates it if it doesn’t exist) |
+| **obsidian_put_file** | Creates a new file or replaces the entire body of an existing file |
+
+*See Obsidian's [Local REST API specifications](https://coddingtonbear.github.io/obsidian-local-rest-api) for more details.*
 
 ---
 
 ### Example prompts
 
 ```text
-# Summarise the latest “architecture call” note
+# Summarize the latest “architecture call” note
 # (Claude will transparently call list_files_in_vault → get_file_contents)
-Get the contents of the last “architecture call” note and summarise them.
+Get the contents of the last “architecture call” note and summarize them.
 
 # Find all mentions of Cosmos DB
 Search for all files where “Azure CosmosDb” is mentioned and explain the context briefly.
 
 # Create a summary note
-Summarise yesterday’s meeting and save it as
-“summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.
+Summarize yesterday’s meeting and save it as “summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.
 ```
 
 ---
 
 ## ⚙️ Configuration
 
-### Environment variables
-
-Copy `.env.example` to `.env` and fill in your values:
-
-```bash
-PORT=3045           # TCP port the MCP server will listen on
-OBSIDIAN_API_KEY=   # Obtain this from the plugin settings in Obsidian
-OBSIDIAN_PROTOCOL=http
-OBSIDIAN_HOST=localhost
-OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
-```
-
 ### Obsidian REST API key
 
-You can supply the key either by:
+There are two ways to pass the Obsidian API key to the server:
 
 1. **Server config (recommended)** – pass it via the `env` field in your Claude (or other client) MCP-server declaration:
 
-   ```jsonc
-   {
-     "mcpServers": {
-       "mcp-obsidian-ts": {
-         "command": "bunx",
-         "args": ["mcp-obsidian-ts"],     // or the binary of your package
-         "env": {
-           "OBSIDIAN_API_KEY": "paste_key_here",
-           "OBSIDIAN_HOST": "localhost"
-         }
-       }
-     }
-   }
-   ```
-
-2. **`.env` file** – place the key in the `.env` you created above.
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "@fazer-ai/mcp-obsidian": {
+      "command": "bunx",
+      "args": ["@fazer-ai/mcp-obsidian@latest"],
+      "env": {
+        "OBSIDIAN_API_KEY": "your-obsidian-api-key"
+      }
+    }
+  }
+}
+```
 
----
+>[!NOTE]
+> Use `@fazer-ai/mcp-obsidian@latest` to ensure you always run the most up to date version of the server.
 
-## 🚀 Quickstart
+2. Alternatively, you can use an **`.env` file**. Place the key in the `.env` you created above. Note it must be placed in the working directory where the MCP server is running.
 
-### Prerequisites
 
-* **Bun** ≥ 1.1 → <https://bun.sh/docs/installation>  
-* Obsidian with the **Local REST API** plugin enabled.
+### Environment variables
 
-### Install & run
+You can use the `.env.example` file as reference to create your own `.env` file.
 
 ```bash
-# 1. Grab the package
-git clone https://github.com/your-org/mcp-obsidian-ts.git
-cd mcp-obsidian-ts
-bun install
-
-# 2. Configure env vars
-cp .env.example .env          # then edit as needed
-
-# 3. Launch the server
-bunx mcp-obsidian-ts          # starts on $PORT (default 3045)
-```
-
-When the server starts you should see:
-
-```
-▶ MCP server (obsidian) listening on http://localhost:3045
+PORT=3045           # TCP port the MCP server will listen on
+OBSIDIAN_API_KEY=   # Obtain this from the plugin settings in Obsidian
+OBSIDIAN_PROTOCOL=http
+OBSIDIAN_HOST=localhost
+OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
 ```
 
-Add / update the entry in your Claude Desktop or MCP-compatible client and you’re ready to chat with your vault.
-
 ---
 
 ## 🛠 Development
 
-### Scripts
+### Running local version on Claude Desktop
+
+After cloning this repo, you can update Claude's config to run your local version of the server instead of pulling from npm.
+This is useful for quickly testing changes before publishing.
+
+>[!NOTE]
+>Keep in mind any changes you make on the code will only take effect after restarting the Claude Desktop app.
+
+1. Clone this repo and run `bun install` to install dependencies.
+1. Update your `claude_desktop_config.json` to point to your local version of the server:
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "@fazer-ai/mcp-obsidian": {
+      "command": "bun",
+      "args": ["/path/to/repo/src/index.ts"],
+      "env": {
+        "OBSIDIAN_API_KEY": "your-obsidian-api-key"
+      }
+    }
+  }
+}
+```
 
-| Script | What it does |
-|--------|--------------|
-| `bun run dev` | Starts the server with live-reload (tsx) |
-| `bun run build` | Bundles to `dist/` (ESM) |
-| `bun test` | Runs unit tests (vitest) |
+>[!IMPORTANT]
+>Note we use `bun` instead of `bunx` here.
 
 ### Debugging
 
 MCP servers talk over **stdio**, so normal debuggers aren’t helpful.  
-Use the excellent **[MCP Inspector]**:
+Use the **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)**:
 
 ```bash
-npx @modelcontextprotocol/inspector bunx --directory /path/to/mcp-obsidian-ts run dev
+npx @modelcontextprotocol/inspector bun /path/to/repo/src/index.ts
 ```
 
-Open the URL it prints to step through requests, inspect tool calls, and watch logs in real time.  
-Alternatively, tail the log file written by Claude Desktop:
-
-```bash
-tail -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-ts.log
-```
+Open the URL it prints to step through requests (usually http://localhost:6274), inspect tool calls, and watch logs in real time.
 
 ---
 
 ## 📦 Publishing
 
-1. Run `bun run build`.
-2. `npm publish --access public` (or `np`, `release-it`, etc.).
-3. Update the badge URL at the top of this file with the server ID from <https://glama.ai/mcp>.
-
----
-
-### Licence
-
-MIT – see [LICENCE](LICENCE).
+1. Update the version in `package.json`.
+1. Create GitHub release.
+1. Run `bun publish`.
 
 ---
 
-**Happy note-wrangling!** 🗒️✨
-```
+## License
 
-*Tip:* If your project has its own name (e.g. **`mcp-obsidian-ts`**) just swap it in wherever you see a placeholder.
+MIT – see [LICENSE](LICENSE).

package/dist/index.js

@@ -123,7 +123,10 @@ class Obsidian {
       method: "POST"
     });
   }
-  openFile({ filename, newLeaf }) {
+  openFile({
+    filename,
+    newLeaf
+  }) {
     const qs = newLeaf ? "?newLeaf=true" : "";
     return this.fetch(`/open/${sanitizeAndEncodePath(filename)}${qs}`, {
       method: "POST"
@@ -4267,7 +4270,7 @@ var z = /* @__PURE__ */ Object.freeze({
 // src/tools.ts
 var obsidian = new Obsidian(config_default.obsidian);
 function registerTools(server) {
-  server.tool("status", "Returns basic details about the server.", async () => {
+  server.tool("obsidian_status", "Returns basic details about the server.", async () => {
     const status = await obsidian.status();
     return {
       content: [
@@ -4278,19 +4281,19 @@ function registerTools(server) {
       ]
     };
   });
-  server.tool("delete_active", "Deletes the currently-active file.", async () => {
+  server.tool("obsidian_delete_active", "Deletes the currently-active file.", async () => {
     await obsidian.deleteActive();
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("get_active", "Returns the content of the currently-active file.", async () => {
+  server.tool("obsidian_get_active", "Returns the content of the currently-active file.", async () => {
     const note = await obsidian.getActive();
     return {
       content: [{ type: "text", text: JSON.stringify(note) }]
     };
   });
-  server.tool("patch_active", "Inserts content into the active file relative to a target.", {
+  server.tool("obsidian_patch_active", "Inserts content into the active file relative to a target.", {
     operation: z.enum(["append", "prepend", "replace"]),
     targetType: z.enum(["heading", "block", "frontmatter"]),
     target: z.string(),
@@ -4304,19 +4307,19 @@ function registerTools(server) {
       content: [{ type: "text", text: JSON.stringify(res) }]
     };
   });
-  server.tool("post_active", "Appends content to the active file.", { content: z.string() }, async (args) => {
+  server.tool("obsidian_post_active", "Appends content to the active file.", { content: z.string() }, async (args) => {
     await obsidian.postActive(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("put_active", "Replaces content of the active file.", { content: z.string() }, async (args) => {
+  server.tool("obsidian_put_active", "Replaces content of the active file.", { content: z.string() }, async (args) => {
     await obsidian.putActive(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("get_commands", "Returns a list of available commands.", async () => {
+  server.tool("obsidian_get_commands", "Returns a list of available commands.", async () => {
     const commands = await obsidian.getCommands();
     return {
       content: [
@@ -4327,19 +4330,19 @@ function registerTools(server) {
       ]
     };
   });
-  server.tool("execute_command", "Executes a specified command.", { commandId: z.string() }, async (args) => {
+  server.tool("obsidian_execute_command", "Executes a specified command.", { commandId: z.string() }, async (args) => {
     await obsidian.executeCommand(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("open_file", "Opens a file, optionally in a new leaf.", { filename: z.string(), newLeaf: z.boolean() }, async (args) => {
+  server.tool("obsidian_open_file", "Opens a file, optionally in a new leaf.", { filename: z.string(), newLeaf: z.boolean().nullish() }, async (args) => {
     await obsidian.openFile(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("delete_periodic", "Deletes the periodic note for a given period.", {
+  server.tool("obsidian_delete_periodic", "Deletes the periodic note for a given period.", {
     period: z.enum(["daily", "weekly", "monthly", "quarterly", "yearly"])
   }, async (args) => {
     await obsidian.deletePeriodic(args);
@@ -4347,7 +4350,7 @@ function registerTools(server) {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("get_periodic", "Returns the periodic note for a given period.", {
+  server.tool("obsidian_get_periodic", "Returns the periodic note for a given period.", {
     period: z.enum(["daily", "weekly", "monthly", "quarterly", "yearly"])
   }, async (args) => {
     const note = await obsidian.getPeriodic(args);
@@ -4355,7 +4358,7 @@ function registerTools(server) {
       content: [{ type: "text", text: JSON.stringify(note) }]
     };
   });
-  server.tool("patch_periodic", "Inserts content into a periodic note relative to a target.", {
+  server.tool("obsidian_patch_periodic", "Inserts content into a periodic note relative to a target.", {
     period: z.enum(["daily", "weekly", "monthly", "quarterly", "yearly"]),
     operation: z.enum(["append", "prepend", "replace"]),
     targetType: z.enum(["heading", "block", "frontmatter"]),
@@ -4370,7 +4373,7 @@ function registerTools(server) {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("post_periodic", "Appends content to the periodic note.", {
+  server.tool("obsidian_post_periodic", "Appends content to the periodic note.", {
     period: z.enum(["daily", "weekly", "monthly", "quarterly", "yearly"]),
     content: z.string()
   }, async (args) => {
@@ -4379,7 +4382,7 @@ function registerTools(server) {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("put_periodic", "Replaces content of the periodic note.", {
+  server.tool("obsidian_put_periodic", "Replaces content of the periodic note.", {
     period: z.enum(["daily", "weekly", "monthly", "quarterly", "yearly"]),
     content: z.string()
   }, async (args) => {
@@ -4388,49 +4391,49 @@ function registerTools(server) {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("search_dataview", "Searches using a Dataview query.", { query: z.string() }, async (args) => {
+  server.tool("obsidian_search_dataview", "Searches using a Dataview query.", { query: z.string() }, async (args) => {
     const results = await obsidian.searchDataview(args);
     return {
       content: [{ type: "text", text: JSON.stringify(results) }]
     };
   });
-  server.tool("search_json_logic", "Searches using a JsonLogic query.", { logic: z.unknown() }, async ({ logic }) => {
+  server.tool("obsidian_search_json_logic", "Searches using a JsonLogic query.", { logic: z.unknown() }, async ({ logic }) => {
     const results = await obsidian.searchJsonLogic(logic);
     return {
       content: [{ type: "text", text: JSON.stringify(results) }]
     };
   });
-  server.tool("simple_search", "Searches for text in vault with optional context.", { query: z.string(), contextLength: z.number().optional() }, async (args) => {
+  server.tool("obsidian_simple_search", "Searches for text in vault with optional context.", { query: z.string(), contextLength: z.number().optional() }, async (args) => {
     const results = await obsidian.simpleSearch(args);
     return {
       content: [{ type: "text", text: JSON.stringify(results) }]
     };
   });
-  server.tool("list_vault_root", "Lists files in the root of the vault.", async () => {
+  server.tool("obsidian_list_vault_root", "Lists files in the root of the vault.", async () => {
     const files = await obsidian.listVaultRoot();
     return {
       content: [{ type: "text", text: JSON.stringify(files) }]
     };
   });
-  server.tool("list_vault_directory", "Lists files in a specified directory.", { pathToDirectory: z.string() }, async (args) => {
+  server.tool("obsidian_list_vault_directory", "Lists files in a specified directory.", { pathToDirectory: z.string() }, async (args) => {
     const files = await obsidian.listVaultDirectory(args);
     return {
       content: [{ type: "text", text: JSON.stringify(files) }]
     };
   });
-  server.tool("delete_file", "Deletes a file in the vault.", { filename: z.string() }, async (args) => {
+  server.tool("obsidian_delete_file", "Deletes a file in the vault.", { filename: z.string() }, async (args) => {
     await obsidian.deleteFile(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("get_file", "Returns content of a vault file.", { filename: z.string() }, async (args) => {
+  server.tool("obsidian_get_file", "Returns content of a vault file.", { filename: z.string() }, async (args) => {
     const file = await obsidian.getFile(args);
     return {
       content: [{ type: "text", text: JSON.stringify(file) }]
     };
   });
-  server.tool("patch_file", "Inserts content into a vault file relative to a target.", {
+  server.tool("obsidian_patch_file", "Inserts content into a vault file relative to a target.", {
     filename: z.string(),
     operation: z.enum(["append", "prepend", "replace"]),
     targetType: z.enum(["heading", "block", "frontmatter"]),
@@ -4445,13 +4448,13 @@ function registerTools(server) {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("post_file", "Appends content to a vault file.", { filename: z.string(), content: z.string() }, async (args) => {
+  server.tool("obsidian_post_file", "Appends content to a vault file.", { filename: z.string(), content: z.string() }, async (args) => {
     await obsidian.postFile(args);
     return {
       content: [{ type: "text", text: "OK" }]
     };
   });
-  server.tool("put_file", "Creates or replaces a vault file.", { filename: z.string(), content: z.string() }, async (args) => {
+  server.tool("obsidian_put_file", "Creates or replaces a vault file.", { filename: z.string(), content: z.string() }, async (args) => {
     await obsidian.putFile(args);
     return {
       content: [{ type: "text", text: "OK" }]
@@ -7169,7 +7172,7 @@ class StdioServerTransport {
 
 // package.json
 var name = "@fazer-ai/mcp-obsidian";
-var version = "1.0.14";
+var version = "1.1.0";
 
 // src/index.ts
 var server = new McpServer({ name, version }, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fazer-ai/mcp-obsidian",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "module": "src/index.ts",
   "main": "dist/index.js",
   "bin": "dist/index.js",