From 7c1774bcbe9f86f69302403dec6fa596256e48a0 Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Fri, 3 Jul 2026 23:01:25 -0500 Subject: [PATCH 1/3] docs(readme): lead with concrete verbs + the native/no-server edge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Repositioning the README opening after a competitive prose analysis of the top Obsidian-MCP projects. The old opening led with an abstract tagline ("Give AI semantic agency over your knowledge graph") and spent prime real estate explaining what MCP is — to people who searched for MCP — while our single biggest differentiator (a native in-Obsidian server, no external Node process, no separate REST-API plugin) went unstated. A competitor was already using our own "no external dependencies" angle. Changes to the top-of-README positioning only (setup/tools/docs untouched): - Verb-first tagline: "Read, write, search, and traverse your Obsidian vault from any AI assistant — through an MCP server that runs inside Obsidian." - State the native/no-server edge in the first sentence, framed positively (our own architecture, not a competitor put-down); connect it to why the drag-drop `.mcpb` setup is possible. - Ground the "8 semantic tools" claim with a concrete, verified example (the vault tool alone handles 13 actions) instead of an abstraction. - Relocate the "what is MCP" explainer to a short "New to MCP?" aside. - Preserve the drag-drop onboarding hero — the strongest story in the field. --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a83da47..42e3d7a 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,15 @@ 📦 **[Available in the Obsidian Community Plugin directory →](https://community.obsidian.md/plugins/semantic-vault-mcp)** -**Give AI semantic agency over your knowledge graph** +**Read, write, search, and traverse your Obsidian vault from any AI assistant — through an MCP server that runs _inside_ Obsidian.** -This plugin connects your Obsidian vault to AI assistants through MCP (Model Context Protocol), giving them the ability to understand and navigate your notes as a connected knowledge graph, not just isolated files. Through semantic hints and graph traversal, AI gains the agency to explore concepts, follow connections, and synthesize information across your entire vault. +No external Node process to launch, no separate REST-API plugin to bridge through: the server *is* the plugin. Setup is a drag-and-drop — drop the `.mcpb` bundle onto Claude Desktop, paste your key, done. -**MCP (Model Context Protocol)** is the open standard that lets AI assistants interact with external tools and data sources. This plugin works with any MCP-compatible client including: -- Claude Desktop (Anthropic) -- Claude Code/Continue.dev (VS Code) -- Any platform that supports local MCP servers +It exposes **8 semantic tools** — each one a family of operations rather than a single call (the `vault` tool alone handles 13: list, read, create, search, move, split, combine, and more) — plus Dataview queries, Bases, and graph traversal. So the AI can follow links, tags, and backlinks and synthesize across your whole vault as a connected knowledge graph, not one open file at a time. + +**Works with any MCP-compatible client** — Claude Desktop, Claude Code, Cline, Continue.dev, and anything that speaks local MCP. + +> **New to MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) is the open standard that lets AI assistants interact with external tools and data. You don't need to understand it to use this — the [Quick Start](#quick-start) is three steps. ## Quick Start From 7a7faa84a787eaab0d632600151689f7fe4cc519 Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Fri, 3 Jul 2026 23:03:37 -0500 Subject: [PATCH 2/3] docs(readme): drop "semantic" jargon, foreground permissions + Bases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per feedback: "semantic" is insider framing nobody searches for. Lead the capability line with concrete value instead — 8 powerful tools, first-class Dataview + Bases support, and (the real trust differentiator) that every operation respects the permissions you set: read-only mode, per-operation controls, and path allow/block lists. Competitors mostly hand the AI unrestricted read/write; this one doesn't. All claims verified against the shipped VaultSecurityManager + readOnlyMode settings. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 42e3d7a..5a4d731 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ No external Node process to launch, no separate REST-API plugin to bridge through: the server *is* the plugin. Setup is a drag-and-drop — drop the `.mcpb` bundle onto Claude Desktop, paste your key, done. -It exposes **8 semantic tools** — each one a family of operations rather than a single call (the `vault` tool alone handles 13: list, read, create, search, move, split, combine, and more) — plus Dataview queries, Bases, and graph traversal. So the AI can follow links, tags, and backlinks and synthesize across your whole vault as a connected knowledge graph, not one open file at a time. +It exposes **8 powerful tools** — each a whole family of operations, not a single call (the `vault` tool alone handles 13: list, read, create, search, move, split, combine, and more) — with first-class **Dataview** and **Bases** support plus graph traversal across links, tags, and backlinks. And every operation respects the permissions *you* set — a read-only mode, per-operation controls, and path allow/block lists — so the AI only ever does what you've allowed, not unrestricted run of your vault. **Works with any MCP-compatible client** — Claude Desktop, Claude Code, Cline, Continue.dev, and anything that speaks local MCP. From f72b460ab20189d70c99d0530bcf289ca2c90f4e Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Fri, 3 Jul 2026 23:11:03 -0500 Subject: [PATCH 3/3] =?UTF-8?q?docs(readme):=20finish=20de-jargoning=20?= =?UTF-8?q?=E2=80=94=20headings,=20feature=20labels,=20fix=20stale=20name?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Carry the "drop semantic jargon" pass through the whole README, not just the opening: - "## Why Semantic MCP?" → "## Why It's Different" - "## The Semantic Advantage" → "## In Practice" (the section is examples; the old title also near-duplicated "Why It's Different") - "### Semantic Search" → "### Full-Text Search" — the section describes operators/regex/relevance ranking, i.e. full-text, not embedding-semantic; the old label was both jargon and inaccurate - "Search across all notes semantically" → "Search and rank across all notes" - "Concept Discovery: Semantic search finds..." → "Search and graph traversal surface related ideas..." - "AI uses semantic tools to:" → "AI uses these tools to:" - Fix stale settings reference: "Semantic MCP" → "Semantic Notes Vault MCP" (the actual manifest name shown in Obsidian's plugin list) "Semantic" now survives only as the plugin's own name and the semantic-vault-mcp slug / cert paths — its established identity, unchanged. --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5a4d731..70b508b 100644 --- a/README.md +++ b/README.md @@ -125,24 +125,24 @@ Once connected, simply chat with your AI assistant about your notes! For example Your AI assistant now has these capabilities: - Navigate your vault's link structure -- Search across all notes semantically +- Search and rank across all notes - Read, edit, and create notes - Analyze your knowledge graph - Work with Dataview queries (if installed) - Manage Obsidian Bases (database views) -## Why Semantic MCP? +## Why It's Different -Traditional file access gives AI a narrow view - one document at a time. This plugin transforms that into **semantic agency**: +Traditional file access gives AI a narrow view — one document at a time. This plugin gives it the whole connected picture: - **Graph Navigation**: AI follows links between notes, understanding relationships and context -- **Concept Discovery**: Semantic search finds related ideas across your vault +- **Concept Discovery**: Search and graph traversal surface related ideas across your vault - **Contextual Awareness**: AI understands where information lives in your knowledge structure - **Intelligent Synthesis**: Combine fragments from multiple notes to answer complex questions ## Core Tools -The plugin provides 8 semantic tool groups that give AI comprehensive vault access: +The plugin provides 8 powerful tools that give AI comprehensive vault access — each one a family of related operations, all subject to the permissions you set: | Tool | Purpose | Key Actions | |------|---------|-------------| @@ -167,15 +167,15 @@ Detailed documentation for each tool and feature: - [🔧 Configuration](docs/configuration.md) - Server settings and options - [❓ Troubleshooting](docs/troubleshooting.md) - Common issues and solutions -## The Semantic Advantage +## In Practice -This plugin doesn't just give AI access to files - it provides **semantic understanding**: +This plugin doesn't just give AI access to files — it lets AI work across your vault as a connected whole: ### Example: Research Assistant ``` User: "Summarize my research on machine learning optimization" -AI uses semantic tools to: +AI uses these tools to: 1. Search for notes with ML optimization concepts 2. Traverse graph to find related papers and techniques 3. Follow backlinks to discover applications @@ -195,7 +195,7 @@ AI uses graph tools to: ## Features -### Semantic Search +### Full-Text Search - Advanced query operators: `tag:`, `path:`, `content:` - Regular expressions and phrase matching - Relevance ranking and snippet extraction @@ -220,7 +220,7 @@ AI uses graph tools to: ## Plugin Settings -Access settings via: Settings → Community plugins → Semantic MCP +Access settings via: Settings → Community plugins → Semantic Notes Vault MCP Key configuration options: - **Server Ports**: HTTP (3001) and HTTPS (3443)