@manex/obsidianmcp 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +108 -77
  2. package/bin/index.js +13 -0
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,98 +1,129 @@
1
1
  # ObsidianMCP
2
2
 
3
- ObsidianMCP es un servidor Model Context Protocol (MCP) que permite interactuar con tu vault de Obsidian a través de herramientas expuestas como endpoints MCP. Está pensado para integraciones avanzadas, automatización y conexión con agentes de IA.
4
-
5
- ## ¿Qué hace esta herramienta?
6
-
7
- Permite:
8
-
9
- - Listar todas las notas de tu vault de Obsidian.
10
- - Leer el contenido de cualquier nota.
11
- - Crear nuevas notas.
12
- - Añadir contenido a notas existentes.
13
- - Eliminar notas.
14
- - Buscar notas por nombre o contenido.
15
- - Comprobar el estado de salud del servidor.
16
-
17
- Ideal para conectar Obsidian con asistentes inteligentes, automatizaciones o flujos de trabajo personalizados.
18
-
19
- ## Herramientas disponibles (tools)
3
+ A lightweight, secure Model Context Protocol (MCP) server for seamless Obsidian vault integration with AI assistants and automation tools.
4
+
5
+ Interact with your Obsidian vault through MCP-compatible clients like **Claude Desktop**, **VSCode**, or any other MCP-enabled application.
6
+
7
+ ## Features
8
+
9
+ - **List notes** - Browse your entire vault structure with folder hierarchy
10
+ - **Read notes** - Access note content securely
11
+ - **Create notes** - Add new notes with initial content
12
+ - **Append content** - Extend existing notes
13
+ - **Delete notes** - Remove notes safely
14
+ - **Search** - Find notes by name or content
15
+ - **Health checks** - Monitor server status and vault accessibility
16
+
17
+ Perfect for integrating Obsidian with AI agents, building automations, and creating advanced workflows.
18
+
19
+ ## Available Tools
20
+
21
+ | Tool | Description | Parameters |
22
+ | ---------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
23
+ | `check_health` | Check server health and vault accessibility. | — |
24
+ | `list_notes` | List all markdown notes with folder hierarchy. | — |
25
+ | `read_note` | Read the content of a specific note. | `note`: Note path (e.g., `Personal/Diary.md`) |
26
+ | `create_note` | Create a new note. Fails if it already exists. | `note`: Note path<br>`content`: Initial content (optional) |
27
+ | `append_to_note` | Append content to an existing note. | `note`: Note path<br>`content`: Text to append |
28
+ | `delete_note` | Delete a note. This action is irreversible. | `note`: Note path |
29
+ | `search_notes` | Search notes by name or content. | `query`: Search text<br>`searchContent`: Also search content (optional, default: `false`) |
30
+
31
+ ## Quick Start
32
+
33
+ Just add this to your MCP client configuration:
34
+
35
+ ### Claude Code
36
+
37
+ Edit `~/.claude.json`:
38
+
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "obsidian": {
43
+ "type": "stdio",
44
+ "command": "npx",
45
+ "args": ["@manex/obsidianmcp"],
46
+ "env": {
47
+ "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault"
48
+ }
49
+ }
50
+ }
51
+ }
52
+ ```
20
53
 
21
- El servidor expone las siguientes tools MCP:
54
+ ### VSCode (Copilot)
55
+
56
+ Edit `~/.config/Code/User/mcp.json`:
57
+
58
+ ```jsonc
59
+ {
60
+ "servers": {
61
+ "obsidian": {
62
+ "type": "stdio",
63
+ "command": "npx",
64
+ "args": ["@manex/obsidianmcp"],
65
+ "env": {
66
+ "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault",
67
+ },
68
+ },
69
+ },
70
+ }
71
+ ```
22
72
 
23
- | Tool | Descripción | Parámetros |
24
- | ---------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
25
- | `check_health` | Comprueba el estado de salud del servidor y accesibilidad del vault. | — |
26
- | `list_notes` | Lista todas las notas markdown del vault con su jerarquía de carpetas. | — |
27
- | `read_note` | Lee el contenido de una nota específica. | `note`: Ruta de la nota (ej: `Personal/Diario.md`) |
28
- | `create_note` | Crea una nueva nota. Falla si ya existe. | `note`: Ruta de la nota<br>`content`: Contenido inicial (opcional) |
29
- | `append_to_note` | Añade contenido al final de una nota existente. | `note`: Ruta de la nota<br>`content`: Texto a añadir |
30
- | `delete_note` | Elimina una nota. Esta acción es irreversible. | `note`: Ruta de la nota |
31
- | `search_notes` | Busca notas por nombre o contenido. | `query`: Texto a buscar<br>`searchContent`: Buscar también en contenido (opcional, default: `false`) |
73
+ Replace `~/Documents/ObsidianVault` with your actual Obsidian vault path. You can use `~` for the home directory.
32
74
 
33
- ## ¿Cómo poner en marcha el servidor MCP?
75
+ > **Note:** `OBSIDIAN_VAULT_PATH` must point to an existing Obsidian vault directory.
34
76
 
35
- 1. Instala las dependencias:
77
+ ## Development
36
78
 
37
- ```bash
38
- bun install
39
- ```
79
+ ### Requirements
40
80
 
41
- 2. Compila el servidor:
81
+ - **Node.js** v18+ (or **Bun** v1.0+ for development build)
82
+ - **Obsidian** vault (local directory)
42
83
 
43
- ```bash
44
- bun run build
45
- ```
84
+ ### Available Scripts
46
85
 
47
- 3. No ejecutes el servidor directamente. Añádelo como servidor MCP en tu cliente compatible (por ejemplo, GitHub Copilot en VSCode, Claude Code, etc.).
86
+ | Command | Description |
87
+ | ------------------- | ------------------------------- |
88
+ | `bun run dev` | Run server in development mode |
89
+ | `bun run build` | Build for production |
90
+ | `bun run start` | Run the compiled server |
91
+ | `bun test` | Run test suite |
92
+ | `bun test --watch` | Run tests in watch mode |
93
+ | `bun run typecheck` | Type check with TypeScript |
94
+ | `bun run inspector` | Run MCP inspector for debugging |
48
95
 
49
- Por ejemplo, para VSCode, en tu archivo `mcp.json` añade la siguiente configuración:
96
+ ## Project Structure
50
97
 
51
- ```jsonc
52
- "servers": {
53
- "obsidian": {
54
- "type": "stdio",
55
- "command": "node",
56
- "args": ["RUTA/AL/dist/server.js"],
57
- "env": {
58
- "OBSIDIAN_VAULT_PATH": "~/ruta/a/tu/vault"
59
- }
60
- }
61
- }
62
- ```
98
+ ```
99
+ src/
100
+ ├── server.ts # MCP server entry point
101
+ ├── config/ # Configuration & environment validation
102
+ ├── errors/ # Typed error classes
103
+ ├── schemas/ # Zod input validation schemas
104
+ ├── tools/ # MCP tool implementations
105
+ ├── types/ # TypeScript type definitions
106
+ └── utils/ # File system & security utilities
107
+ ```
63
108
 
64
- > **Importante:** La ruta del vault se configura mediante la variable de entorno `OBSIDIAN_VAULT_PATH`. Puedes usar `~` para el directorio home.
109
+ ## Security
65
110
 
66
- ## Scripts disponibles
111
+ Built with security as a first-class concern:
67
112
 
68
- | Script | Descripción |
69
- | ------------------- | -------------------------------------- |
70
- | `bun run dev` | Ejecuta el servidor en modo desarrollo |
71
- | `bun run build` | Compila el servidor para producción |
72
- | `bun run start` | Ejecuta el servidor compilado |
73
- | `bun test` | Ejecuta los tests |
74
- | `bun test --watch` | Tests en modo watch |
75
- | `bun run typecheck` | Verifica tipos de TypeScript |
113
+ - **Path traversal prevention** - Validates all paths against vault boundaries
114
+ - **Symlink escape detection** - Prevents breaking out via symbolic links
115
+ - **DoS protection** - Limits recursion depth and result counts
116
+ - **TOCTOU prevention** - Atomic file operations for safe concurrent access
117
+ - **Input validation** - All inputs validated with Zod schemas
76
118
 
77
- ## Requisitos
119
+ ## License
78
120
 
79
- - Node.js (recomendado v18+)
80
- - Bun (https://bun.sh)
81
- - Un vault de Obsidian
121
+ MIT
82
122
 
83
- ## Estructura del proyecto
123
+ ## Support
84
124
 
85
- ```
86
- src/
87
- ├── server.ts # Entry point del servidor MCP
88
- ├── config/ # Configuración y validación de env vars
89
- ├── errors/ # Clases de error tipadas
90
- ├── schemas/ # Esquemas Zod para validación de inputs
91
- ├── tools/ # Handlers de las herramientas MCP
92
- ├── types/ # Definiciones de tipos TypeScript
93
- └── utils/ # Utilidades (filesystem, seguridad de paths)
94
- ```
125
+ Found a bug or have a feature request? Open an [issue](https://github.com/Manex142/ObsidianMCP/issues).
95
126
 
96
- ## Créditos
127
+ ---
97
128
 
98
- Creado con [Bun](https://bun.sh) y [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk).
129
+ **Built with** [Bun](https://bun.sh) and [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
package/bin/index.js ADDED
@@ -0,0 +1,13 @@
1
+ #!/usr/bin/env node
2
+ // ES module wrapper for MCP server
3
+ import { fileURLToPath } from 'url';
4
+ import { dirname, join } from 'path';
5
+
6
+ const __filename = fileURLToPath(import.meta.url);
7
+ const __dirname = dirname(__filename);
8
+
9
+ // Import and run the server
10
+ import(join(__dirname, '../dist/server.js')).catch(err => {
11
+ console.error('Error starting MCP server:', err);
12
+ process.exit(1);
13
+ });
package/package.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
2
  "name": "@manex/obsidianmcp",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "A Model Context Protocol server for secure integration with Obsidian vaults",
5
5
  "author": "Manex142",
6
6
  "license": "MIT",
7
7
  "type": "module",
8
8
  "private": false,
9
- "bin": "bin/cli.sh",
10
9
  "repository": {
11
10
  "type": "git",
12
11
  "url": "https://github.com/Manex142/ObsidianMCP.git"
@@ -22,6 +21,7 @@
22
21
  "ai"
23
22
  ],
24
23
  "main": "dist/server.js",
24
+ "bin": "bin/index.js",
25
25
  "scripts": {
26
26
  "dev": "bun run src/server.ts",
27
27
  "build": "bun build src/server.ts --outdir dist --target node",