npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@promptowl/contextnest-mcp-server

v2.16.0

Published

MCP server for governed, versioned, AI-ready context — gives Claude, Cursor, Gemini, Copilot, and Windsurf access to structured knowledge bases

Readme

@promptowl/contextnest-mcp-server

Governed context for your AI agents — not memory.

by PromptOwl | Website | Whitepaper | Specification | Discord

npm License: AGPL-3.0 SOC 2 Type 2

MCP server for Context Nest — gives AI agents direct access to your context vault via the Model Context Protocol. Every node is typed, versioned, and hash-chained, so what the agent reads is governed and auditable, not a fuzzy memory blob. Supports all node types — documents, source nodes, and skill nodes. Exposes 47 tools over stdio transport: 27 canonical context_* tools, 9 vault, review and drift tools, and 11 deprecated aliases.

New in 2.2.1 — context_folders lists the vault's folders and their document counts without opening a document, and context_list takes a folder to read one folder instead of crawling the whole vault. Writes on a large vault no longer slow down as its checkpoint chain grows.

New in 2.1 — the server now installs zero dependencies, down from 97 packages at depth 11. context_import also gained the whole folder-import flow, so an existing folder of markdown can be imported in one call.

New in 2.0 — sixteen canonical context_* tools are generated straight from the engine's operation catalog, so this server, the ctx CLI and the PromptOwl cloud now advertise the same names, schemas and error codes. The older tools still work and are marked deprecated. See Upgrading to 2.0.

Install

Run it directly, no install:

npx -y @promptowl/contextnest-mcp-server /path/to/your/vault

Or install globally:

npm install -g @promptowl/contextnest-mcp-server

Zero dependencies, no install scripts. Everything the server needs is compiled into the published bundle, so the install pulls one package and executes none of our code. A stdio server never touches the SDK's express, hono, ajv or jose transports, and they are no longer shipped. Every bundled package is listed with its version and licence in DEPENDENCIES.md.

Usage

With Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "contextnest": {
      "command": "contextnest-mcp",
      "args": ["/path/to/your/vault"]
    }
  }
}

With Claude Code

claude mcp add contextnest -- contextnest-mcp /path/to/your/vault

With Gemini CLI

gemini mcp add contextnest -- contextnest-mcp /path/to/your/vault

Standalone

contextnest-mcp /path/to/your/vault

The positional argument may also be a registered alias (see the CLI's ctx vault add), in which case the path is looked up in the central registry (~/.contextnest/config.yaml):

contextnest-mcp work

Or via environment variable:

# Absolute path
CONTEXTNEST_VAULT_PATH=/path/to/vault contextnest-mcp
# …or a registered alias (overrides the registry default)
CONTEXTNEST_VAULT=work contextnest-mcp

The vault is resolved with this precedence: CONTEXTNEST_VAULT (alias) → CONTEXTNEST_VAULT_PATH (path) → positional argument (alias or path) → a vault found above the current directory → the registry's default alias → the current directory.

Tools

Canonical tools (context_*)

Name, description and input schema for each of these come from the engine's operation catalog, so this surface cannot drift from the CLI or the cloud. Prefer them over the legacy tools below.

| Tool | Description | |------|-------------| | context_init | Open a vault: its CONTEXT.md instructions, configuration, path, and what it holds (totals, counts by type and status, tag set). include_nodes to also list nodes | | context_nests | List every nest in the central registry — alias, path, description, which is default, whether it exists | | context_skill | Render a type: skill node for an agent harness (Claude Code, Cursor, Codex, raw) — trigger becomes the harness matcher | | context_skill_install | Build the file manifest that installs a vault skill. Loader mode (default) fetches at runtime and cannot drift; full embeds an offline copy that will | | context_structure | The nest's structure rules — allowed folders, node types, folder/file-name formats, templates and required sections/files. folder resolves one folder's rule with its template body; report lists existing content that breaks the rules. Writes that break an enforced rule are refused | | context_get | Read one node. include_raw for the exact stored bytes, verify_checksum to detect drift on read, allow_rejected to read a retired node. Returns last_edit: who made the version served (the human, plus the agent that made the call) | | context_list | List nodes with folder / type / status / tag filters. Takes folder (a path relative to the vault root — the id prefix) and recursive, an array of types, include_retired, full, limit, and include_last_edit (who last edited each row) | | context_folders | List the vault's folders and their document counts, read from directory entries without opening a document. folder to scope it, recursive: false for the immediate children only | | context_search | Search published nodes, best match first. mode: lexical (stemmed BM25, default), semantic (embeddings), hybrid (RRF of both, exact title/#tag matches pinned); rerank re-scores the top hits. Each hit carries score + per-signal scores | | context_embed | Build/refresh the embedding index for semantic/hybrid search — published nodes only, re-embeds only new/changed versions, prunes the rest (rebuild to start over) | | context_query | Selector query with graph traversal. include_drafts for authoring surfaces | | context_resolve | Resolve a selector to full bodies within a token budget | | context_versions | List a document's version history (new capability — nothing exposed this before) | | context_reconstruct | Reconstruct a specific version. Refuses a version the history does not contain, instead of returning a neighbour's content | | context_packs | List packs, each with its includes and excludes | | context_verify | Verify every hash chain in the vault and rebuild every recorded version (version_unreconstructable when one cannot be rebuilt). Forgotten versions verify hash-only (tombstoned) | | context_forget | Forget a node (spec §6.3): erase every version's content, keep the hashes so verify still passes, leave an empty status: forgotten stub every URI resolves to. reason_code is a closed set, never free text. Later republish/re-import of the content is refused | | context_forget_log | The forget audit trail: who, when, reason code, which versions. Never the content | | context_archive | Archive a node: out of lists and retrieval, history kept (spec §1.13) | | context_unarchive | Bring an archived node back in the status it left | | context_move | Move a node to another folder with its history and any PDF | | context_create | Create a node. Mint your own id, keep it a draft with publish: false, set an initial status, record a note, or supply a full skill block | | context_update | Update a node — rename via title, set status, stamp an explicit version, clear a metadata key by sending null. Defaults to not publishing when status names a non-published state | | context_publish | Publish a node (bump version, seal checkpoint); takes a note, returns the chain_hash | | context_delete | Delete a node and its version history, recorded in the forget audit log (purge: true for none); returns the deleted node's title | | context_import_pdf | Import a PDF (bytes_base64) as a type: pdf node: extracted text as the body (<!-- page N --> markers; empty + text_layer: false for a scan), the PDF stored beside it and bound by SHA-256. Pass id of an existing pdf node for a new version — the old binary is kept in history | | context_import | Bulk create-and-publish. Takes documents (title + content) and/or ids (files already in the vault, published as-is) — a mixed batch seals one checkpoint and regenerates the index once |

client — attributing a call

Every tool above takes an optional client object naming the calling agent and its session, plus any custom scalar keys:

context_create({
  title: "API Design",
  content: "…",
  client: { agent: "claude-code", session_id: "s-9f2" }
})

A write that publishes records it on the version-history entry it seals, so context_versions can answer which agent wrote v7, in which session; a graph read stamps it on the access traces it emits.

Every field is optional — client itself, and agent/session_id within it. Send none, one, or all.

You usually do not need to send it. The server fills both fields from what the connection already tells it: agent from the clientInfo.name in your initialize handshake, and session_id from a per-process id — over stdio one server process is one client connection, so every call sharing that id really did come from one session. Anything you send wins, merged per key: supply just agent and you keep it while still getting a session id.

| Env var | Effect | |---------|--------| | CONTEXTNEST_NO_ATTRIBUTION=1 | Server derives nothing; nothing is recorded unless a caller sends its own client | | CONTEXTNEST_AGENT | Overrides the agent the handshake reports | | CONTEXTNEST_SESSION_ID | Overrides the per-process session id |

Precedence per key: caller > env > connection. With attribution off and no caller value, the client key is left off the record entirely rather than written as {} — "not attributed" and "attributed to nobody" are different claims, and history should only make the first. The opt-out matters because what gets derived lands in an append-only history: an operator who does not want their client's name recorded in a vault needs to say so before the first write, not scrub it after.

It is a label, never an identity claim — clientInfo.name is your self-report, the server authenticates neither, and it never authorizes from either — and it is not an input to any hash chain. Note that client describes the CALL; metadata on context_create / context_update is frontmatter and describes the DOCUMENT. See spec §9.4.

Vault tools

| Tool | Description | |------|-------------| | document_format | Get the document format spec (call before creating docs) | | read_index | Return the context.yaml graph index | | read_pack | Resolve and return a context pack | | list_checkpoints | List recent checkpoints | | context_review | Controls the review gate. It can list held writes, approve or reject one by id, and turn the gate off or on. |

Deprecated tools

Registered and behaving exactly as before, so existing clients keep working. They will be removed in a future major.

| Deprecated | Use instead | |------|-------------| | vault_info | context_init | | read_document | context_get | | list_documents | context_list | | search | context_search | | resolve | context_resolve | | read_version | context_reconstruct | | verify_integrity | context_verify | | create_document | context_create | | update_document | context_update | | publish_document | context_publish | | delete_document | context_delete |

Drift Governance

When a live file drifts from its last-approved bytes, these tools capture and resolve the change without touching the canonical document or hash chain until approved:

| Tool | Description | |------|-------------| | stage_drift_suggestion | Capture an out-of-band edit as a staged suggestion under _suggestions/ (does not modify canonical doc or chain) | | list_suggestions | List all staged suggestions for a document | | approve_suggestion | Apply a staged suggestion: patch, bump version, write new canonical bytes, archive under _archive/approved/ | | reject_suggestion | Reject a staged suggestion: archive under _archive/rejected/, emit a chain event (reason required for audit trail) |

Typical flow: verify_integrity detects drift → stage_drift_suggestion → list_suggestions → approve_suggestion or reject_suggestion.

Selector Grammar

The resolve tool takes a selector. One-liner:

#tag  type:X  status:X  pack:id  contextnest://path   ·   combine with + (AND)  | (OR)  - (NOT)  ( ) to group

Example: resolve({ selector: "(#api | #auth) + status:published - #deprecated" }). Full grammar in the specification.

Graph Traversal

The resolve, search, and read_pack tools support graph-aware queries:

  • hops (number, default: 2) — Controls traversal depth from matched documents. More hops = more context loaded, slower. Fewer hops = faster, less context.
  • full (boolean, default: false) — Bypass graph traversal and load all documents (legacy mode).

Skill Nodes

Agents can discover and use skill nodes — governed procedures with triggers, inputs, and guard rails:

context_resolve({ selector: "type:skill + #engineering" })  → all engineering skills
context_list({ type: "skill" })                             → all skill nodes
context_create({ type: "skill", trigger: "..." })           → create a new skill

Upgrading to 2.0

Nothing in your MCP client config changes. The old tools are all still registered. Four things do change:

context_overview is removed. It returned counts and a node list. context_init now returns everything it did plus the vault's CONTEXT.md instructions, its configuration and its path — so opening a vault is one call instead of two. vault_info is an alias for context_init now, which is what that name always promised. Node lists are opt-in behind include_nodes.

Document ids are taken exactly as stored. A bare slug is no longer re-rooted under nodes/. If you were passing api-design to read_document and relying on it finding nodes/api-design, pass the full id to context_get. This is what makes flat-layout vaults work at all — every id from one used to resolve to a document that does not exist. A trailing .md and leading slashes are still stripped.

context_import output changed: created → published, and checkpoint is added. failed entries carry id (for the ids path) or title (for the documents path), not title unconditionally.

context_update semantics: title now sets a new title rather than selecting the node to update — select by id. tags replaces the tag set rather than merging into it; send the merged set if you want the old behaviour. A null metadata value clears that key.

Two long-standing filter bugs are fixed in context_list, which may return results where it previously returned nothing: status: "rejected" could never match, and type: "document" skipped every document that omitted the optional type field. Tags now match with or without a leading # and regardless of case.

Ecosystem

The MCP server is one of four ways into the same vault — same file format, same governed history:

| | What it is | Get it | |---|---|---| | CLI (ctx) | Build and query the vault from the terminal | @promptowl/contextnest-cli | | MCP server | Agent access over the Model Context Protocol (this package) | @promptowl/contextnest-mcp-server | | Engine | Core library — parsing, storage, versioning, graph traversal | @promptowl/contextnest-engine | | PromptOwl cloud | Hosted packs, SSO, approvals, role-scoped publishing | promptowl.ai |

Drop the server into any MCP-capable agent — Claude Desktop, Claude Code, Cursor, Gemini CLI, Windsurf — to plug the same vault into your IDE or chat client.

Links

License

AGPL-3.0 — your files, your agent, your vault. No vendor lock-in. Commercial licensing available when you want to embed; contact PromptOwl.