obsidian-native-mcp 0.2.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "obsidian-native-mcp",
+  "version": "0.2.0",
+  "description": "Zero-dependency MCP server for Obsidian vaults. Direct filesystem access — no Obsidian process or REST API plugin needed.",
+  "license": "MIT",
+  "bin": {
+    "obsidian-native-mcp": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:plugin": "node scripts/build-plugin.mjs",
+    "dev": "tsx watch src/cli/index.ts",
+    "start": "node dist/cli/index.js",
+    "check": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "clean": "rm -rf dist/",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "eslint": "^10.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.4",
+    "obsidian": "^1.7.0",
+    "prettier": "^3.8.3",
+    "semantic-release": "^25.0.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.59.3"
+  }
+}

package/scripts/build-plugin.mjs

@@ -0,0 +1,35 @@
+import * as esbuild from "esbuild";
+import { copyFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+
+async function main() {
+  await esbuild.build({
+    entryPoints: [join(root, "src", "plugin", "main.ts")],
+    outfile: join(root, "dist", "plugin", "main.js"),
+    bundle: true,
+    platform: "node",
+    target: "es2022",
+    format: "cjs",
+    external: ["obsidian"],
+    sourcemap: "inline",
+    treeShaking: true,
+  });
+
+  const manifestDest = join(root, "dist", "plugin", "manifest.json");
+  const manifestSrc = join(root, "manifest.json");
+  if (!existsSync(dirname(manifestDest))) {
+    mkdirSync(dirname(manifestDest), { recursive: true });
+  }
+  copyFileSync(manifestSrc, manifestDest);
+
+  console.log("Plugin built: dist/plugin/main.js + manifest.json");
+}
+
+main().catch((err) => {
+  console.error("Build failed:", err);
+  process.exit(1);
+});

package/scripts/sync-version.cjs

@@ -0,0 +1,12 @@
+const { readFileSync, writeFileSync } = require("fs");
+const { join } = require("path");
+
+const root = join(__dirname, "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+const manifest = JSON.parse(readFileSync(join(root, "manifest.json"), "utf-8"));
+
+if (manifest.version !== pkg.version) {
+  manifest.version = pkg.version;
+  writeFileSync(join(root, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  console.log(`Synced manifest.json version to ${pkg.version}`);
+}

package/src/cli/index.ts

@@ -0,0 +1,25 @@
+import { createServer } from "../mcp/server";
+import { StdioTransport } from "../mcp/stdio-transport";
+import { VaultRegistry } from "../utils/vaults";
+
+async function main() {
+  const registry = new VaultRegistry();
+
+  if (process.argv.includes("--version") || process.argv.includes("-v")) {
+    console.log("0.2.0");
+    process.exit(0);
+  }
+
+  console.error("obsidian-native-mcp server starting");
+
+  const server = createServer(registry);
+  const transport = new StdioTransport();
+
+  transport.onRequest(async (msg) => server.handleRequest(msg));
+  transport.start();
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/handlers/prompts.ts

@@ -0,0 +1,148 @@
+import { readdirSync, statSync } from "fs";
+import { readFile } from "fs/promises";
+import { join } from "path";
+import type { PromptDefinition } from "../mcp/protocol";
+import type { VaultRegistry } from "../utils/vaults";
+
+interface Frontmatter {
+  [key: string]: any;
+}
+
+function parseFrontmatter(content: string): { frontmatter: Frontmatter; body: string } | null {
+  if (!content.startsWith("---")) return null;
+  const endIndex = content.indexOf("---", 3);
+  if (endIndex === -1) return null;
+  const raw = content.slice(3, endIndex).trim();
+  const body = content.slice(endIndex + 3).trim();
+  const frontmatter: Frontmatter = {};
+  for (const line of raw.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    let value: any = line.slice(colonIndex + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+    else if (value.startsWith("[") && value.endsWith("]")) {
+      value = value
+        .slice(1, -1)
+        .split(",")
+        .map((s: string) => s.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body };
+}
+
+export class PromptHandler {
+  private registry: VaultRegistry;
+  private promptDir = "Prompts";
+
+  constructor(registry: VaultRegistry) {
+    this.registry = registry;
+  }
+
+  async list(vaultName?: string): Promise<PromptDefinition[]> {
+    const vaultPath = this.registry.resolve(vaultName);
+    const promptPath = join(vaultPath, this.promptDir);
+
+    let entries: string[];
+    try {
+      entries = readdirSync(promptPath);
+    } catch {
+      return [];
+    }
+
+    const prompts: PromptDefinition[] = [];
+
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+
+      const fullPath = join(promptPath, entry);
+      const stat = statSync(fullPath);
+      if (!stat.isFile()) continue;
+
+      try {
+        const content = await readFile(fullPath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        const tags: string[] = parsed?.frontmatter?.tags || [];
+
+        if (!tags.includes("mcp-tools-prompt")) continue;
+
+        const promptArgs = parsePromptParameters(parsed?.body || content);
+        prompts.push({
+          name: entry,
+          description: parsed?.frontmatter?.description || entry.replace(".md", ""),
+          arguments: promptArgs,
+        });
+      } catch {
+        continue;
+      }
+    }
+
+    return prompts;
+  }
+
+  async get(
+    name: string,
+    vaultName?: string,
+  ): Promise<{
+    messages: Array<{ role: string; content: { type: string; text: string } }>;
+  }> {
+    const vaultPath = this.registry.resolve(vaultName);
+    const promptPath = join(vaultPath, this.promptDir, name);
+
+    let content: string;
+    try {
+      content = await readFile(promptPath, "utf-8");
+    } catch {
+      throw new Error(`Prompt not found: ${name}`);
+    }
+
+    const parsed = parseFrontmatter(content);
+    const body = parsed?.body || content;
+    const withoutFrontmatter = body.trim();
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: withoutFrontmatter,
+          },
+        },
+      ],
+    };
+  }
+}
+
+interface PromptParameter {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+function parsePromptParameters(content: string): PromptParameter[] {
+  const regex = /<%[-_*]*\s*tp\.mcpTools\.prompt\(([^)]+)\)\s*[-_]*%>/g;
+  const params: PromptParameter[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    try {
+      const argsStr = match[1];
+      const args = argsStr.split(",").map((s) => s.trim().replace(/^["']|["']$/g, ""));
+
+      if (args.length >= 1) {
+        params.push({
+          name: args[0],
+          description: args[1],
+          required: true,
+        });
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return params;
+}

package/src/handlers/tools.ts

@@ -0,0 +1,146 @@
+import {
+  listFiles,
+  readFileHandler,
+  createFile,
+  appendFile,
+  deleteFileHandler,
+  patchFile,
+} from "../utils/fs-utils";
+import { searchInVault } from "../utils/search";
+import type { VaultRegistry } from "../utils/vaults";
+import type { ToolResult } from "../mcp/protocol";
+
+type ToolHandler = (args: Record<string, any>) => Promise<ToolResult>;
+
+export class VaultFileHandler {
+  private registry: VaultRegistry;
+
+  constructor(registry: VaultRegistry) {
+    this.registry = registry;
+  }
+
+  getHandlers(): Record<string, ToolHandler> {
+    return {
+      list_vaults: this.handleListVaults.bind(this),
+      get_vault_info: this.handleVaultInfo.bind(this),
+      list_files: this.handleListFiles.bind(this),
+      get_file: this.handleGetFile.bind(this),
+      create_file: this.handleCreateFile.bind(this),
+      append_to_file: this.handleAppendFile.bind(this),
+      patch_file: this.handlePatchFile.bind(this),
+      delete_file: this.handleDeleteFile.bind(this),
+      search: this.handleSearch.bind(this),
+    };
+  }
+
+  private resolveVault(args: Record<string, any>): string {
+    return this.registry.resolve(args.vault);
+  }
+
+  private async handleListVaults(_args: Record<string, any>): Promise<ToolResult> {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(this.registry.list(), null, 2),
+        },
+      ],
+    };
+  }
+
+  private async handleVaultInfo(args: Record<string, any>): Promise<ToolResult> {
+    const info = this.registry.info(args.vault);
+    return {
+      content: [{ type: "text", text: JSON.stringify(info, null, 2) }],
+    };
+  }
+
+  private async handleListFiles(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    const entries = listFiles(vaultPath, args.directory);
+    return {
+      content: [{ type: "text", text: JSON.stringify(entries, null, 2) }],
+    };
+  }
+
+  private async handleGetFile(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    const result = await readFileHandler(vaultPath, args.filename);
+
+    if (args.format === "json") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                filename: args.filename,
+                frontmatter: result.frontmatter,
+                content: result.content,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    }
+
+    return { content: [{ type: "text", text: result.content }] };
+  }
+
+  private async handleCreateFile(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    await createFile(vaultPath, args.filename, args.content);
+    return {
+      content: [{ type: "text", text: "File created successfully" }],
+    };
+  }
+
+  private async handleAppendFile(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    await appendFile(vaultPath, args.filename, args.content);
+    return {
+      content: [{ type: "text", text: "Content appended successfully" }],
+    };
+  }
+
+  private async handlePatchFile(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    const result = await patchFile(
+      vaultPath,
+      args.filename,
+      args.operation,
+      args.targetType,
+      args.target,
+      args.content,
+      {
+        contentType: args.contentType,
+        targetDelimiter: args.targetDelimiter,
+        trimTargetWhitespace: args.trimTargetWhitespace,
+      },
+    );
+    return {
+      content: [
+        { type: "text", text: "File patched successfully" },
+        { type: "text", text: result },
+      ],
+    };
+  }
+
+  private async handleDeleteFile(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    deleteFileHandler(vaultPath, args.filename);
+    return {
+      content: [{ type: "text", text: "File deleted successfully" }],
+    };
+  }
+
+  private async handleSearch(args: Record<string, any>): Promise<ToolResult> {
+    const vaultPath = this.resolveVault(args);
+    const matches = await searchInVault(vaultPath, args.query, args.directory, args.contextLength);
+    return {
+      content: [{ type: "text", text: JSON.stringify(matches, null, 2) }],
+    };
+  }
+}

package/src/mcp/http-transport.ts

@@ -0,0 +1,138 @@
+import http from "http";
+import type { JSONRPCRequest, JSONRPCResponse } from "./protocol";
+
+export class HttpTransport {
+  private requestHandler: ((request: JSONRPCRequest) => Promise<JSONRPCResponse | null>) | null =
+    null;
+  private server: http.Server | null = null;
+  private sessions = new Map<string, http.ServerResponse>();
+  private port = 0;
+
+  get url(): string {
+    return `http://127.0.0.1:${this.port}/sse`;
+  }
+
+  get actualPort(): number {
+    return this.port;
+  }
+
+  onRequest(handler: (request: JSONRPCRequest) => Promise<JSONRPCResponse | null>): void {
+    this.requestHandler = handler;
+  }
+
+  sendMessage(_message: JSONRPCResponse): void {
+    // Messages sent back via SSE response, not directly
+  }
+
+  start(): Promise<void> {
+    return new Promise((resolve) => {
+      this.server = http.createServer((req, res) => {
+        this.handleRequest(req, res);
+      });
+
+      this.server.listen(0, "127.0.0.1", () => {
+        const addr = this.server!.address();
+        if (addr && typeof addr === "object") {
+          this.port = addr.port;
+        }
+        console.error(`MCP HTTP server listening on http://127.0.0.1:${this.port}`);
+        resolve();
+      });
+    });
+  }
+
+  close(): void {
+    for (const res of this.sessions.values()) {
+      res.end();
+    }
+    this.sessions.clear();
+    this.server?.close();
+  }
+
+  private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+    // CORS headers for Claude Desktop
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+
+    if (req.method === "GET" && url.pathname === "/sse") {
+      this.handleSSE(req, res);
+    } else if (req.method === "POST" && url.pathname === "/message") {
+      this.handleMessage(req, res);
+    } else {
+      res.writeHead(404);
+      res.end("Not found");
+    }
+  }
+
+  private handleSSE(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const sessionId = generateId();
+
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    });
+
+    const messageUrl = `/message?session_id=${sessionId}`;
+    res.write(`event: endpoint\ndata: ${messageUrl}\n\n`);
+
+    this.sessions.set(sessionId, res);
+
+    req.on("close", () => {
+      this.sessions.delete(sessionId);
+    });
+  }
+
+  private handleMessage(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    const sessionId = url.searchParams.get("session_id");
+
+    if (!sessionId || !this.sessions.has(sessionId)) {
+      res.writeHead(400);
+      res.end("Invalid or missing session_id");
+      return;
+    }
+
+    let body = "";
+    req.on("data", (chunk: Buffer) => {
+      body += chunk.toString();
+    });
+    req.on("end", async () => {
+      try {
+        const msg = JSON.parse(body);
+        if (msg.jsonrpc !== "2.0" || !("method" in msg) || !("id" in msg)) {
+          res.writeHead(400);
+          res.end("Invalid JSON-RPC message");
+          return;
+        }
+
+        const response = await this.requestHandler?.(msg as JSONRPCRequest);
+        if (response) {
+          const sseRes = this.sessions.get(sessionId);
+          if (sseRes) {
+            sseRes.write(`event: message\ndata: ${JSON.stringify(response)}\n\n`);
+          }
+        }
+
+        res.writeHead(202);
+        res.end();
+      } catch {
+        res.writeHead(400);
+        res.end("Invalid JSON");
+      }
+    });
+  }
+}
+
+function generateId(): string {
+  return crypto.randomUUID();
+}

package/src/mcp/protocol.ts

@@ -0,0 +1,69 @@
+export interface JSONRPCMessage {
+  jsonrpc: "2.0";
+  id?: number | string;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: { code: number; message: string; data?: any };
+}
+
+export type JSONRPCRequest = Required<Pick<JSONRPCMessage, "jsonrpc" | "id" | "method">> & {
+  params?: any;
+};
+
+export type JSONRPCResponse = Required<Pick<JSONRPCMessage, "jsonrpc" | "id">> & {
+  result?: any;
+  error?: { code: number; message: string; data?: any };
+};
+
+export interface ToolDefinition {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, any>;
+}
+
+export interface ToolResult {
+  content: Array<{ type: "text" | "image"; text?: string; data?: string; mimeType?: string }>;
+  isError?: boolean;
+}
+
+export interface PromptDefinition {
+  name: string;
+  description?: string;
+  arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}
+
+export function encodeMessage(message: any): Uint8Array {
+  const json = JSON.stringify(message);
+  const header = `Content-Length: ${json.length}\r\n\r\n`;
+  const encoder = new TextEncoder();
+  const headerBytes = encoder.encode(header);
+  const bodyBytes = encoder.encode(json);
+  const combined = new Uint8Array(headerBytes.length + bodyBytes.length);
+  combined.set(headerBytes);
+  combined.set(bodyBytes, headerBytes.length);
+  return combined;
+}
+
+export function sendMessage(message: any): void {
+  process.stdout.write(encodeMessage(message));
+}
+
+export function parseMessages(buffer: string): { messages: string[]; remaining: string } {
+  const messages: string[] = [];
+  let remaining = buffer;
+
+  while (true) {
+    const headerMatch = remaining.match(/^Content-Length: (\d+)\r\n\r\n/);
+    if (!headerMatch) break;
+    const contentLength = parseInt(headerMatch[1], 10);
+    const headerEnd = headerMatch[0].length;
+    const totalLength = headerEnd + contentLength;
+    if (remaining.length < totalLength) break;
+    const jsonStr = remaining.slice(headerEnd, totalLength);
+    remaining = remaining.slice(totalLength);
+    messages.push(jsonStr);
+  }
+
+  return { messages, remaining };
+}