English Français العربية

io.github.CloudCorpRecords/vaultnotes

السجل الرسمي البحث والويب

List, read, search, and edit markdown notes in a local vault directory.

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @reneturcios/vaultnotes
Claude Code 
claude mcp add vaultnotes -- npx -y @reneturcios/vaultnotes@0.1.0 mcp
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "vaultnotes": {
            "command": "npx",
            "args": [
                "-y",
                "@reneturcios/vaultnotes@0.1.0",
                "mcp"
            ]
        }
    }
}
OCI package ghcr.io/cloudcorprecords/vaultnotes:0.1.0
Claude Code 
claude mcp add vaultnotes -- docker run -i --rm ghcr.io/cloudcorprecords/vaultnotes:0.1.0 mcp
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "vaultnotes": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/cloudcorprecords/vaultnotes:0.1.0",
                "mcp"
            ]
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. vaultnotes
  2. Install
  3. Choosing the vault
  4. CLI
  5. MCP server
  6. Development
  7. License

vaultnotes

vaultnotes is a small set of tools for working with a vault of notes stored as plain files in a folder on your own disk: list what is in the vault, read a note, search across the markdown files, and append to, patch, or delete a note. It runs from the command line or as an MCP server for agents.

Local mode. vaultnotes works directly on a local directory. It does not need a running note-taking application or a plugin API: point it at the folder that holds your notes and every tool operates on the files there. Paths are always vault-relative, and anything that would resolve outside the vault — .. escapes, absolute paths elsewhere, symlinks pointing out — is refused before a file is touched.

Install

npx @reneturcios/vaultnotes list --vault ~/notes

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/vaultnotes

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

Choosing the vault

The vault directory is resolved in this order:

  1. the --vault <dir> flag on the command line,
  2. the VAULTNOTES_DIR environment variable,
  3. the current working directory.

CLI

vaultnotes list --vault ~/notes                 # every file in the vault
vaultnotes list-dir projects --vault ~/notes    # files under one directory
vaultnotes read projects/alpha.md --vault ~/notes
vaultnotes search "launch checklist" --vault ~/notes
vaultnotes append inbox.md "Call Sam on Tuesday." --vault ~/notes
vaultnotes patch inbox.md "Tuesday" "Wednesday" --vault ~/notes
vaultnotes delete drafts/old.md --vault ~/notes

vaultnotes --version

Exit codes: 0 on success, 1 when an operation fails (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/vaultnotes mcp

MCP client configuration (set the vault with the environment):

{
  "mcpServers": {
    "vaultnotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/vaultnotes", "mcp"],
      "env": { "VAULTNOTES_DIR": "/path/to/your/notes" }
    }
  }
}

The server starts and lists its tools even when no vault has been configured yet; the vault is resolved per call and a missing vault produces a tool error rather than a crash.

Tools
ToolInputWhat it returns
list_files_in_vault(no arguments)Every file in the vault, as vault-relative paths.
list_files_in_dirdirpath (string, required)Every file under that vault directory, as vault-relative paths.
get_file_contentsfilepath (string, required)The file's contents as text.
searchquery (string, required)Case-insensitive substring matches across the vault's .md files: for each match, the filepath, the line number, and the matching line as a snippet.
append_contentfilepath (string, required), content (string, required)Appends the content to the file, creating the file (and parent folders) when it does not exist yet.
patch_contentfilepath (string, required), target (string, required), content (string, required)Replaces the first occurrence of the exact target text with the new content; an error when the target text is not in the file.
delete_filetarget_filepath (string, required)Deletes the file. Directories are refused.

A note on patch_content: targeting here is exact-text — the target is the literal passage to replace, not a heading name or a block reference. That keeps a patch unambiguous: it either finds the exact text once and replaces it, or it fails and changes nothing.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real fs in temp dirs, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.

الأسئلة الشائعة

ما هو io.github.CloudCorpRecords/vaultnotes؟

List, read, search, and edit markdown notes in a local vault directory.

كيف أثبّت io.github.CloudCorpRecords/vaultnotes؟

يعمل على جهازك. في Claude Code: claude mcp add vaultnotes -- npx -y @reneturcios/vaultnotes@0.1.0 mcp. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.CloudCorpRecords/vaultnotes إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.CloudCorpRecords/vaultnotes مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.CloudCorpRecords/vaultnotes؟

ينشره CloudCorpRecords. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.