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.

Related MCP server: Obsidian MCP Server

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

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:

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).

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.

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.

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):

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

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.