obsidian-mcp-server 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.5] - 2025-06-20
+
+### Changed
+
+- **Tool Renaming**: Renamed the `obsidian_update_file` tool to `obsidian_update_note` to avoid conflicts and better reflect its function. During agentic use, LLMs confused this tool with filesystem operations, leading to errors. The new name clarifies that it operates on Obsidian notes specifically.
+- **HTTP Transport Refactor**: Restructured the HTTP transport layer for improved clarity and robustness. Authentication logic is now more modular, and a centralized error handler has been implemented.
+- **Dependency Updates**: Updated all dependencies to their latest versions.
+- **Documentation Improvements**: Enhanced the documentation around installation & MCP Client configuration. Suggested by [@bgheneti](https://github.com/bgheneti) in [PR #14](https://github.com/cyanheads/obsidian-mcp-server/pull/14). Thanks!
+
+## [2.0.4] - 2025-06-13
+
+### Added
+
+- **Recursive File Listing**: The `obsidian_list_files` tool now supports recursive listing of directories with a `recursionDepth` parameter.
+
+### Changed
+
+- **Documentation**:
+  - Consolidated tool specifications into `obsidian_mcp_tools_spec.md`.
+  - Updated `.clinerules` with a detailed logger implementation example for the agent.
+  - Updated the repository's directory tree documentation.
+
 ## [2.0.3] - 2025-06-12
 
 ### Fixed

package/README.md

@@ -1,8 +1,8 @@
 # Obsidian MCP Server
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.1-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.0.3-blue.svg)](./CHANGELOG.md)
+[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-2.0.5-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Production-brightgreen.svg)](https://github.com/cyanheads/obsidian-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/obsidian-mcp-server?style=social)](https://github.com/cyanheads/obsidian-mcp-server)
@@ -20,7 +20,7 @@ This server equips your AI with specialized tools to interact with your Obsidian
 | Tool Name                                                                              | Description                                                     | Key Features                                                                                                                                           |
 | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`obsidian_read_file`](./src/mcp-server/tools/obsidianReadFileTool/)                   | Retrieves the content and metadata of a specified file.         | - Read in `markdown` or `json` format.<br/>- Case-insensitive path fallback.<br/>- Includes file stats (creation/modification time).                   |
-| [`obsidian_update_file`](./src/mcp-server/tools/obsidianUpdateFileTool/)               | Modifies notes using whole-file operations.                     | - `append`, `prepend`, or `overwrite` content.<br/>- Can create files if they don't exist.<br/>- Targets files by path, active note, or periodic note. |
+| [`obsidian_update_note`](./src/mcp-server/tools/obsidianUpdateNoteTool/)               | Modifies notes using whole-file operations.                     | - `append`, `prepend`, or `overwrite` content.<br/>- Can create files if they don't exist.<br/>- Targets files by path, active note, or periodic note. |
 | [`obsidian_search_replace`](./src/mcp-server/tools/obsidianSearchReplaceTool/)         | Performs search-and-replace operations within a target note.    | - Supports string or regex search.<br/>- Options for case sensitivity, whole word, and replacing all occurrences.                                      |
 | [`obsidian_global_search`](./src/mcp-server/tools/obsidianGlobalSearchTool/)           | Performs a search across the entire vault.                      | - Text or regex search.<br/>- Filter by path and modification date.<br/>- Paginated results.                                                           |
 | [`obsidian_list_files`](./src/mcp-server/tools/obsidianListFilesTool/)                 | Lists files and subdirectories within a specified vault folder. | - Filter by file extension or name regex.<br/>- Provides a formatted tree view of the directory.                                                       |
@@ -32,8 +32,8 @@ This server equips your AI with specialized tools to interact with your Obsidian
 
 ## Table of Contents
 
-| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
-| [Configuration](#configuration) | [Project Structure](#project-structure) | [Vault Cache Service](#vault-cache-service) |
+| [Overview](#overview) | [Features](#features) | [Configuration](#configuration) |
+| [Project Structure](#project-structure) | [Vault Cache Service](#vault-cache-service) |
 | [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
 
 ## Overview
@@ -54,7 +54,7 @@ Built on the robust `mcp-ts-template`, this server provides a standardized, secu
 
 ### Core Utilities
 
-Leverages the robust utilities provided by the `mcp-ts-template`:
+Leverages the robust utilities provided by `cyanheads/mcp-ts-template`:
 
 - **Logging**: Structured, configurable logging (file rotation, console, MCP notifications) with sensitive data redaction.
 - **Error Handling**: Centralized error processing, standardized error types (`McpError`), and automatic logging.
@@ -62,7 +62,7 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic.
 - **Request Context**: Tracking and correlation of operations via unique request IDs.
 - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
-- **HTTP Transport Option**: Built-in Hono server with SSE, session management, CORS support, and JWT authentication.
+- **HTTP Transport Option**: Built-in Hono server with SSE, session management, CORS support, and pluggable authentication strategies (JWT and OAuth 2.1).
 
 ### Obsidian Integration
 
@@ -82,52 +82,73 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 3.  **API Key**: Configure an API key within the Local REST API plugin settings in Obsidian. You will need this key to configure the server.
 4.  **Node.js & npm**: Ensure you have Node.js (v18 or later recommended) and npm installed.
 
-### Install via npm (Recommended)
+## Configuration
 
-```bash
-npm install obsidian-mcp-server
-```
+### MCP Client Settings
 
-### Install from Source
-
-1.  Clone the repository:
-    ```bash
-    git clone https://github.com/cyanheads/obsidian-mcp-server.git
-    cd obsidian-mcp-server
-    ```
-2.  Install dependencies:
-    ```bash
-    npm install
-    ```
-3.  Build the project:
-    ```bash
-    npm run build
-    ```
-    This compiles the TypeScript code to JavaScript in the `dist/` directory and makes the entry point executable.
+Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically download & install the package if not already present:
 
-## Configuration
+```json
+{
+  "mcpServers": {
+    "obsidian-mcp-server": {
+      "command": "npx",
+      "args": ["obsidian-mcp-server"],
+      "env": {
+        "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
+        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
+        "OBSIDIAN_VERIFY_SSL": "false",
+        "OBSIDIAN_ENABLE_CACHE": "true"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
 
-### Environment Variables
+**Note**: Verify SSL is set to false here because the Obsidian Local REST API plugin uses a self-signed certificate by default. If you are deploying this in a production environment, consider using the encrypted HTTPS endpoint and set `OBSIDIAN_VERIFY_SSL` to `true` after configuring your server to trust the self-signed certificate.
 
-Configure the server using environment variables.
+If you installed from source, change `command` and `args` to point to your local build:
 
-These variables must be set in the MCP client configuration (e.g., `cline_mcp_settings.json`) or in your environment before starting the server (if running directly).
+```json
+{
+  "mcpServers": {
+    "obsidian-mcp-server": {
+      "command": "node",
+      "args": ["/path/to/your/obsidian-mcp-server/dist/index.js"],
+      "env": {
+        "OBSIDIAN_API_KEY": "YOUR_OBSIDIAN_API_KEY",
+        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
+        "OBSIDIAN_VERIFY_SSL": "false",
+        "OBSIDIAN_ENABLE_CACHE": "true"
+      }
+    }
+  }
+}
+```
 
-If running directly, they can be set in a `.env` file in the project root or directly in your environment.
+### Environment Variables
 
-| Variable                              | Description                                               | Required          | Default                  |
-| :------------------------------------ | :-------------------------------------------------------- | :---------------- | :----------------------- |
-| **`OBSIDIAN_API_KEY`**                | API Key from the Obsidian Local REST API plugin.          | **Yes**           | `undefined`              |
-| **`OBSIDIAN_BASE_URL`**               | Base URL of your Obsidian Local REST API.                 | **Yes**           | `http://127.0.0.1:27123` |
-| `MCP_TRANSPORT_TYPE`                  | Server transport: `stdio` or `http`.                      | No                | `stdio`                  |
-| `MCP_HTTP_PORT`                       | Port for the HTTP server.                                 | No                | `3010`                   |
-| `MCP_HTTP_HOST`                       | Host for the HTTP server.                                 | No                | `127.0.0.1`              |
-| `MCP_ALLOWED_ORIGINS`                 | Comma-separated origins for CORS. **Set for production.** | No                | (none)                   |
-| **`MCP_AUTH_SECRET_KEY`**             | 32+ char secret for JWT auth. **Required for HTTP.**      | **Yes (if HTTP)** | `undefined`              |
-| `MCP_LOG_LEVEL`                       | Logging level (`debug`, `info`, `error`, etc.).           | No                | `info`                   |
-| `OBSIDIAN_VERIFY_SSL`                 | Set to `false` to disable SSL verification.               | No                | `true`                   |
-| `OBSIDIAN_ENABLE_CACHE`               | Set to `true` to enable the in-memory vault cache.        | No                | `true`                   |
-| `OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN` | Refresh interval for the vault cache in minutes.          | No                | `10`                     |
+Configure the server using environment variables. These environmental variables are set within your MCP client config/settings (e.g. `cline_mcp_settings.json` for Cline, `claude_desktop_config.json` for Claude Desktop).
+
+| Variable                              | Description                                                              | Required             | Default                  |
+| :------------------------------------ | :----------------------------------------------------------------------- | :------------------- | :----------------------- |
+| **`OBSIDIAN_API_KEY`**                | API Key from the Obsidian Local REST API plugin.                         | **Yes**              | `undefined`              |
+| **`OBSIDIAN_BASE_URL`**               | Base URL of your Obsidian Local REST API.                                | **Yes**              | `http://127.0.0.1:27123` |
+| `MCP_TRANSPORT_TYPE`                  | Server transport: `stdio` or `http`.                                     | No                   | `stdio`                  |
+| `MCP_HTTP_PORT`                       | Port for the HTTP server.                                                | No                   | `3010`                   |
+| `MCP_HTTP_HOST`                       | Host for the HTTP server.                                                | No                   | `127.0.0.1`              |
+| `MCP_ALLOWED_ORIGINS`                 | Comma-separated origins for CORS. **Set for production.**                | No                   | (none)                   |
+| `MCP_AUTH_MODE`                       | Authentication strategy: `jwt` or `oauth`.                               | No                   | (none)                   |
+| **`MCP_AUTH_SECRET_KEY`**             | 32+ char secret for JWT. **Required for `jwt` mode.**                    | **Yes (if `jwt`)**   | `undefined`              |
+| `OAUTH_ISSUER_URL`                    | URL of the OAuth 2.1 issuer.                                             | **Yes (if `oauth`)** | `undefined`              |
+| `OAUTH_AUDIENCE`                      | Audience claim for OAuth tokens.                                         | **Yes (if `oauth`)** | `undefined`              |
+| `OAUTH_JWKS_URI`                      | URI for the JSON Web Key Set (optional, derived from issuer if omitted). | No                   | (derived)                |
+| `MCP_LOG_LEVEL`                       | Logging level (`debug`, `info`, `error`, etc.).                          | No                   | `info`                   |
+| `OBSIDIAN_VERIFY_SSL`                 | Set to `false` to disable SSL verification.                              | No                   | `true`                   |
+| `OBSIDIAN_ENABLE_CACHE`               | Set to `true` to enable the in-memory vault cache.                       | No                   | `true`                   |
+| `OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN` | Refresh interval for the vault cache in minutes.                         | No                   | `10`                     |
 
 ### Connecting to the Obsidian API
 
@@ -165,27 +186,6 @@ _Using the encrypted HTTPS URL:_
 }
 ```
 
-### MCP Client Settings
-
-Add to your MCP client settings (e.g., `cline_mcp_settings.json`):
-
-```json
-{
-  "mcpServers": {
-    "obsidian-mcp-server": {
-      "command": "node",
-      "args": ["/path/to/your/obsidian-mcp-server/dist/index.js"],
-      "env": {
-        "OBSIDIAN_API_KEY": "YOUR_OBSIDIAN_API_KEY",
-        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
-        "OBSIDIAN_VERIFY_SSL": "false",
-        "OBSIDIAN_ENABLE_CACHE": "true"
-      }
-    }
-  }
-}
-```
-
 ## Project Structure
 
 The codebase follows a modular structure within the `src/` directory:
@@ -199,7 +199,8 @@ src/
 │   ├── server.ts      # Server setup, transport handling, tool/resource registration
 │   ├── resources/     # MCP Resource implementations (currently none)
 │   ├── tools/         # MCP Tool implementations (subdirs per tool)
-│   └── transports/    # Stdio and HTTP transport logic, auth middleware
+│   └── transports/    # Stdio and HTTP transport logic
+│       └── auth/      # Authentication strategies (JWT, OAuth)
 ├── services/          # Abstractions for external APIs or internal caching
 │   └── obsidianRestAPI/ # Typed client for Obsidian Local REST API
 ├── types-global/      # Shared TypeScript type definitions (errors, etc.)
@@ -239,7 +240,7 @@ The Obsidian MCP Server provides a suite of tools for interacting with your vaul
 | Tool Name                     | Description                                               | Key Arguments                                                 |
 | :---------------------------- | :-------------------------------------------------------- | :------------------------------------------------------------ |
 | `obsidian_read_file`          | Retrieves the content and metadata of a file.             | `filePath`, `format?`, `includeStat?`                         |
-| `obsidian_update_file`        | Modifies a file by appending, prepending, or overwriting. | `targetType`, `content`, `targetIdentifier?`, `wholeFileMode` |
+| `obsidian_update_note`        | Modifies a file by appending, prepending, or overwriting. | `targetType`, `content`, `targetIdentifier?`, `wholeFileMode` |
 | `obsidian_search_replace`     | Performs search-and-replace operations in a note.         | `targetType`, `replacements`, `useRegex?`, `replaceAll?`      |
 | `obsidian_global_search`      | Searches the entire vault for content.                    | `query`, `searchInPath?`, `useRegex?`, `page?`, `pageSize?`   |
 | `obsidian_list_files`         | Lists files and subdirectories in a folder.               | `dirPath`, `fileExtensionFilter?`, `nameRegexFilter?`         |
@@ -259,32 +260,23 @@ This server currently focuses on providing interactive tools for vault manipulat
 
 ### Build and Test
 
+To get started with development, clone the repository, install dependencies, and use the following scripts:
+
 ```bash
-# Build the project (compile TS to JS in dist/ and make executable)
-npm run build
+# Install dependencies
+npm install
 
-# Format code using Prettier
-npm run format
+# Build the project (compile TS to JS in dist/ and make executable)
+npm run rebuild
 
-# Test the server locally using stdio transport
-npm start
-# or specifically:
-npm run start:stdio
+# Start the server locally using stdio transport
+npm start:stdio
 
-# Test the server locally using http transport
+# Start the server using http transport
 npm run start:http
 
-# Generate a file tree representation for documentation (runs scripts/tree.ts)
-npm run tree
-
-# Clean build artifacts and then rebuild the project
-npm run rebuild
-
-# Fetch the Obsidian API spec (requires Obsidian running with Local REST API)
-npm run fetch:spec http://127.0.0.1:27123/ docs/obsidian-api/obsidian_rest_api_spec
-
-# Generate API documentation using TypeDoc
-npm run docs:generate
+# Format code using Prettier
+npm run format
 
 # Inspect the server's capabilities using the MCP Inspector tool
 npm run inspect:stdio

package/dist/mcp-server/server.js

@@ -24,7 +24,7 @@ import { registerObsidianGlobalSearchTool } from "./tools/obsidianGlobalSearchTo
 import { registerObsidianListFilesTool } from "./tools/obsidianListFilesTool/index.js";
 import { registerObsidianReadFileTool } from "./tools/obsidianReadFileTool/index.js";
 import { registerObsidianSearchReplaceTool } from "./tools/obsidianSearchReplaceTool/index.js";
-import { registerObsidianUpdateFileTool } from "./tools/obsidianUpdateFileTool/index.js";
+import { registerObsidianUpdateNoteTool } from "./tools/obsidianUpdateNoteTool/index.js";
 import { registerObsidianManageFrontmatterTool } from "./tools/obsidianManageFrontmatterTool/index.js";
 import { registerObsidianManageTagsTool } from "./tools/obsidianManageTagsTool/index.js";
 // Import transport setup functions.
@@ -93,7 +93,7 @@ async function createMcpServerInstance(obsidianService, vaultCacheService) {
             logger.warning("Skipping registration of 'obsidian_global_search' because the Vault Cache Service is disabled.", context);
         }
         await registerObsidianSearchReplaceTool(server, obsidianService, vaultCacheService);
-        await registerObsidianUpdateFileTool(server, obsidianService, vaultCacheService);
+        await registerObsidianUpdateNoteTool(server, obsidianService, vaultCacheService);
         await registerObsidianManageFrontmatterTool(server, obsidianService, vaultCacheService);
         await registerObsidianManageTagsTool(server, obsidianService, vaultCacheService);
         logger.info("Resources and tools registered successfully", context);

package/dist/mcp-server/tools/obsidianListFilesTool/logic.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Core logic for the 'obsidian_list_files' tool.
+ * This module defines the input schema, response types, and processing logic for
+ * recursively listing files and directories in an Obsidian vault with filtering.
+ * @module src/mcp-server/tools/obsidianListFilesTool/logic
+ */
 import { z } from "zod";
 import { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
 import { RequestContext } from "../../../utils/index.js";
@@ -7,58 +13,56 @@ import { RequestContext } from "../../../utils/index.js";
 export declare const ObsidianListFilesInputSchema: z.ZodObject<{
     /**
      * The vault-relative path to the directory whose contents should be listed.
-     * Examples: "Attachments/Images", "Projects", "" (for vault root), "/" (for vault root).
      * The path is treated as case-sensitive by the underlying Obsidian API.
      */
     dirPath: z.ZodString;
     /**
      * Optional array of file extensions (including the leading dot) to filter the results.
-     * Only files matching one of these extensions will be included. Directories are always included regardless of this filter.
-     * Example: [".md", ".png"]
+     * Only files matching one of these extensions will be included. Directories are always included.
      */
     fileExtensionFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     /**
      * Optional JavaScript-compatible regular expression pattern string to filter results by name.
      * Only files and directories whose names match the regex will be included.
-     * Example: "^\\d{4}-\\d{2}-\\d{2}" (matches names starting with YYYY-MM-DD)
      */
     nameRegexFilter: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /**
+     * The maximum depth of subdirectories to list recursively.
+     * - A value of `0` lists only the files and directories in the specified `dirPath`.
+     * - A value of `1` lists the contents of `dirPath` and the contents of its immediate subdirectories.
+     * - A value of `-1` (the default) indicates infinite recursion, listing all subdirectories.
+     */
+    recursionDepth: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     dirPath: string;
+    recursionDepth: number;
     fileExtensionFilter?: string[] | undefined;
     nameRegexFilter?: string | null | undefined;
 }, {
     dirPath: string;
     fileExtensionFilter?: string[] | undefined;
     nameRegexFilter?: string | null | undefined;
+    recursionDepth?: number | undefined;
 }>;
 /**
  * TypeScript type inferred from the input schema (`ObsidianListFilesInputSchema`).
- * Represents the validated input parameters used within the core processing logic.
  */
 export type ObsidianListFilesInput = z.infer<typeof ObsidianListFilesInputSchema>;
 /**
- * Defines the structure of the successful response returned by the `processObsidianListFiles` function.
- * This object is typically serialized to JSON and sent back to the client.
+ * Defines the structure of the successful response returned by the core logic function.
  */
 export interface ObsidianListFilesResponse {
-    /** The vault-relative path of the directory whose contents were listed (normalized, e.g., "/" for root). */
     directoryPath: string;
-    /** A string representation of the directory contents formatted as a simple tree structure. */
     tree: string;
-    /** The total number of files and directories included in the formatted tree after filtering. */
     totalEntries: number;
 }
 /**
- * Processes the core logic for listing files and directories within a specified
- * directory in the Obsidian vault. Applies optional filters and formats the output.
+ * Processes the core logic for listing files and directories recursively within the Obsidian vault.
  *
  * @param {ObsidianListFilesInput} params - The validated input parameters.
  * @param {RequestContext} context - The request context for logging and correlation.
  * @param {ObsidianRestApiService} obsidianService - An instance of the Obsidian REST API service.
- * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response
- *   containing the listed directory path, a formatted tree string, and the total entry count.
- * @throws {McpError} Throws an McpError if the directory cannot be listed (e.g., not found)
- *   or if any other API interaction or validation fails.
+ * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response.
+ * @throws {McpError} Throws an McpError if the initial directory is not found or another error occurs.
  */
 export declare const processObsidianListFiles: (params: ObsidianListFilesInput, context: RequestContext, obsidianService: ObsidianRestApiService) => Promise<ObsidianListFilesResponse>;