Add mastervault-mcp-server v1.1.1

A project by JustMichael-80 (https://github.com/JustMichael-80). Headless,
filesystem-backed MCP server that serves a MasterVault (files + its
orientation/decision-log/soft-delete protocol) to any MCP client over stdio.

Author: voidstackloop

mastervault-mcp-server/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+dist-bundled/
+*.log

mastervault-mcp-server/HANDOFF.md

@@ -0,0 +1,78 @@
+# Handoff Spec — Deferred Work
+
+This is the scoped, mechanical work deliberately left out of v1 so it can be
+handed to a cheaper model (in ModelForge, Claude Code, or a Sonnet session)
+rather than spending premium tokens on it. v1 is complete and verified without
+any of the below; these are additive.
+
+## Context for the model picking this up
+
+`mastervault-mcp-server` is a TypeScript stdio MCP server that serves a
+"MasterVault" (a structured Obsidian-style knowledge vault) to any MCP client,
+without Obsidian. It has 9 tools across three tiers (protocol / files / delete).
+The build passes (`npm run build`), a functional harness passes 12/12 including
+path-traversal security tests, and an MCP stdio handshake exposes all 9 tools.
+Read `README.md` first, then `src/` — start at `src/index.ts`.
+
+Do not change the security model in `src/services/vault.ts` without re-running
+`node test-harness.mjs` and keeping all security tests green.
+
+## Task 1 — Evaluation suite (mcp-builder Phase 4)
+
+The mcp-builder skill asks for 10 evaluation questions in XML. Create
+`evaluations/eval.xml` with 10 `<qa_pair>` entries that test whether an LLM can
+use these tools to answer realistic questions about a vault. Each question must
+be independent, read-only, complex (multiple tool calls), realistic, verifiable
+(single string-comparable answer), and stable.
+
+Build a small fixture vault under `evaluations/fixture-vault/` with known
+content so answers are deterministic. Example question shape: "Using orient then
+search, what confidence value is recorded for the vault-structure seed row?" →
+answer a specific string.
+
+Format per the skill:
+```xml
+<evaluation>
+  <qa_pair>
+    <question>...</question>
+    <answer>...</answer>
+  </qa_pair>
+</evaluation>
+```
+
+## Task 2 — Unit tests
+
+Convert `test-harness.mjs` into a proper test suite (node:test or vitest). Cover:
+- VaultService: read (with/without line range), list pagination, search, write,
+  append, move (collision + overwrite paths).
+- Security: `../` traversal, absolute path, escaping move, null byte — all must
+  throw `PathSecurityError` or stay confined.
+- Tool layer: patch's zero-match and multi-match rejection; log_decision
+  section-aware append when the category heading is absent vs present;
+  stage_delete collision suffixing.
+Wire it to `npm test` and a `.github/workflows/ci.yml` that runs lint + build +
+test on push.
+
+## Task 3 — Git read tools (v2 tool tier)
+
+Add read-only git helpers as a fourth tier, mirroring ModelForge's own set:
+`mastervault_git_status`, `mastervault_git_log`, `mastervault_git_diff`. All
+`readOnlyHint: true`. Shell out to `git -C <vaultRoot>` with argument arrays
+(never string interpolation — no injection surface). Guard: if the vault is not
+a git repo, return an actionable message, not an error. Keep `git_commit` out
+unless explicitly requested — writes should stay behind the existing tools.
+
+## Task 4 — Packaging niceties
+
+- Add a `LICENSE` file (MIT) to match `package.json`.
+- Add `.gitignore` (`node_modules/`, `dist/`, `*.log`).
+- Consider publishing as an npm package so the ModelForge config can use
+  `npx -y mastervault-mcp-server <vault>` like the filesystem-server example.
+
+## Explicitly NOT in scope
+
+- No hard-delete tool, ever.
+- No shell/run_command tool (clients provide their own).
+- No streamable-HTTP transport in v1 (stdio is the target for local clients like
+  ModelForge). Add later only if a remote/multi-client use case appears; the
+  mcp-builder TypeScript guide has the HTTP transport pattern ready to drop in.

mastervault-mcp-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChronoDyne Systems, Inc.
+
+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.

mastervault-mcp-server/README.md

@@ -0,0 +1,101 @@
+# MasterVault MCP Server
+
+A project by [JustMichael-80](https://github.com/JustMichael-80).
+
+A headless, filesystem-backed [Model Context Protocol](https://modelcontextprotocol.io) server that serves **any MasterVault** — its files *and* its operating protocol — to any MCP client, over stdio. No Obsidian required.
+
+Point it at a vault directory; any MCP-capable LLM client (ModelForge, Claude Desktop, AnythingLLM, etc.) can then orient on the vault's protocol, read and search its contents, log decisions, and soft-delete files — all behind the client's own approval flow.
+
+## Why this exists
+
+An Obsidian vault can already be served over MCP via the Local REST API plugin, but that ties it to Obsidian. This server drops the Obsidian dependency: it speaks the same vault semantics against a plain directory, so the MasterVault becomes portable to any client and any model. It also surfaces the vault's *protocol* (orientation, decision-logging, soft-delete), not just its files — so a fresh LLM can run the system, not merely read it.
+
+## Install
+
+```bash
+git clone https://github.com/JustMichael-80/mastervault-mcp-server.git
+cd mastervault-mcp-server
+npm install      # also builds via the prepare script
+npm run build    # (if you skipped prepare)
+```
+
+Requires Node.js 18+.
+
+## Run
+
+```bash
+mastervault-mcp-server /absolute/path/to/vault
+# or
+MASTERVAULT_ROOT=/absolute/path/to/vault node dist/index.js
+```
+
+The vault path is the only configuration. Nothing is hardcoded — the same binary serves any vault.
+
+## Connecting a client
+
+### ModelForge
+
+In **Settings → MCP servers**, add a **stdio** server:
+
+- **Command:** `node`
+- **Args:** `/absolute/path/to/mastervault-mcp-server/dist/index.js` `/absolute/path/to/vault`
+
+(or use the `mastervault-mcp-server` bin directly if installed globally). The server's tools then appear in Agent mode's tool list, each behind ModelForge's Allow/Deny approval — exactly like its built-in file tools.
+
+### Any MCP client (generic stdio config)
+
+```json
+{
+  "mcpServers": {
+    "mastervault": {
+      "command": "node",
+      "args": ["/absolute/path/to/dist/index.js", "/absolute/path/to/vault"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Tier | Read-only | What it does |
+|------|------|:---------:|--------------|
+| `mastervault_orient` | protocol | ✅ | Reads the orientation file and the protocol files it points to, in order. **Call this first.** |
+| `mastervault_get_confidence_summary` | protocol | ✅ | Returns the calibration dashboard (`_Meta/Confidence Summary.md`). |
+| `mastervault_log_decision` | protocol | ✍️ | Appends a consequential decision (proposal + confidence + verdict) to the right category in `_Meta/Decision Log.md`. |
+| `mastervault_read` | files | ✅ | Reads a file, optionally by line range; parses markdown frontmatter. |
+| `mastervault_list` | files | ✅ | Lists a directory, paginated, directories first. |
+| `mastervault_search` | files | ✅ | Case-insensitive full-text search across text files. |
+| `mastervault_write` | files | ✍️ | Creates or overwrites a file. |
+| `mastervault_patch` | files | ✍️ | Replaces one exact, unique text block in a file. |
+| `mastervault_stage_delete` | delete | ✍️ | Moves a file to `_ToDelete/` and logs the proposal. **Never hard-deletes.** |
+
+Every tool supports `response_format: "markdown"` (default) or `"json"`.
+
+## Security model
+
+- **Path confinement is the single security boundary.** Every path is resolved and confined to the vault root before any filesystem call. Lexical `..` traversal, absolute paths, and null bytes are rejected; a leading slash is treated as vault-relative, not filesystem-absolute. Existing paths get a second `realpath` check so a symlink inside the vault can't point out of it.
+- **No hard delete.** The server has no tool that destroys data. `stage_delete` only *moves* files into `_ToDelete/`; a human is the sole final actor who empties it. This is why `stage_delete` is marked non-destructive — it's reversible by design.
+- **No shell execution.** File operations only. If a client needs shell access it provides that itself (ModelForge does, sandboxed and gated separately).
+- **stdio hygiene.** All logging goes to stderr; stdout carries only the MCP protocol.
+
+## The MasterVault protocol layer
+
+This server is more than a file server because of three conventions it understands:
+
+- **`_orientation.md`** — the entry point a fresh LLM reads first (via `mastervault_orient`) to inherit the vault's working rules.
+- **`_Meta/Decision Log.md` + `Confidence Summary.md`** — a decision-logging + calibration system: consequential proposals are logged with a pre-verdict confidence estimate, and the gap between estimate and outcome accumulates into a per-category calibration signal.
+- **`_ToDelete/`** — the soft-delete staging area; the human is always the final actor on removal.
+
+A vault that lacks these still works as a plain file tree — the protocol tools report what's missing rather than failing.
+
+## Development
+
+```bash
+npm run dev     # tsx watch
+npm run build   # tsc -> dist/
+npm start       # node dist/index.js <vault>
+```
+
+## License
+
+MIT