Cursidian

Implementation of the Obsidian llm-wiki concept for Cursor, using an MCP designed to minimise token consumption and maximise relevant results. Includes slop removal tools.

Getting Started:

• Download Obsidian, create an empty vault, make a note of its location.
• Install the "LLM Slop Detector" plugin in your Cursor (thias-se.llm-slop-detector)
• Install this MCP and the skills into your Cursor.
• Restart / Reload Cursor.
• Enter this prompt: "I have just created an empty obsidian vault at vault location, please set up my wiki there"

Let it do its thing, it will take about 5 minutes and burn like 30k tokens. Auto is fine, you don't need Claude for this! At this point you don't even need to be running Obsidian any more, the point of it was just to create the vault structure.

Once it is set up you can just ask Cursor agents for stuff like "create pages in my wiki about my project, as many as you need to capture everything." Or "refactor my ui to be more colourful, using the design notes in my wiki" etc. The sky is the limit. The more effort you ask agents to put into your wiki, the more you get out of it.

And notice the distinction there. the more effort you ask your agents to put in, you don't write this thing yourself. Have the Cursor agents do everything, they write the wiki, they read it, they lint it, check it and maintain it. You can dump entire ebooks into it, or have it review your most recent 100 cursor chat transcripts and save any relevant information it finds to your wiki. Optionally, ask it to "remove all slop from my wiki" once in a while.

You can dip in to read it using Obsidian whenever you like, but really its a resource for Cursor agents to store information about your projects, your goals, your design desisions and rules and so on.

Credits

I took the "Obsidian Wiki" concept from Andrej Karpathy, and I drew inspiration from this existing Obsidian MCP: @istrejo/obsidian-mcp. But really the credit goes to Fable, Grok and Composer 2.5, I am just their conductor, and I used Cursor to create this.

Anyway that's the end of the human-written portion of the readme, the rest is by Agents and for Agents really, but feel free to keep reading if you want.

Emjoy! John.

Features

• 4 MCP tools - note, search, graph, vault (action-dispatch surface)
• Safe writes - patch inferred when old_string/new_string are set; replace_section for heading edits
• Agent-friendly search - default limit 10, compact format, stopwords stripped, token-AND with OR/typo fallback; hits include title/summary/tags
• Auto timestamps - note create/update/frontmatter set created/updated automatically
• Optimistic concurrency - revisionHash on read (full note), expectedRevision on write; contentHash / expectedHash remain as body-only / deprecated alias
• Operation journals + undo - mutating calls return operationId; vault history / undo reverse journaled work
• Typed manifest - vault manifest for _meta/manifest.md (no hand-edited ledger lines)
• Signature-based caches - index and search snapshots invalidate when files change on disk (including Obsidian edits)
• Deslop gate - npm run build runs slop:check first; strips AI typography and decorative emoji from the repo (and optionally the wiki vault)
• Wiki skills - nine Cursor skills that drive the MCP tools for ingest, query, lint, capture, update, status, and deslop
• Skill contract gate - npm run skills:check rejects retired tool names, phantom health fields, and read-only write leaks

Tools

Tool	Actions	Purpose
note	read, create, update, delete, rename, frontmatter	Note CRUD, safe edits, metadata; returns revisionHash / operationId
search	content (default), by_tags, list, recent, tags	Find and enumerate notes (paginated; may report incomplete)
graph	-	One-hop neighborhood (resolved + unresolved outgoing, paginated backlinks)
vault	health, sync_index, slop_check, deslop, create_folder, list_folders, delete_folder, log, history, undo, manifest	Health, catalog, deslop, folders, bookkeeping, undo, ingest ledger

Requirements

• Node.js >= 20
• An absolute Obsidian vault path via OBSIDIAN_VAULT_PATH

Quick start (published package)

Add to ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

{
  "mcpServers": {
    "cursidian": {
      "command": "npx",
      "args": ["-y", "cursidian"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\you\\Documents\\MyVault"
      }
    }
  }
}

Unix:

"OBSIDIAN_VAULT_PATH": "/Users/you/Documents/MyVault"

Reload Cursor. The config key "cursidian" appears as MCP server user-cursidian.

See also examples/cursor-mcp.json.

Local development setup

git clone https://github.com/CoolJohn-lab/Cursidian.git
cd Cursidian
npm install
npm run build
npm test

Point Cursor at the built entrypoint:

{
  "mcpServers": {
    "cursidian": {
      "command": "node",
      "args": ["/absolute/path/to/Cursidian/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Wiki skills + MCP

Cursidian is a two-layer product:

Layer	Role	Where
MCP server	Runtime vault I/O for agents	Published cursidian package / local dist/
Wiki skills	Workflow instructions (ingest, query, lint, ...)	skills/wiki/ copied into ~/.cursor/skills/

The MCP server is the only way agents read or write vault markdown. Skills do not open vault files with the IDE filesystem tools or shell - they call user-cursidian (note, search, graph, vault). If an MCP call fails, the skill reports the failure and stops (no silent filesystem fallback).

Source documents outside the vault (PDFs, repo files, URLs) may be read with normal tools for ingest; the moment content enters the vault, it is MCP-only.

How agents use both

1. Cursor loads skills from ~/.cursor/skills/ when the user asks something matching a skill description (e.g. "add this to the wiki", "what do I know about X").
2. The skill tells the agent which MCP actions to call, in what order (cheap search first, full note read only when needed).
3. Writes follow the safe-write protocol: note read -> revisionHash -> narrowest note update with expectedRevision. Mutating skills keep an operation-ID stack and call vault undo in reverse on failure after writes.
4. After multi-page edits, skills typically call vault sync_index (rebuild index.md) and vault log (append log.md / optional hot.md), then verify with sync_index dryRun: true expecting wouldWrite: false.

Shared schema and the full MCP contract live in the llm-wiki skill.

Install skills

npm run skills:install
# or from the published package:
npx cursidian-skills

That removes then copies the nine skill folders into ~/.cursor/skills/ (never symlink; copying into an existing folder nests skill/skill/SKILL.md). Full steps: skills/wiki/INSTALL.md. Re-run after skill or MCP tool-surface changes, then start a new agent chat so Cursor re-discovers them.

Exception: none for vault writes. wiki-slop uses MCP vault slop_check / deslop for the vault; npm slop:* remains for the repo build gate (and optional human/CI *:wiki CLIs).

Skill	Purpose	Typical MCP use
llm-wiki	Theory, schema, MCP contract	Reference for other skills
wiki-query	Read-only Q&A	search -> optional note read / graph (no writes)
wiki-lint	Vault health / consolidate	vault health, then note/vault fixes
wiki-setup	Bootstrap vault structure	vault folders, note create special files
wiki-ingest	Distill docs/URLs into pages	search + note create/update + vault manifest/log/sync
wiki-capture	Save session findings	note create/update (_raw/ or full pages); merge on duplicate
wiki-update	Sync a project into the wiki	git delta outside vault; writes via note/vault manifest
wiki-status	Delta / what next / hot.md	vault manifest read; _raw/ with includeOperational; hot refresh on request
wiki-slop	Deslop repo or vault	Repo: npm slop:*. Vault: vault slop_check / deslop

Deslop (LLM-slop)

Keeps AI typography (em/en dashes, curly quotes, ellipsis, arrows) and decorative emoji out of the package and, when you ask, the Obsidian vault. Uses llm-slop-detector with this repo's .llmsloprc.json. Vault MCP deslop covers bodies and all frontmatter string fields so index drift stays clear. By default MCP skips operational files (index/log/hot/_raw/_archives/_meta); pass includeOperational: true to include them. Human/CI slop:*:wiki still scans the full tree.

Command / tool	Purpose
npm run slop:check	Scan this repo; exit non-zero if dirty
npm run slop:fix	Auto-fix chars/emoji in this repo
vault slop_check	Read-only vault slop report (body + frontmatter; wordFindings/phraseDocuments)
vault deslop	Journaled vault char/emoji fix (dryRun / confirm: true)
npm run slop:check:wiki	Human/CI CLI vault scan (agents prefer MCP)
npm run slop:fix:wiki	Human/CI CLI vault fix (agents must use MCP deslop)
npm run build	prebuild -> slop:check, then tsc

Wiki scans use the same rules but do not gate build (the vault lives outside the package). Phrase-pack hits need a manual rewrite; chars/emoji are auto-fixed. Prefer the wiki-slop skill over ad-hoc CLI flags.

Safe write workflow

1. Read - note with action: "read"; note the revisionHash (full note) and legacy contentHash (body only).
2. Edit - note with action: "update" using the safest mode for surgical edits (patch, replace_section, append, prepend). For wholesale page rewrites, use a single replace. Prefer one combined update that also passes frontmatter (merge) so body + metadata share one operationId.
3. Pass expectedRevision from step 1 to detect concurrent edits (including frontmatter-only changes). expectedHash still works as a deprecated body-hash alias.
4. On success, record operationId when present and replace any cached revisionHash for that path with the response value. To reverse: vault undo with operationId and confirm: true.

Same-path edits in one session

• Never fire parallel note mutations for the same path.
• Pattern: read -> immediate write with that revisionHash -> use the response revisionHash for any further write to that path.
• Prefer combined body + frontmatter on one update over a body write then a separate frontmatter call.
• On hash_mismatch, prefer details.currentRevision for frontmatter-only / full-replace retries; re-read when re-deriving a patch / replace_section.

Undo example

{ "action": "history", "limit": 10 }

{ "action": "undo", "operationId": "<id-from-mutation>", "confirm": true }

Manifest example

{
  "action": "manifest",
  "manifestOperation": "upsert_source",
  "sourceKey": "C:/abs/path/paper.pdf",
  "sourceIngested": "2026-07-13T00:00:00Z",
  "sourcePages": ["concepts/foo"]
}

Security model

Cursidian is a local stdio MCP server. It trusts the Cursor process that launches it and the OS user that owns the vault directory. There is no network attack surface in normal use; hardening focuses on path containment, bounded I/O, and recoverable writes when agents or external editors touch the vault.

Layer	What it guarantees
Lexical containment	Resolved paths must stay under OBSIDIAN_VAULT_PATH (blocks ../ and absolute escapes).
Real-path containment	Symlinks/junctions that resolve outside the vault are rejected before reads and writes.
Symlink-safe discovery	Vault scans use followSymbolicLinks: false and filter results whose real path escapes the vault.
Atomic single-file writes	Creates use exclusive open; updates use same-directory temp + rename under a per-path lock.
Optimistic concurrency	revisionHash / expectedRevision checked under the mutation lock; frontmatter-only external edits are detected.
Multi-file rollback	Rename (including source backup), backlink rewrites, and vault log (log + hot) journal together and roll back on failure; partial_update with sideEffects: "partial" only when rollback itself fails.

For untrusted agents or shared machines, run with OBSIDIAN_READ_ONLY=true and restrict vault directory ACLs to least privilege.

Backups (.cursidian-trash)

When OBSIDIAN_BACKUP_ENABLED is true (default), each mutating MCP call journals under .cursidian-trash/<operationId>/ (prior snapshots for every affected path, including creates so undo can remove them):

Operation	Journaled
note update / replace / patch / section edit	Yes
note frontmatter set / merge / delete	Yes
note delete	Yes
note rename	Yes (source + each rewritten backlink/index file)
note create (incl. overwrite)	Yes
vault sync_index	Yes (index.md)
vault deslop	Yes (each changed note; index.md when summaries change)
vault log	Yes (log.md; hot.md when updated)
vault manifest	Yes

Legacy .obsidian-mcp-trash entries are migrated into .cursidian-trash/_legacy-migrated/ on first backup (not deleted). Retention keeps the newest 50 operation folders by default; older folders are pruned automatically. With backups disabled, mutations still succeed but return undoAvailable: false.

Environment variables

Variable	Required	Description
OBSIDIAN_VAULT_PATH	Yes	Absolute path to your Obsidian vault (~ / %USERPROFILE% expanded)
OBSIDIAN_READ_ONLY	No	Set to true to disable writes
OBSIDIAN_MAX_FILE_SIZE	No	Max file size in bytes (default 10 MB)
OBSIDIAN_BACKUP_ENABLED	No	Pre-write backups to .cursidian-trash (default true; set false to disable)
OBSIDIAN_LOG_LEVEL	No	debug, info, warn, error (default info)

Development

npm run dev      # run server directly (stdio)
npm test         # vitest with coverage
npm run test:file -- tests/tools/read-note.test.ts  # focused test file, no coverage threshold
npm run test:clean # coverage run through npm env cleanup for Cursor sandboxes
npm run lint     # eslint
npm run typecheck
npm run build    # slop:check (prebuild), then tsc
npm run verify   # lint + typecheck + test + build + MCP integration + skills check + fixture smoke
npm run smoke    # live smoke against OBSIDIAN_VAULT_PATH (unique path, finally cleanup)
npm run skills:check
npm run mcp:test -- suite smoke

In Cursor agent sandboxes, npm may inherit a deprecated npm_config_devdir value. Use npm run verify or npm run test:clean so child processes run through the repository's npm environment cleanup. On Windows PowerShell, prefer these scripts over manual && command chains.

Isolated tool calls:

npm run mcp:test -- note --action read --path index
npm run mcp:test -- search --query "wiki index" --limit 10
npm run mcp:test -- --list

License

MIT - see LICENSE.