@tac0de/obsidian-mcp 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm run test
+npm run build
+```
+
+## Guardrails
+
+- Keep tool behavior deterministic.
+- Preserve read-only scope for `0.1.x`.
+- Do not introduce network side effects in tool handlers.
+- Include tests for new edge cases and error codes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tac0de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# obsidian-mcp
+
+Deterministic read-only MCP server for Obsidian vaults.
+
+## Scope (v0.1)
+
+- Transport: `stdio` only
+- Runtime: Node.js 20+
+- Tools:
+  - `vault.list_notes(input:{folder?,glob?,limit?}) -> {notes[],total}`
+  - `vault.read_note(input:{path,maxBytes?}) -> {path,content,bytes,sha256,lineCount}`
+  - `vault.search_notes(input:{query,caseSensitive?,limit?}) -> {matches[],total}`
+  - `vault.get_metadata(input:{path}) -> {path,title?,tags[],frontmatter}`
+- Read-only contract: no write/update/delete tools.
+
+## Security defaults
+
+- Vault boundary enforced by `OBSIDIAN_VAULT_ROOT`
+- Path traversal blocked
+- Symlink escape blocked
+- Max file size bounded by `MAX_FILE_BYTES` (default: `262144`)
+- No network calls in tool handlers
+
+## Quick start
+
+```bash
+npm ci
+OBSIDIAN_VAULT_ROOT="/absolute/path/to/vault" npm run dev
+```
+
+Build and test:
+
+```bash
+npm run typecheck
+npm run test
+npm run build
+```
+
+## Determinism guarantees
+
+- Sorted path output
+- Sorted match output
+- Stable SHA-256 for note content
+- Fixed validation and error code prefixes for boundary violations
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported versions
+
+- `0.1.x`
+
+## Reporting
+
+Report security issues privately via GitHub Security Advisories for this repository.
+
+## Security model
+
+- Read-only vault access in v0.1
+- Root-constrained path resolution
+- Path traversal and symlink escape rejection
+- No outbound network operations in tool handlers

package/dist/errors.js

@@ -0,0 +1,25 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+export class VaultError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.name = 'VaultError';
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+export function toMcpError(error) {
+    if (error instanceof VaultError) {
+        const category = error.code === 'E_FILE_NOT_FOUND'
+            ? ErrorCode.InvalidParams
+            : error.code === 'E_MAX_BYTES_EXCEEDED'
+                ? ErrorCode.InvalidParams
+                : ErrorCode.InvalidParams;
+        return new McpError(category, `${error.code}: ${error.message}`);
+    }
+    if (error instanceof Error) {
+        return new McpError(ErrorCode.InternalError, `E_INTERNAL: ${error.message}`);
+    }
+    return new McpError(ErrorCode.InternalError, 'E_INTERNAL: Unknown error');
+}

package/dist/schemas.js

@@ -0,0 +1,73 @@
+import * as z from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+const toJsonSchema = zodToJsonSchema;
+const listNotesInputSchema = z.object({
+    folder: z.string().optional(),
+    glob: z.string().optional(),
+    limit: z.number().int().min(1).max(1000).optional()
+});
+const listNotesOutputSchema = z.object({
+    notes: z.array(z.string()),
+    total: z.number().int().nonnegative()
+});
+const readNoteInputSchema = z.object({
+    path: z.string().min(1),
+    maxBytes: z.number().int().min(1).max(10_000_000).optional()
+});
+const readNoteOutputSchema = z.object({
+    path: z.string(),
+    content: z.string(),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    lineCount: z.number().int().nonnegative()
+});
+const searchNotesInputSchema = z.object({
+    query: z.string(),
+    caseSensitive: z.boolean().optional(),
+    limit: z.number().int().min(1).max(500).optional()
+});
+const searchNotesOutputSchema = z.object({
+    matches: z.array(z.object({
+        path: z.string(),
+        lineNumber: z.number().int().positive(),
+        line: z.string()
+    })),
+    total: z.number().int().nonnegative()
+});
+const getMetadataInputSchema = z.object({
+    path: z.string().min(1)
+});
+const getMetadataOutputSchema = z.object({
+    path: z.string(),
+    title: z.string().optional(),
+    tags: z.array(z.string()),
+    frontmatter: z.record(z.string(), z.unknown())
+});
+export const toolSchemas = {
+    listNotesInputSchema,
+    listNotesOutputSchema,
+    readNoteInputSchema,
+    readNoteOutputSchema,
+    searchNotesInputSchema,
+    searchNotesOutputSchema,
+    getMetadataInputSchema,
+    getMetadataOutputSchema
+};
+export const toolJsonSchemas = {
+    'vault.list_notes': {
+        input: toJsonSchema(listNotesInputSchema, 'vault.list_notes.input'),
+        output: toJsonSchema(listNotesOutputSchema, 'vault.list_notes.output')
+    },
+    'vault.read_note': {
+        input: toJsonSchema(readNoteInputSchema, 'vault.read_note.input'),
+        output: toJsonSchema(readNoteOutputSchema, 'vault.read_note.output')
+    },
+    'vault.search_notes': {
+        input: toJsonSchema(searchNotesInputSchema, 'vault.search_notes.input'),
+        output: toJsonSchema(searchNotesOutputSchema, 'vault.search_notes.output')
+    },
+    'vault.get_metadata': {
+        input: toJsonSchema(getMetadataInputSchema, 'vault.get_metadata.input'),
+        output: toJsonSchema(getMetadataOutputSchema, 'vault.get_metadata.output')
+    }
+};

package/dist/server.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { toolSchemas } from './schemas.js';
+import { toMcpError } from './errors.js';
+import { VaultReader } from './vault.js';
+const SERVER_NAME = 'obsidian-mcp';
+const SERVER_VERSION = '0.1.0';
+const DEFAULT_MAX_FILE_BYTES = 262_144;
+function getEnv(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        throw new Error(`${name} is required`);
+    }
+    return value;
+}
+function getMaxFileBytes() {
+    const raw = process.env.MAX_FILE_BYTES;
+    if (!raw) {
+        return DEFAULT_MAX_FILE_BYTES;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error('MAX_FILE_BYTES must be a positive number');
+    }
+    return Math.floor(parsed);
+}
+function toToolResult(payload) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(payload, null, 2)
+            }
+        ],
+        structuredContent: payload
+    };
+}
+export async function createServer() {
+    const vaultRoot = getEnv('OBSIDIAN_VAULT_ROOT');
+    const maxFileBytes = getMaxFileBytes();
+    const reader = await VaultReader.create(vaultRoot, maxFileBytes);
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION
+    });
+    server.registerTool('vault.list_notes', {
+        description: 'List notes in the vault using deterministic ordering.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: toolSchemas.listNotesInputSchema.shape,
+        outputSchema: toolSchemas.listNotesOutputSchema.shape
+    }, async (input) => {
+        try {
+            const output = await reader.listNotes(input);
+            return toToolResult(output);
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    server.registerTool('vault.read_note', {
+        description: 'Read one note from the vault and return stable hash metadata.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: toolSchemas.readNoteInputSchema.shape,
+        outputSchema: toolSchemas.readNoteOutputSchema.shape
+    }, async (input) => {
+        try {
+            const output = await reader.readNote(input);
+            return toToolResult(output);
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    server.registerTool('vault.search_notes', {
+        description: 'Search note contents in deterministic order.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: toolSchemas.searchNotesInputSchema.shape,
+        outputSchema: toolSchemas.searchNotesOutputSchema.shape
+    }, async (input) => {
+        try {
+            const output = await reader.searchNotes(input);
+            return toToolResult(output);
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    server.registerTool('vault.get_metadata', {
+        description: 'Return frontmatter and metadata from a note.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: toolSchemas.getMetadataInputSchema.shape,
+        outputSchema: toolSchemas.getMetadataOutputSchema.shape
+    }, async (input) => {
+        try {
+            const output = await reader.getMetadata(input);
+            return toToolResult(output);
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    return server;
+}
+async function main() {
+    const server = await createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} ${SERVER_VERSION} running on stdio`);
+}
+main().catch((error) => {
+    console.error('FATAL', error);
+    process.exit(1);
+});

package/dist/vault.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import matter from 'gray-matter';
+import { VaultError } from './errors.js';
+export class VaultReader {
+    rootPath;
+    maxFileBytes;
+    constructor(rootPath, maxFileBytes) {
+        this.rootPath = rootPath;
+        this.maxFileBytes = maxFileBytes;
+    }
+    static async create(rootPath, maxFileBytes) {
+        const resolved = path.resolve(rootPath);
+        let stat;
+        try {
+            stat = await fs.stat(resolved);
+        }
+        catch {
+            throw new VaultError('E_FILE_NOT_FOUND', `Vault root does not exist: ${rootPath}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new VaultError('E_INVALID_FOLDER', `Vault root is not a directory: ${rootPath}`);
+        }
+        const realRoot = await fs.realpath(resolved);
+        return new VaultReader(realRoot, maxFileBytes);
+    }
+    async listNotes(input) {
+        const limit = clampLimit(input.limit, 100, 1, 1000);
+        const folder = input.folder ?? '.';
+        const globPattern = input.glob?.trim() || '**/*.md';
+        const folderAbs = await this.resolveExistingDirectory(folder);
+        const notesInFolder = await fg([globPattern], {
+            cwd: folderAbs,
+            onlyFiles: true,
+            absolute: false,
+            dot: false,
+            followSymbolicLinks: false,
+            unique: true,
+            suppressErrors: false
+        });
+        const mapped = notesInFolder
+            .map((relativeInFolder) => {
+            const fullPath = path.resolve(folderAbs, relativeInFolder);
+            const relFromRoot = path.relative(this.rootPath, fullPath);
+            return toPosixPath(relFromRoot);
+        })
+            .filter((value) => value.length > 0)
+            .sort();
+        const notes = mapped.slice(0, limit);
+        return {
+            notes,
+            total: mapped.length
+        };
+    }
+    async readNote(input) {
+        const maxBytes = input.maxBytes ?? this.maxFileBytes;
+        const absolute = await this.resolveExistingFile(input.path);
+        const stats = await fs.stat(absolute);
+        if (stats.size > maxBytes) {
+            throw new VaultError('E_MAX_BYTES_EXCEEDED', `File exceeds maxBytes (${stats.size} > ${maxBytes})`);
+        }
+        const buffer = await fs.readFile(absolute);
+        const content = buffer.toString('utf8');
+        return {
+            path: toPosixPath(path.relative(this.rootPath, absolute)),
+            content,
+            bytes: buffer.byteLength,
+            sha256: createHash('sha256').update(buffer).digest('hex'),
+            lineCount: content === '' ? 0 : content.split(/\r?\n/).length
+        };
+    }
+    async searchNotes(input) {
+        const query = input.query.trim();
+        if (!query) {
+            throw new VaultError('E_EMPTY_QUERY', 'Query must not be empty');
+        }
+        const limit = clampLimit(input.limit, 50, 1, 500);
+        const caseSensitive = input.caseSensitive ?? false;
+        const needle = caseSensitive ? query : query.toLowerCase();
+        const { notes } = await this.listNotes({ glob: '**/*.md', limit: 5000 });
+        const matches = [];
+        for (const notePath of notes) {
+            const absolute = await this.resolveExistingFile(notePath);
+            const stats = await fs.stat(absolute);
+            if (stats.size > this.maxFileBytes) {
+                continue;
+            }
+            const text = await fs.readFile(absolute, 'utf8');
+            const lines = text.split(/\r?\n/);
+            for (let index = 0; index < lines.length; index += 1) {
+                const line = lines[index];
+                const hay = caseSensitive ? line : line.toLowerCase();
+                if (hay.includes(needle)) {
+                    matches.push({
+                        path: notePath,
+                        lineNumber: index + 1,
+                        line: line.trimEnd()
+                    });
+                }
+            }
+        }
+        const sorted = matches.sort((a, b) => {
+            if (a.path === b.path) {
+                return a.lineNumber - b.lineNumber;
+            }
+            return a.path.localeCompare(b.path);
+        });
+        return {
+            matches: sorted.slice(0, limit),
+            total: sorted.length
+        };
+    }
+    async getMetadata(input) {
+        const absolute = await this.resolveExistingFile(input.path);
+        const stats = await fs.stat(absolute);
+        if (stats.size > this.maxFileBytes) {
+            throw new VaultError('E_MAX_BYTES_EXCEEDED', `File exceeds maxBytes (${stats.size} > ${this.maxFileBytes})`);
+        }
+        const text = await fs.readFile(absolute, 'utf8');
+        const parsed = matter(text);
+        const normalizedFrontmatter = normalizeValue(parsed.data);
+        const titleFromFrontmatter = typeof normalizedFrontmatter.title === 'string' ? normalizedFrontmatter.title : undefined;
+        const titleFromHeading = extractHeading(text);
+        return {
+            path: toPosixPath(path.relative(this.rootPath, absolute)),
+            title: titleFromFrontmatter ?? titleFromHeading,
+            tags: normalizeTags(normalizedFrontmatter.tags),
+            frontmatter: normalizedFrontmatter
+        };
+    }
+    async resolveExistingDirectory(relativePath) {
+        const safe = await this.resolveInsideRoot(relativePath || '.');
+        let stat;
+        try {
+            stat = await fs.stat(safe);
+        }
+        catch {
+            throw new VaultError('E_FILE_NOT_FOUND', `Directory not found: ${relativePath}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new VaultError('E_INVALID_FOLDER', `Not a directory: ${relativePath}`);
+        }
+        return safe;
+    }
+    async resolveExistingFile(relativePath) {
+        const safe = await this.resolveInsideRoot(relativePath);
+        let stat;
+        try {
+            stat = await fs.stat(safe);
+        }
+        catch {
+            throw new VaultError('E_FILE_NOT_FOUND', `File not found: ${relativePath}`);
+        }
+        if (!stat.isFile()) {
+            throw new VaultError('E_INVALID_PATH', `Not a file: ${relativePath}`);
+        }
+        return safe;
+    }
+    async resolveInsideRoot(relativePath) {
+        if (!relativePath || typeof relativePath !== 'string') {
+            throw new VaultError('E_INVALID_PATH', 'Path is required');
+        }
+        if (path.isAbsolute(relativePath)) {
+            throw new VaultError('E_PATH_TRAVERSAL', 'Absolute paths are not allowed');
+        }
+        const normalized = path.normalize(relativePath);
+        const candidate = path.resolve(this.rootPath, normalized);
+        const rootWithSep = this.rootPath.endsWith(path.sep) ? this.rootPath : `${this.rootPath}${path.sep}`;
+        if (!(candidate === this.rootPath || candidate.startsWith(rootWithSep))) {
+            throw new VaultError('E_PATH_TRAVERSAL', 'Path traversal is not allowed');
+        }
+        try {
+            const real = await fs.realpath(candidate);
+            if (!(real === this.rootPath || real.startsWith(rootWithSep))) {
+                throw new VaultError('E_PATH_TRAVERSAL', 'Symlink path traversal is not allowed');
+            }
+            return real;
+        }
+        catch {
+            return candidate;
+        }
+    }
+}
+function clampLimit(value, fallback, min, max) {
+    const chosen = value ?? fallback;
+    if (!Number.isFinite(chosen)) {
+        return fallback;
+    }
+    const integer = Math.floor(chosen);
+    return Math.max(min, Math.min(max, integer));
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function extractHeading(content) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : undefined;
+}
+function normalizeTags(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+            .filter((entry) => entry.length > 0)
+            .sort();
+    }
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)
+            .sort();
+    }
+    return [];
+}
+function normalizeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeValue(entry));
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        const next = {};
+        for (const key of keys) {
+            next[key] = normalizeValue(record[key]);
+        }
+        return next;
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@tac0de/obsidian-mcp",
+  "version": "0.1.0",
+  "description": "Deterministic read-only MCP server for Obsidian vaults",
+  "main": "dist/server.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "vault",
+    "deterministic",
+    "read-only"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.6",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "bin": {
+    "obsidian-mcp": "dist/server.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tac0de/obsidian-mcp.git"
+  },
+  "homepage": "https://github.com/tac0de/obsidian-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/tac0de/obsidian-mcp/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ]
+}