obsidian-mcp-local 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# Obsidian MCP Local
+
+MCP local em **Node.js + TypeScript** para expor seu **vault do Obsidian** ao **VS Code + GitHub Copilot**.
+
+Ele foi pensado para uso local via **stdio**, com foco em ler e escrever notas Markdown dentro do seu vault.
+
+## Install
+
+npm install -g obsidian-mcp-local
+
+## Features
+
+### Tools disponíveis
+
+- `search_notes(query)`
+  - busca por texto no path, frontmatter e conteúdo das notas
+  - retorna resultados ranqueados com pequeno excerpt
+
+- `get_note(path)`
+  - abre uma nota do vault
+  - retorna `path`, `frontmatter` e `content`
+
+- `create_note(path, content, overwrite?)`
+  - cria uma nota nova
+  - opcionalmente sobrescreve uma nota existente
+
+- `append_to_note(path, content)`
+  - adiciona conteúdo no final de uma nota existente
+
+- `find_by_tag(tag)`
+  - encontra notas por tag
+  - suporta `tags` no frontmatter e tags inline no conteúdo
+
+## Regras implementadas
+
+- só acessa arquivos **dentro do vault configurado**
+- ignora diretórios como:
+  - `.obsidian`
+  - `.git`
+  - `node_modules`
+- trabalha apenas com arquivos `.md`
+- normaliza paths para evitar acesso fora do diretório base
+
+## Estrutura do projeto
+
+```txt
+obsidian-mcp-local/
+  package.json
+  tsconfig.json
+  README.md
+  .vscode/
+    mcp.example.json
+  src/
+    index.ts
+```
+
+## Pré-requisitos
+
+- Node.js 20+
+- npm
+- VS Code com GitHub Copilot
+- um vault do Obsidian local
+
+## Instalação
+
+No diretório do projeto:
+
+```bash
+npm install
+npm run build
+```
+
+Para desenvolvimento:
+
+```bash
+npm run dev
+```
+
+Para rodar a versão compilada:
+
+```bash
+npm start
+```
+
+## Como usar no VS Code
+
+### 1. Compile o projeto
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Ajuste o arquivo MCP do VS Code
+
+Copie o conteúdo de `.vscode/mcp.example.json` para o seu `.vscode/mcp.json` no workspace onde você vai usar o Copilot.
+
+Exemplo:
+
+```json
+{
+  "servers": {
+    "obsidian-local-vault": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["C:/caminho/para/obsidian-mcp-local/dist/index.js"],
+      "env": {
+        "OBSIDIAN_VAULT_PATH": "D:/Obsidian/Vault"
+      }
+    }
+  }
+}
+```
+
+### 3. Atualize os caminhos
+
+Substitua:
+
+- `C:/caminho/para/obsidian-mcp-local/dist/index.js`
+- `D:/Obsidian/Vault`
+
+pelos caminhos reais da sua máquina.
+
+### 4. Reinicie/recarrregue o VS Code
+
+Depois disso, o Copilot deve descobrir o servidor MCP.
+
+## Exemplos de uso no Copilot Chat
+
+- “Procure no meu vault notas sobre .NET”
+- “Abra a nota `knowledge/backend/dotnet.md`”
+- “Crie uma nota em `inbox/ideias-mcp.md` com um resumo do que discutimos”
+- “Adicione no final da nota `daily/2026-04-06.md` o texto `- testar MCP local`”
+- “Encontre notas com a tag `#arquitetura`”
+
+## Possíveis melhorias futuras
+
+- `append_under_heading`
+- parsing de `[[wikilinks]]`
+- `get_backlinks(note)`
+- índice em SQLite para busca rápida
+- whitelist de pastas para escrita (`inbox/`, `daily/`, `scratch/`)
+- bloqueio configurável de escrita em determinadas pastas
+
+## Observações importantes
+
+- Este projeto **não depende do Obsidian aberto**.
+- Ele opera diretamente sobre os arquivos do vault.
+- Se você habilitar escrita tanto no Obsidian quanto no VS Code, o controle de concorrência fica por sua conta.
+- O projeto hoje assume que o vault é uma pasta Markdown local.
+
+## Arquivo principal
+
+A implementação está em:
+
+- `src/index.ts`
+
+## Licença
+
+Uso pessoal / base inicial para customização.

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("[obsidian-mcp-local] Fatal error:", error);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as searchNotes from "./tools/search-notes.js";
+import * as getNote from "./tools/get-note.js";
+import * as createNote from "./tools/create-note.js";
+import * as appendToNote from "./tools/append-to-note.js";
+import * as findByTag from "./tools/find-by-tag.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "obsidian-local-vault",
+        version: "1.0.0",
+    });
+    searchNotes.register(server);
+    getNote.register(server);
+    createNote.register(server);
+    appendToNote.register(server);
+    findByTag.register(server);
+    return server;
+}

package/dist/tools/append-to-note.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { appendToNote } from "../vault/notes.js";
+export function register(server) {
+    server.registerTool("append_to_note", {
+        inputSchema: {
+            path: z.string().min(1),
+            content: z.string().min(1),
+        },
+    }, async ({ path, content }) => {
+        const result = await appendToNote(path, content);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/tools/create-note.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { createNote } from "../vault/notes.js";
+export function register(server) {
+    server.registerTool("create_note", {
+        inputSchema: {
+            path: z.string().min(1),
+            content: z.string(),
+            overwrite: z.boolean().optional(),
+        },
+    }, async ({ path, content, overwrite }) => {
+        const result = await createNote(path, content, overwrite ?? false);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/tools/find-by-tag.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { findByTag } from "../vault/notes.js";
+export function register(server) {
+    server.registerTool("find_by_tag", { inputSchema: { tag: z.string().min(1) } }, async ({ tag }) => {
+        const results = await findByTag(tag);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+}

package/dist/tools/get-note.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { readNote } from "../vault/notes.js";
+export function register(server) {
+    server.registerTool("get_note", { inputSchema: { path: z.string().min(1) } }, async ({ path }) => {
+        const note = await readNote(path);
+        return {
+            content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
+        };
+    });
+}

package/dist/tools/search-notes.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { searchNotes } from "../vault/notes.js";
+export function register(server) {
+    server.registerTool("search_notes", { inputSchema: { query: z.string().min(1) } }, async ({ query }) => {
+        const results = await searchNotes(query);
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+}

package/dist/vault/fs-utils.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isMarkdownFile } from "./path-utils.js";
+export async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function walkMarkdownFiles(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === ".obsidian" ||
+                entry.name === ".git" ||
+                entry.name === "node_modules") {
+                continue;
+            }
+            files.push(...(await walkMarkdownFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && isMarkdownFile(entry.name)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}

package/dist/vault/notes.js

@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { VAULT_ROOT, ensureMdExtension, resolveVaultPath, toRelativeVaultPath, } from "./path-utils.js";
+import { pathExists, walkMarkdownFiles } from "./fs-utils.js";
+export async function readNote(relativePath) {
+    const finalPath = ensureMdExtension(relativePath);
+    const fullPath = resolveVaultPath(finalPath);
+    if (!(await pathExists(fullPath))) {
+        throw new Error(`Note not found: ${finalPath}`);
+    }
+    const raw = await fs.readFile(fullPath, "utf-8");
+    const parsed = matter(raw);
+    return {
+        path: finalPath,
+        frontmatter: parsed.data,
+        content: parsed.content,
+    };
+}
+export async function searchNotes(query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const files = await walkMarkdownFiles(VAULT_ROOT);
+    const matches = [];
+    for (const fullPath of files) {
+        const raw = await fs.readFile(fullPath, "utf-8");
+        const parsed = matter(raw);
+        const relativePath = toRelativeVaultPath(fullPath);
+        const haystack = `${relativePath}\n${JSON.stringify(parsed.data)}\n${parsed.content}`.toLowerCase();
+        const idx = haystack.indexOf(q);
+        if (idx >= 0) {
+            const contentLower = parsed.content.toLowerCase();
+            const contentIdx = contentLower.indexOf(q);
+            const excerpt = contentIdx >= 0
+                ? parsed.content
+                    .slice(Math.max(0, contentIdx - 120), Math.min(parsed.content.length, contentIdx + 220))
+                    .trim()
+                : "";
+            let score = 1;
+            if (relativePath.toLowerCase().includes(q))
+                score += 4;
+            if (JSON.stringify(parsed.data).toLowerCase().includes(q))
+                score += 2;
+            if (contentIdx >= 0)
+                score += 1;
+            matches.push({ path: relativePath, score, excerpt });
+        }
+    }
+    return matches
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, 20);
+}
+export async function findByTag(tag) {
+    const normalizedTag = tag.replace(/^#/, "").trim().toLowerCase();
+    if (!normalizedTag)
+        return [];
+    const files = await walkMarkdownFiles(VAULT_ROOT);
+    const results = [];
+    for (const fullPath of files) {
+        const raw = await fs.readFile(fullPath, "utf-8");
+        const parsed = matter(raw);
+        const relativePath = toRelativeVaultPath(fullPath);
+        const matchedIn = [];
+        const fmTags = parsed.data?.tags;
+        if (Array.isArray(fmTags)) {
+            const found = fmTags.some((t) => String(t).replace(/^#/, "").toLowerCase() === normalizedTag);
+            if (found)
+                matchedIn.push("frontmatter.tags");
+        }
+        const inlineTagRegex = /(^|\s)#([a-zA-Z0-9/_-]+)/g;
+        for (const match of parsed.content.matchAll(inlineTagRegex)) {
+            const foundTag = match[2]?.toLowerCase();
+            if (foundTag === normalizedTag) {
+                matchedIn.push("content");
+                break;
+            }
+        }
+        if (matchedIn.length > 0) {
+            results.push({ path: relativePath, matchedIn });
+        }
+    }
+    return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function createNote(relativePath, content, overwrite = false) {
+    const finalPath = ensureMdExtension(relativePath);
+    const fullPath = resolveVaultPath(finalPath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    const exists = await pathExists(fullPath);
+    if (exists && !overwrite) {
+        throw new Error(`Note already exists: ${finalPath}`);
+    }
+    await fs.writeFile(fullPath, content, "utf-8");
+    return {
+        path: finalPath,
+        created: !exists,
+        overwritten: exists && overwrite,
+    };
+}
+export async function appendToNote(relativePath, content) {
+    const finalPath = ensureMdExtension(relativePath);
+    const fullPath = resolveVaultPath(finalPath);
+    if (!(await pathExists(fullPath))) {
+        throw new Error(`Note not found: ${finalPath}`);
+    }
+    const prefix = content.startsWith("\n") ? "" : "\n";
+    await fs.appendFile(fullPath, `${prefix}${content}`, "utf-8");
+    return {
+        path: finalPath,
+        appended: true,
+    };
+}

package/dist/vault/path-utils.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+const vaultPath = process.env.OBSIDIAN_VAULT_PATH;
+if (!vaultPath) {
+    throw new Error("Environment variable OBSIDIAN_VAULT_PATH is required.");
+}
+export const VAULT_ROOT = path.resolve(vaultPath);
+export function normalizeSlashes(input) {
+    return input.replace(/\\/g, "/");
+}
+export function isMarkdownFile(filePath) {
+    return filePath.toLowerCase().endsWith(".md");
+}
+export function ensureMdExtension(filePath) {
+    return isMarkdownFile(filePath) ? filePath : `${filePath}.md`;
+}
+export function resolveVaultPath(relativePath) {
+    const safeRelativePath = normalizeSlashes(relativePath).replace(/^\/+/, "");
+    const fullPath = path.resolve(VAULT_ROOT, safeRelativePath);
+    const rootWithSep = VAULT_ROOT.endsWith(path.sep)
+        ? VAULT_ROOT
+        : `${VAULT_ROOT}${path.sep}`;
+    const isInsideVault = fullPath === VAULT_ROOT || fullPath.startsWith(rootWithSep);
+    if (!isInsideVault) {
+        throw new Error("Access outside the vault is not allowed.");
+    }
+    return fullPath;
+}
+export function toRelativeVaultPath(fullPath) {
+    return normalizeSlashes(path.relative(VAULT_ROOT, fullPath));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "obsidian-mcp-local",
+  "version": "1.0.0",
+  "private": false,
+  "author": "Henrique Carvalho de Souza",
+  "license": "MIT",
+  "description": "MCP local para um vault do Obsidian, pensado para uso com VS Code + GitHub Copilot.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "obsidian-mcp-local": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "obsidian",
+    "copilot",
+    "ai",
+    "knowledge-base"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.4",
+    "dotenv": "^17.4.1",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}