@fazer-ai/mcp-obsidian 1.0.9 → 1.0.11

package/README.md

@@ -1,20 +1,177 @@
-# mcp-obsidian
+# MCP server for Obsidian (TypeScript + Bun)
 
-To install dependencies:
+![NPM Version](https://img.shields.io/npm/v/%40fazer-ai%2Fmcp-obsidian)
+
+> A Model-Context-Protocol (MCP) server that lets Claude (or any MCP-compatible LLM) interact with your Obsidian vault through the [**Local REST API**](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin – written in **TypeScript** and runnable with **bunx**.
+
+---
+
+## ✨ Components
+
+### Tools
+
+| 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.*
+
+---
+
+### Example prompts
+
+```text
+# Summarise 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.
+
+# 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.
+```
+
+---
+
+## ⚙️ 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:
+
+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.
+
+---
+
+## 🚀 Quickstart
+
+### Prerequisites
+
+* **Bun** ≥ 1.1 → <https://bun.sh/docs/installation>  
+* Obsidian with the **Local REST API** plugin enabled.
+
+### Install & run
 
 ```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
+```
+
+Add / update the entry in your Claude Desktop or MCP-compatible client and you’re ready to chat with your vault.
+
+---
+
+## 🛠 Development
+
+### Scripts
+
+| 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) |
+
+### Debugging
+
+MCP servers talk over **stdio**, so normal debuggers aren’t helpful.  
+Use the excellent **[MCP Inspector]**:
+
+```bash
+npx @modelcontextprotocol/inspector bunx --directory /path/to/mcp-obsidian-ts run dev
 ```
 
-To run:
+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
-bun run index.ts
+tail -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-ts.log
 ```
 
-This project was created using `bun init` in bun v1.2.10. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+---
+
+## 📦 Publishing
 
-### TODO
+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).
+
+---
+
+**Happy note-wrangling!** 🗒️✨
+```
 
-- [ ] Write readme
-- [ ] Publish to npm (run with bunx, similar to mcp-inspector)
+*Tip:* If your project has its own name (e.g. **`mcp-obsidian-ts`**) just swap it in wherever you see a placeholder.

package/dist/index.js

@@ -7169,10 +7169,17 @@ class StdioServerTransport {
 
 // package.json
 var name = "@fazer-ai/mcp-obsidian";
-var version = "1.0.9";
+var version = "1.0.11";
 
 // src/index.ts
-var server = new McpServer({ name, version });
+var server = new McpServer({ name, version }, {
+  instructions: "This is a MCP server for Obsidian. It is a simple server that can be used to run commands and get responses from the client running Local REST API community plugin.",
+  capabilities: {
+    resources: {},
+    prompts: {},
+    tools: {}
+  }
+});
 registerTools(server);
 async function main() {
   const transport = new StdioServerTransport;

package/package.json

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