obsidian-mcp-server 1.2.6 → 1.4.0

package/examples/find-in-file.md

@@ -0,0 +1,94 @@
+# Find in File Tool Example
+
+## Request 1 (Many Results)
+```json
+{
+  "query": "tags:",
+  "contextLength": 20
+}
+```
+
+## Response 1
+```json
+{
+  "message": "Found 34 files with matches. Showing file names only:",
+  "results": [
+    {
+      "filename": "Projects/Project Alpha/Documentation/Requirements.md",
+      "matchCount": 1
+    },
+    {
+      "filename": "Projects/Project Beta/Specifications.md",
+      "matchCount": 2
+    },
+    {
+      "filename": "Daily Notes/2024-01-25.md",
+      "matchCount": 1
+    }
+  ]
+}
+```
+
+## Request 2 (Few Results)
+```json
+{
+  "query": "priority: high",
+  "contextLength": 50
+}
+```
+
+## Response 2
+```json
+{
+  "results": [
+    {
+      "filename": "Projects/Project Alpha/tasks.md",
+      "matches": [
+        {
+          "line": 15,
+          "content": "---\ntitle: Critical Tasks\ntags: [tasks, urgent]\npriority: high\n---\n\n# High Priority Tasks",
+          "matchStart": 45,
+          "matchEnd": 57
+        }
+      ]
+    },
+    {
+      "filename": "Areas/Work/Deadlines.md",
+      "matches": [
+        {
+          "line": 8,
+          "content": "## Q1 Deliverables\n- [ ] Feature launch (priority: high)\n- [ ] Security audit",
+          "matchStart": 35,
+          "matchEnd": 47
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Example Use Cases
+
+1. **Content Search**
+   - Find notes with specific tags or properties
+   - Search for keywords across the vault
+   - Locate specific metadata patterns
+
+2. **Task Management**
+   - Find high-priority tasks
+   - Search for incomplete items
+   - Locate notes with specific status
+
+3. **Knowledge Discovery**
+   - Find related content across notes
+   - Search for specific topics or references
+   - Identify patterns in note metadata
+
+## Notes
+- Returns either file list or detailed matches based on result count
+- Provides line numbers for precise location
+- Shows surrounding context for each match
+- Context length is customizable
+- Supports searching in frontmatter and note content
+- Results include match position information
+- Can search across all vault files

package/examples/get-file-contents.md

@@ -0,0 +1,72 @@
+# Get File Contents Tool Example
+
+## Request
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md"
+}
+```
+
+## Response
+```markdown
+---
+title: Project Requirements
+tags: [project, requirements, documentation]
+status: [in-progress]
+created: 2024-01-20
+modified: 2024-01-25
+---
+
+# Project Requirements Document
+
+## Overview
+This document outlines the key requirements for Project Alpha.
+
+## Features
+1. User Authentication
+   - [ ] Login system
+   - [ ] Password recovery
+   - [ ] Two-factor authentication
+
+2. Data Management
+   - [ ] Database integration
+   - [ ] Backup system
+   - [x] Data validation
+
+## Related Documents
+- [[Architecture Overview]]
+- [[Technical Specifications]]
+- [[Meeting Notes/Kickoff Meeting]]
+
+## References
+![[project-diagram.png]]
+
+#project-alpha #documentation #requirements
+```
+
+## Example Use Cases
+
+1. **Content Retrieval**
+   - Access note contents for reading or processing
+   - Extract metadata from YAML frontmatter
+   - Parse markdown formatting
+
+2. **Document Analysis**
+   - Review document structure
+   - Extract links and references
+   - Process task lists and status
+
+3. **Integration**
+   - Import content into other systems
+   - Process notes programmatically
+   - Extract specific sections or metadata
+
+## Notes
+- Returns raw markdown content including YAML frontmatter
+- Preserves all formatting, links, and special syntax
+- Handles various Obsidian-specific markdown features:
+  * Wiki-style links: [[Page Name]]
+  * Tags: #tag-name
+  * Embedded content: ![[file.png]]
+  * Task lists: - [ ] todo item
+- File path is relative to vault root

package/examples/get-properties.md

@@ -0,0 +1,89 @@
+# Get Properties Tool Example
+
+## Request
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md"
+}
+```
+
+## Response
+```json
+{
+  "properties": {
+    "title": "Project Requirements",
+    "tags": ["project", "requirements", "documentation"],
+    "status": ["in-progress"],
+    "created": "2024-01-20",
+    "modified": "2024-01-25",
+    "type": ["technical", "specification"],
+    "author": "Team Lead",
+    "version": "1.0",
+    "reviewers": ["Tech Lead", "Product Manager"],
+    "priority": "high"
+  }
+}
+```
+
+## Example Use Cases
+
+1. **Metadata Management**
+   - Extract note properties
+   - Review document metadata
+   - Track document status
+
+2. **Content Organization**
+   - Get tags for categorization
+   - Check document status
+   - Review creation/modification dates
+
+3. **Project Tracking**
+   - Monitor document versions
+   - Track review status
+   - Identify document owners
+
+## Notes
+- Extracts YAML frontmatter from markdown files
+- Returns structured JSON object
+- Supports various property types:
+  * Strings
+  * Arrays
+  * Dates
+  * Numbers
+  * Boolean values
+- Common properties:
+  * title: Document title
+  * tags: Categorization tags
+  * status: Document status
+  * created/modified: Timestamps
+  * type: Content type
+  * author: Content creator
+  * version: Document version
+  * custom fields: Any additional metadata
+
+## Property Types
+1. **Basic Properties**
+   ```yaml
+   title: "Document Title"
+   author: "John Doe"
+   version: 1.0
+   ```
+
+2. **Array Properties**
+   ```yaml
+   tags: [project, documentation]
+   status: [draft, review]
+   reviewers: [Alice, Bob]
+   ```
+
+3. **Date Properties**
+   ```yaml
+   created: 2024-01-20
+   due: 2024-02-01
+   ```
+
+4. **Custom Properties**
+   ```yaml
+   priority: high
+   department: Engineering
+   confidential: true

package/examples/list-files-in-dir.md

@@ -0,0 +1,55 @@
+# List Files in Directory Tool Example
+
+## Request
+```json
+{
+  "dirpath": "Projects/Project Alpha"
+}
+```
+
+## Response
+```
+Documentation/
+  Documentation/Requirements.md
+  Documentation/Architecture.md
+Notes/
+  Notes/Meeting Notes.md
+  Notes/Research.md
+Resources/
+  Resources/Images/
+  Resources/References/
+tasks.md
+timeline.md
+```
+
+## Example Use Cases
+
+1. **Project Organization**
+   - Browse project-specific files and folders
+   - Navigate through project documentation
+   - Find relevant project resources
+
+2. **Content Discovery**
+   - Locate specific project documents
+   - Access meeting notes and research
+   - Review project structure
+
+3. **Knowledge Management**
+   - Organize project materials
+   - Track project documentation
+   - Maintain clear folder hierarchies
+
+## Notes
+- Returns contents of a specific directory path
+- Shows both subdirectories and files
+- Directory paths end with a forward slash (/)
+- Results are alphabetically sorted
+- Empty directories are included in the results
+- Path is relative to vault root
+
+## Common Directory Structures
+The example shows a typical project organization:
+- Documentation/ - Project requirements and architecture
+- Notes/ - Meeting notes and research findings
+- Resources/ - Project assets and references
+- Root level files for quick access to important information

package/examples/list-files-in-vault.md

@@ -0,0 +1,53 @@
+# List Files in Vault Tool Example
+
+## Request
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+## Response
+```
+Areas/
+  Areas/Work/
+  Areas/Personal/
+  Areas/Projects/
+Resources/
+  Resources/Templates/
+  Resources/Attachments/
+Daily Notes/
+  Daily Notes/2024-01-25.md
+Projects/
+  Projects/Project Alpha/
+  Projects/Project Beta/
+Archive/
+README.md
+index.md
+```
+
+## Example Use Cases
+
+1. **Vault Organization**
+   - Get a complete overview of your vault structure
+   - Identify main areas and categories
+   - Plan content organization
+
+2. **Content Management**
+   - Find important directories and files
+   - Review vault hierarchy
+   - Locate specific resources
+
+3. **Navigation**
+   - Quick access to key areas
+   - Browse through project directories
+   - Find templates and resources
+
+## Notes
+- The tool returns both files and directories at the root level
+- Directory paths end with a forward slash (/)
+- File extensions are preserved in the output
+- Results are alphabetically sorted
+- Special characters in filenames are preserved
+- Provides a hierarchical view of your vault structure

package/examples/patch-content.md

@@ -0,0 +1,60 @@
+# Patch Content Tool Example
+
+## Request 1 (Update Existing Note)
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Architecture.md",
+  "content": "---\ntitle: System Architecture\ntags: [architecture, documentation]\nstatus: [complete]\nmodified: 2024-01-25\n---\n\n# System Architecture\n\n## Overview\nThis document describes the high-level architecture of Project Alpha.\n\n## Components\n\n### Frontend\n- React-based web application\n- Material UI components\n- Redux state management\n\n### Backend\n- Node.js REST API\n- PostgreSQL database\n- Redis caching layer\n\n### Infrastructure\n- AWS cloud hosting\n- Docker containerization\n- CI/CD pipeline\n\n## System Diagram\n![[architecture-diagram.png]]\n\n## Integration Points\n- Authentication service\n- Payment processing\n- Email service\n- Analytics platform\n\n#project-alpha #architecture #technical"
+}
+```
+
+## Response 1
+```json
+{
+  "success": true,
+  "message": "File content updated successfully"
+}
+```
+
+## Request 2 (Create New Note)
+```json
+{
+  "filepath": "Templates/Meeting Note.md",
+  "content": "---\ntitle: {{title}}\ndate: {{date}}\nattendees: \ntags: [meeting]\nstatus: [draft]\n---\n\n# {{title}}\n\n## Agenda\n1. \n2. \n3. \n\n## Discussion Points\n- \n\n## Decisions\n- \n\n## Action Items\n- [ ] \n- [ ] \n- [ ] \n\n## Next Steps\n- \n\n## Notes\n- "
+}
+```
+
+## Response 2
+```json
+{
+  "success": true,
+  "message": "File created successfully"
+}
+```
+
+## Example Use Cases
+
+1. **Document Updates**
+   - Complete revision of documentation
+   - Update outdated content
+   - Replace temporary content with final version
+
+2. **Template Creation**
+   - Create note templates
+   - Define standardized formats
+   - Set up reusable structures
+
+3. **Content Migration**
+   - Move and reformat content
+   - Update note structure
+   - Implement new organization systems
+
+## Notes
+- Replaces entire file content or creates new file
+- Supports YAML frontmatter
+- Handles template variables
+- Preserves markdown formatting
+- Creates parent directories if needed
+- Validates content structure
+- File path is relative to vault root
+- Useful for major content revisions

package/examples/update-properties.md

@@ -0,0 +1,126 @@
+# Update Properties Tool Example
+
+## Request 1 (Update Multiple Properties)
+```json
+{
+  "filepath": "Projects/Project Alpha/Documentation/Requirements.md",
+  "properties": {
+    "status": ["in-review"],
+    "tags": ["project", "requirements", "documentation", "technical"],
+    "modified": "2024-01-25",
+    "reviewers": ["Tech Lead", "Product Manager", "Security Team"],
+    "version": "1.1"
+  }
+}
+```
+
+## Response 1
+```json
+{
+  "success": true,
+  "message": "Properties updated successfully"
+}
+```
+
+## Request 2 (Merge Array Properties)
+```json
+{
+  "filepath": "Projects/Project Beta/Specifications.md",
+  "properties": {
+    "tags": ["api", "backend"],
+    "status": ["draft"]
+  },
+  "replace": false
+}
+```
+
+## Response 2
+```json
+{
+  "success": true,
+  "message": "Properties merged successfully"
+}
+```
+
+## Example Use Cases
+
+1. **Document Management**
+   - Update document status
+   - Add or remove tags
+   - Track document versions
+   - Manage review process
+
+2. **Project Tracking**
+   - Update task status
+   - Assign reviewers
+   - Track modifications
+   - Version control
+
+3. **Content Organization**
+   - Categorize content
+   - Update metadata
+   - Manage document lifecycle
+   - Track document history
+
+## Notes
+- Updates YAML frontmatter properties
+- Supports property merging or replacement
+- Handles various property types:
+  * Strings
+  * Arrays
+  * Dates
+  * Numbers
+  * Boolean values
+- Preserves existing properties not specified in update
+- Automatically updates modified timestamp
+- Creates properties if they don't exist
+
+## Property Handling
+
+1. **Array Merging (replace: false)**
+```yaml
+# Original
+tags: [project, draft]
+status: [review]
+
+# Update
+tags: [technical, draft]
+status: [complete]
+
+# Result
+tags: [project, draft, technical]
+status: [review, complete]
+```
+
+2. **Array Replacement (replace: true)**
+```yaml
+# Original
+reviewers: [Alice, Bob]
+tags: [draft]
+
+# Update (replace: true)
+reviewers: [Charlie]
+tags: [final]
+
+# Result
+reviewers: [Charlie]
+tags: [final]
+```
+
+3. **Property Types**
+```yaml
+# String properties
+title: "Updated Title"
+author: "New Author"
+
+# Date properties
+modified: 2024-01-25
+due: 2024-02-01
+
+# Number properties
+version: 2.0
+priority: 1
+
+# Boolean properties
+published: true
+confidential: false

package/mcp-client-config.example.json

@@ -0,0 +1,23 @@
+{
+  "mcpServers": {
+    "obsidian-mcp-server": {
+      "command": "node",
+      "args": [
+        "/path/to/obsidian-mcp-server/build/index.js"
+      ],
+      "env": {
+        "OBSIDIAN_API_KEY": "your_api_key_here",
+        "VERIFY_SSL": "false",
+        "OBSIDIAN_PROTOCOL": "https",
+        "OBSIDIAN_HOST": "127.0.0.1",
+        "OBSIDIAN_PORT": "27124",
+        "REQUEST_TIMEOUT": "5000",
+        "MAX_CONTENT_LENGTH": "52428800",
+        "MAX_BODY_LENGTH": "52428800",
+        "RATE_LIMIT_WINDOW_MS": "900000",
+        "RATE_LIMIT_MAX_REQUESTS": "200",
+        "TOOL_TIMEOUT_MS": "60000"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "1.2.6",
+  "version": "1.4.0",
   "description": "Model Context Protocol server for Obsidian integration with token-aware response handling",
   "main": "build/index.js",
   "type": "module",
@@ -8,10 +8,11 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc && chmod +x build/index.js",
+    "build": "tsc",
+    "postbuild": "node -e \"if (process.platform !== 'win32') require('fs').chmodSync('build/index.js', '755')\"",
     "start": "node build/index.js",
     "dev": "tsc -w",
-    "clean": "rm -rf build",
+    "clean": "node -e \"require('fs').rmSync('build', { recursive: true, force: true })\"",
     "rebuild": "npm run clean && npm run build",
     "test": "echo \"No tests specified yet\" && exit 0",
     "lint": "eslint . --ext .ts",

package/src/index.ts

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
-import { run } from "./server.js";
+import { run } from "./mcp/server.js";
+import { createLogger } from "./utils/logging.js";
+
+// Create a logger for the main entry point
+const logger = createLogger('Main');
 
 // Main entry point
 if (import.meta.url === `file://${process.argv[1]}`) {
+  logger.info("Starting Obsidian MCP Server");
   run().catch((error) => {
-    console.error("Failed to start server:", error);
+    logger.error("Failed to start server:", error);
     process.exit(1);
   });
 }
 
-export { run };
+// Export the run function and other important modules
+export { run } from "./mcp/server.js";
+export * from "./obsidian/index.js";
+export * from "./tools/index.js";
+export * from "./resources/index.js";
+export * from "./utils/index.js";