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.
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.
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.
Move Quick Start above the conceptual sections so install is the first
thing readers hit, and relocate 'Why Semantic MCP?' down to before Core
Tools. Add an inline-emoji hero banner (box → robot) for the .mcpb
drag-into-Claude-Desktop flow — glyphs render on the Obsidian listing
where embedded images get stripped, making the one-click path obvious
to non-power-users.
#192 replaced the Claude Code copy/paste command with a hand-edit-this-JSON
blob plus a warning against `claude mcp add --header`. That was a real UX
regression, and the security premise was wrong for THIS transport:
- The argv / macOS-unified-log exposure applies to **stdio** transports
(a spawned `npx mcp-remote --header ...` child), NOT native **HTTP**
transport — there is no spawned child carrying the header in argv. #143's
threat model was conflated with the mcp-remote setup it was also removing.
- Cleartext-at-rest in ~/.claude.json / .mcp.json is identical whether the
entry is added via the CLI or hand-edited, so "edit the file instead"
bought no at-rest improvement either.
(Confirmed against current Claude Code docs via claude-code-guide.)
Restores the single `claude mcp add --transport http ...` command as the
Claude Code path in the Settings UI, README, and the issue-32 template.
Removes the inaccurate warning and its now-dead `.mcp-security-warning` CSS
and the eslint-disable it required.
Kept from #192 (those parts were legit): native HTTP transport over the
deprecated mcp-remote, and the self-signed-cert / NODE_EXTRA_CA_CERTS
trust docs.
ADR-104's context has a passing line calling the `--header` form
deprecated; left as-is (accepted ADRs are immutable records of what we
believed then) — this commit is the corrective record.
`claude mcp add --header "Authorization: Bearer <token>"` defeats
secret-at-rest protection: the CLI resolves and echoes the header value to
stdout (captured by any parent process, incl. AI agents) and on macOS the
spawned MCP child argv is written to the unified log. Editing the MCP config
file directly avoids both vectors.
- Settings UI: new shared `renderClaudeCodeConnection()` renders a
ready-to-paste JSON config + a security warning for the authenticated
path, and the safe plain CLI command only when auth is disabled. Used by
both the initial render and the live-refresh handler so they cannot drift
(the previous two copies had already diverged).
- README / SECURITY.md / troubleshooting.md / issue-32 response template:
drop `mcp-remote` + `NODE_TLS_REJECT_UNAUTHORIZED=0`, document native HTTP
transport and proper self-signed-cert trust (macOS Keychain +
NODE_EXTRA_CA_CERTS for Bun-based runtimes), add the `--header` warning.
- styles.css: `.mcp-security-warning`.
Reimplemented from PR #143 against current `main` (the settings UI had been
restructured since the PR was opened); supersedes and closes out #143.
ADR-100 left untouched — accepted ADRs are immutable records; the `--header`
deprecation is recorded in ADR-104's context instead.
Co-authored-by: Earl Plak <5597016+laplaque@users.noreply.github.com>
Plugin is live in the community directory (2026-05-16). Capture settled
knowledge so it isn't re-investigated:
- README: link to the public Obsidian listing; fix stale '(coming soon)'
install section (it's live) and the search term to the real plugin name.
- CLAUDE.md: document the portal=source-of-truth -> bot-mirrors-to
community-plugins.json -> in-app browser reads the mirror architecture,
and the resulting post-approval propagation lag (normal, not a bug).
- CLAUDE.md: broaden 'accepted scorecard cautions' to 'accepted review
findings' covering the full submit review — fs access, vault enumeration,
clipboard, and the README placeholder false positive — each with its
justification, so they aren't re-litigated. Refresh the issue tracker line.
Closes#176.
Three onboarding paths now documented in priority order: MCPB
one-click install for Claude Desktop (with cross-platform mime-type
caveat), Claude Code CLI, and the JSON config block for other MCP
clients and multi-vault setups. The maker CLI (scripts/make-mcpb.mjs)
gets its own advanced section for custom-named bundles.
Mirrors the Settings UI ordering so the README and the in-plugin
guidance tell the same story.
Refs ADR-102.
Always run in pooled/concurrent mode — the dual code path (single
MCPServer vs MCPServerPool) existed for backward compatibility with
clients that couldn't handle HTTP transport. All modern MCP clients
now support Streamable HTTP natively.
Changes:
- Remove enableConcurrentSessions toggle and maxConcurrentConnections
setting from interfaces, defaults, and settings UI
- Remove single-server code path (setupMCPHandlers, non-concurrent
request handling branch) — ~200 lines of dead code
- Simplify connection templates from 4 options to 2:
Claude Code command + standard JSON with Authorization header
- Drop mcp-remote and Windows workaround templates
- Fix auth format: use standard Authorization header instead of
URL-embedded credentials
- Remove unused imports (schema types, DataviewTool, FileSystemAdapter)
- Update README and troubleshooting docs
- Accept ADR-100
Net: -433 lines
Remove the community engagement and release download statistics from README and delete the automated stats update workflow. This simplifies the repository and removes unnecessary automation.
Critical bug fix:
- The awk script in update-stats.yml had a logic error that caused
repeated appending of <!-- STATS:END --> markers on each run
- This resulted in the README growing from 192 lines to 4.2M lines
over 22 workflow runs
Changes:
1. Restored README.md to clean state from commit 37a640c (192 lines)
2. Rewrote awk logic to properly replace content between markers:
- Now tracks in_stats state correctly
- Skips all content between START and END markers
- Inserts new stats content only once
- Prevents duplication on subsequent runs
Tested:
- First run: correctly inserts stats (192 → 208 lines)
- Second run: correctly replaces stats (stays at 208 lines)
- Only 1 STATS:END marker after multiple runs
