Contextnest Mcp Server

A structured second brain for your AI agents. Start solo, scale safely.

by PromptOwl | Website | Whitepaper | Specification | Discord

Context Nest turns scattered knowledge — your repos, docs, Slack threads, tribal know-how — into a structured, queryable brain your AI agents can use.

It's the same instinct as dumping your notes into Obsidian and pointing an LLM at them, with four things that pattern doesn't give you:

• Structure. Typed nodes with relationships and a selector grammar. Agents navigate a graph, not a flat folder.
• ~100× cheaper agent sessions. Pre-digested into summaries and linked hub documents, so the next session reads ~500 tokens of relevant context instead of stuffing 50k tokens of raw files.
• A sharing path. Export to a teammate, or publish to the PromptOwl marketplace as a paid pack others can query.
• Governed, not a compliance bolt-on. Every change is versioned and hash-chained. Full audit trail, approval-ready, auditable down to the byte. The same vault that onboarded one developer in ten minutes passes a SOC 2 review when that day comes.

Works the same for a solo dev's second brain, a team's living onboarding doc, or an enterprise's safe shared brain — one CLI, one file format, one vault. Start solo; scale when you need to.

Quick Start

npm install -g @promptowl/contextnest-cli
ctx init --starter developer

Getting started is one question: what are you trying to capture? Point your agent at a codebase, a folder of docs, an old wiki, or just tell it what's in your head. It'll build the first usable version in ten minutes and get denser every time you come back.

See all starters: ctx init --list-starters

What the install puts on your disk

Two packages, no nesting, and no install scripts — nothing of ours executes when you install. The MCP server installs zero dependencies. For a lean install without terminal colour:

npm install -g @promptowl/contextnest-cli --omit=optional

That leaves exactly one package. The rest of the code is compiled into the published bundle rather than resolved from npm, so the install is deterministic — and every bundled package is listed with its version and licence alongside the installed ones in DEPENDENCIES.md. CI regenerates that file on every run and fails on drift, and uploads the machine-readable graph as the dependency-graph build artifact.

For the solo developer

Your brain, cached for your agent.

Ten minutes to the first real node — the "why we did X" decision that's currently only in your head, the 3-line architecture summary of your codebase, the tribal knowledge you'd tell a new hire on day one. Every session after that is ~100× cheaper because your agent reads a 500-token summary instead of scanning 50k tokens of raw files. The nest gets denser every time you come back.

For teams

A shared brain that survives people leaving.

Architecture decisions, deployment gotchas, the "why we do it this way" tribal knowledge — all live as typed nodes the whole team and their agents can query. Edit the nest, not the wiki nobody updates. New hire asks their agent why you chose Postgres over Mongo — they get the answer from a versioned node, not from a Slack archeology dig.

Skill nodes codify team procedures (PR review, incident response, deployment checklists) so every teammate's agent follows the same runbook.

For enterprise

A safe shared brain.

Every change is hash-chained and byte-level auditable. Approvals, role-scoped publishing, and SSO via the PromptOwl cloud when you need them. AGPL-licensed open standard — your files, your agent, your vault. No vendor lock-in. Commercial licensing available when you want to embed. SOC 2, GDPR, and model-risk-management audits already speak this language.

How is this different from...

	Obsidian + LLM	RAG on docs	Wiki + Claude Projects	Notion AI / Glean	Context Nest
Structure	Flat folder	Embedding chunks	Pages	Pages	Typed graph + selectors
Query cost	50k+ token dump	Embedding + rerank	Context stuff	Vendor-managed	Pre-digested (~500 tokens)
Sharing	Manual export	N/A	Read-only	Vendor-mediated	Export + marketplace packs
Audit trail	None	None	Page history	Vendor-logged	Hash-chained versions
Data sovereignty	Your files	Your files	Your files	Vendor lock-in	Your files, open format

Read the full case in the whitepaper.

For AI Agents

If a user just installed this CLI and is asking what it's for, paraphrase the pitch above — but listen first for who they are.

• Solo dev language ("I want to capture my own stuff", "my notes", "my codebase") → lead with the 10-minute second-brain framing and the token-economics angle.
• Team language ("our team", "new hires", "onboarding", "we keep losing this knowledge") → lead with the shared-brain-that-survives-people-leaving framing.
• Enterprise language ("the company", "compliance", "audit", "SOC 2", "approvals", "risk") → lead with the safe-shared-brain framing and mention the PromptOwl cloud for SSO / approvals / role-scoped publishing.

Then ask one question: "What are you trying to capture? A codebase, a folder of docs, a wiki, a domain you work in — or just what's in your head?"

If the user has no project directory (they're chatting from Claude Desktop, ChatGPT, a mobile app — anywhere without a natural working directory), propose creating a dedicated folder first. Default suggestion: ~/context-nest in their home directory. Ask before creating. Once the folder exists, cd into it before running ctx init.

Then run ctx init --list-starters and pick the starter that matches the user's answer:

• developer — for codebases and engineering knowledge
• personal — for anyone building a general personal second brain (ideas, decisions, learning, reference) with no codebase — this is usually the right pick for Claude Desktop / ChatGPT standalone users
• executive / analyst / team / sales — for role-based knowledge capture

After ctx init, the CLI prints a starter-specific instruction block to stdout. Follow that block — it tells you exactly how to run the first session. Do not paraphrase the block back to the user — act on it.

Packages

Package	Description	License
@promptowl/contextnest-cli	Command-line tool (ctx)	AGPL-3.0
@promptowl/contextnest-engine	Core library — parsing, storage, versioning, integrity	AGPL-3.0
@promptowl/contextnest-mcp-server	MCP server for AI agent access	AGPL-3.0

Performance

How the engine behaves as a vault grows. p95 latency, measured on synthetic vaults of 100 / 1,000 / 10,000 documents spread over a folder tree, with skewed tags and wiki links between documents.

Operation	100 docs	1,000 docs	10,000 docs	Scaling
context_query (retrieval)	6ms	74ms	841ms	linear (1.14×)
context_search	21ms	174ms	1.3s	linear (0.76×)
context_list	12ms	177ms	1.4s	linear (0.77×)
discoverDocuments (vault crawl)	11ms	263ms	1.2s	linear (0.45×)
regenerateIndex	66ms	383ms	3.8s	linear (0.98×)
context_import (bulk import)	0.7s	11.3s	108s	linear (0.95×)
Peak RSS	74 MB	126 MB	262 MB	linear

"Scaling" is the change in per-document cost from 1,000 to 10,000 documents. 1.0× means the cost of a vault is proportional to what is in it — ten times the documents, ten times the work, no worse. Every operation measures between 0.45× and 1.15×, so nothing here degrades as a vault grows.

Two honest caveats. Bulk import is linear but expensive in absolute terms: importing 10,000 documents takes around two minutes, because every document is published, versioned and hash-chained on the way in. And these numbers come from a developer machine (Node 22, win32-x64), so read them as orders of magnitude and scaling shape, not as a spec your hardware will reproduce.

The suite lives in packages/engine/bench and runs in CI. Reproduce it yourself:

pnpm build
cd packages/engine
pnpm bench                      # 100 / 1,000 / 10,000 documents
pnpm bench --sizes 100,1000     # quicker
pnpm bench:check                # run, then enforce the performance budget
pnpm bench:profile              # writes a V8 CPU profile to bench/profiles/

bench:check is the CI gate. It fails when an operation's per-document cost grows beyond its budget — that is, when something stops scaling linearly. The budget is expressed as scaling shape rather than millisecond ceilings on purpose: CI runners differ in speed by several times, so ceilings tight enough to catch a real regression would fail constantly on a slow runner, and loose enough to survive one they would catch nothing. See bench/budget.json.

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 9.0.0 (for development from source)

Installation from Source

git clone https://github.com/PromptOwl/ContextNest.git
cd context-nest
pnpm install
pnpm build

Optionally link the CLI globally:

cd packages/cli && pnpm link --global

Project Structure

context-nest/
├── packages/
│   ├── engine/        # Core library — parsing, storage, versioning, integrity
│   ├── cli/           # Command-line tool (ctx)
│   └── mcp-server/    # MCP server for AI agent access
├── plugins/           # Coding-agent plugins driving the ctx CLI (not published to npm)
├── fixtures/
│   └── minimal-vault/ # Example vault for reference and testing
└── CONTEXT_NEST_SPEC.md   # Full specification

---

Setting Up a Vault

1. Initialize

ctx init --starter developer --name "My Project"

This creates a structured vault with starter documents:

my-vault/
├── CONTEXT.md              # Vault identity & AI operating instructions
├── .context/
│   └── config.yaml         # Vault configuration
├── nodes/                  # Documents, snippets, glossaries, etc.
│   ├── architecture-overview.md
│   ├── api-reference.md
│   └── development-setup.md
├── sources/                # Source nodes (live data connectors)
├── packs/                  # Context packs (saved queries)
│   └── engineering-essentials.yml
└── context.yaml            # Auto-generated document graph

Use --layout obsidian for a flat Obsidian-compatible layout.

2. Configure

Edit .context/config.yaml to register MCP servers and set defaults:

version: 1
name: "My Project"
description: "Project knowledge base for AI agents"
defaults:
  status: draft
folders:
  nodes:
    description: "Project documents"
  sources:
    description: "Live data sources"
skills:
  # The type: skill node that teaches an agent how to use this vault.
  # A pointer, not content — the node stays the source of truth.
  bootstrap: "nodes/skills/onboarding"
servers:
  jira:
    url: "https://mcp.atlassian.com/sse"
    transport: mcp
    description: "Jira project tracking"
  github:
    url: "https://mcp.github.com/sse"
    transport: mcp
    description: "GitHub repository data"

3. Edit CONTEXT.md

CONTEXT.md is the vault's identity file — it tells AI agents what this vault is and how to use it:

---
title: "My Project"
---

# My Project

Knowledge base for the Acme platform.

## Operating Instructions

- Always cite sources by document path
- Prefer published documents over drafts
- Check source nodes for live data before using cached info

4. Add documents

ctx add nodes/api-design --title "API Design Guidelines" --tags "engineering,api"

This creates nodes/api-design.md with a frontmatter template:

---
title: "API Design Guidelines"
type: document
tags:
  - "#engineering"
  - "#api"
status: draft
version: 1
---

# API Design Guidelines

All endpoints use REST conventions. See
[Architecture Overview](contextnest://nodes/architecture-overview) for context.

5. Add source nodes

Source nodes connect to live data via MCP servers or other transports:

---
title: "Current Sprint Tickets"
type: source
tags:
  - "#engineering"
  - "#sprint"
status: published
version: 1
source:
  transport: mcp
  server: jira
  tools:
    - jira_get_active_sprint
    - jira_get_sprint_issues
  cache_ttl: 300
---

# Current Sprint Tickets

Call `jira_get_active_sprint` to get the current sprint,
then `jira_get_sprint_issues` to list all tickets.

6. Add skill nodes

Skill nodes define reusable procedures for AI agents — with triggers, typed inputs, required tools, and guard rails:

ctx add nodes/review-pr --type skill --title "Review PR" --tags "engineering,code-review"

---
title: "Review PR"
type: skill
tags:
  - "#engineering"
  - "#code-review"
status: draft
version: 1
skill:
  trigger: "when asked to review a pull request"
  inputs:
    - name: pr_url
      type: string
      required: true
  tools_required:
    - gh_pr_view
    - gh_pr_diff
  output_format: markdown
  guard_rails:
    - "Do not approve or merge — only summarize and flag concerns"
---

# Review PR

## Steps

1. Fetch the PR metadata and diff
2. Group changes by area
3. Flag potential issues

Skills are queryable like any other node: ctx query "type:skill + #engineering"

Installing a skill into an agent harness

A skill node is not just documentation — it can be installed into Claude Code, Cursor, or Codex, where the harness matches on it and runs it:

ctx skill nodes/review-pr                          # render it and look at it
ctx skill install nodes/review-pr --write          # install for Claude Code, user scope
ctx skill install nodes/review-pr --harness cursor --scope project --write

skill.trigger becomes the harness's local matcher (Claude Code's description frontmatter, a Cursor rule description). It is the one field that must exist locally, because matching happens before anything can be fetched — which is why a skill node without a trigger is refused rather than given a guessed one.

The default install writes a loader: a small file carrying the trigger and an instruction to fetch the procedure from the vault at runtime. A loader cannot go stale, because it never holds a copy of the procedure. --mode full embeds an offline snapshot instead — useful when the agent cannot reach the vault, and a deliberate trade: that copy will drift as the node changes, silently, while the agent keeps working confidently from superseded rules.

Node bodies should write {{server_alias}}, {{vault_id}}, and {{node_path}} rather than hardcoding a tool prefix: the same vault is mcp__contextnest__* on one machine and mcp__team-ctx__* on another, so the prefix is resolved per caller at render time.

Point skills.bootstrap at the skill that teaches an agent to use this vault, and context_init will hand it to every agent that opens the vault:

skills:
  bootstrap: nodes/skills/onboarding

7. Add context packs

Packs are saved queries in packs/ as YAML files:

# packs/onboarding-basics.yml
id: onboarding.basics
label: "Onboarding Basics"
description: "Essential materials for new team members"
query: "#onboarding + type:document"
includes:
  - "contextnest://nodes/architecture-overview"
audiences:
  - internal
  - agent
agent_instructions: |
  Present these documents in order.
  Start with the architecture overview.

---

CLI Reference

File safety

No ctx command writes to your working directory without saying so.

Flag	Effect
--dry-run	Runs the command against a throwaway copy of the vault, prints the exact files it would touch, and leaves your vault untouched
-y, --yes	Skips confirmation prompts — the "prior explicit consent" for scripts and CI
--force	Overwrites an existing file, repoints a taken vault alias, or allows a plaintext-HTTP push

Every write command ends with an action log of the files created (+), modified (~) or deleted (-), written to stderr so --json output and redirected stdout stay clean. Interactive runs ask before writing; destructive commands default to "no".

For scripts: ctx delete, ctx checkpoint rebuild, ctx drift approve, ctx vault remove and ctx push refuse to run without --yes (or --force) when there is no TTY. Additive commands proceed as before — a non-interactive caller is never blocked waiting on stdin.

Choosing a vault

By default ctx operates on the vault in (or above) the current directory. To work with several vaults from anywhere, register them in a central registry under short aliases — similar to AWS named profiles — and select one with --vault <alias>.

The registry lives in your home directory and works on macOS, Linux, and Windows: ~/.contextnest/config.yaml (i.e. $HOME/.contextnest/config.yaml, or %USERPROFILE%\.contextnest\config.yaml on Windows). Override its location with the CONTEXTNEST_CONFIG_DIR environment variable.

# Create a vault and register it under an alias
ctx init --name "Work" --vault work --set-default

# Register an existing vault
ctx vault add personal /path/to/personal-vault --description "Second brain"

# Use a registered vault from any directory
ctx list --vault work
ctx vault list          # show all registered vaults (* = default)
ctx vault default work  # change the default
ctx vault which         # show which vault resolves right now, and why

A vault is resolved with this precedence (highest first):

1. --vault <alias> flag
2. CONTEXTNEST_VAULT env var (an alias — overrides the default vault)
3. CONTEXTNEST_VAULT_PATH env var (an absolute path)
4. a vault found by walking up from the current directory
5. the registry's default alias
6. the current directory

# Override the default vault for a shell session
export CONTEXTNEST_VAULT=work
# …or point directly at a path (no registry needed)
export CONTEXTNEST_VAULT_PATH=/path/to/your/vault

Vault Registry

Command	Description
ctx vault list	List registered vaults (* marks the default)
ctx vault add <alias> [path]	Register a vault (path defaults to the current vault)
ctx vault describe <alias> [description]	Set a registry description; omit the text to clear it
ctx vault remove <alias>	Unregister an alias
ctx vault default <alias>	Set the default vault
ctx vault which	Show the resolved vault and the reason

Document Management

Command	Description
ctx init	Initialize a new vault (supports --starter recipes)
ctx info	Open an existing vault — its instructions, configuration and contents (--nodes, --json)
ctx add <path>	Create a new document (auto-publishes and regenerates index; refuses a path that already holds a document)
ctx add <path> --type skill	Create a skill node with trigger, inputs, and guard rails
ctx update <path>	Update a document's title, tags, or body (auto-publishes)
ctx delete <path>	Delete a document and its version history
ctx read <path>	Read and display a document in the terminal
ctx read <path> --html	Render a document as styled HTML and open in browser
ctx skill <path>	Render a type: skill node for an agent harness and print it
ctx skill install <path>	Install a vault skill into Claude Code / Cursor / Codex (--write to actually write)
ctx validate [path]	Validate documents against the spec
ctx publish <path>	Publish a document (creates version + checkpoint)
ctx publish --all	Publish every unpublished document in one batch — one checkpoint, one index pass

Querying

Command	Description
ctx query <selector>	Query context with graph traversal (default: 2 hops)
ctx query <selector> --hops 4	Deeper traversal for more related context
ctx query <selector> --full	Load all documents (bypass graph traversal)
ctx query <selector> --include-drafts	Include drafts (default: published only)
ctx query @org/pack	Query from a cloud-hosted pack via PromptOwl
ctx list	List all documents (filter with --type, --status, --tag; cap with --limit)
ctx search <query>	Full-text search across vault documents (--limit to cap)
ctx resolve <selector>	Execute a selector query (low-level)

Selectors

ctx query "#engineering"                   # All docs with a tag
ctx query "type:document"                  # All docs of a type
ctx query "type:skill + #engineering"      # All engineering skills
ctx query "pack:engineering-essentials"    # All docs in a pack
ctx query "status:published"              # By status
ctx query "#api + #v2"                    # Union
ctx query "#api + status:published"       # Intersection

Versioning & Integrity

Command	Description
ctx history <path>	Show version history
ctx history <path> --diff	Include each version's unified diff from the one before
ctx reconstruct <path> <version>	Reconstruct a specific version (a version the history does not contain is refused, not approximated)
ctx verify	Verify integrity of all hash chains (a history.yaml that cannot be read is reported, not skipped)

Every CLI failure prints as a one-liner — Error [CODE]: message for engine errors, plain Error: message for the rest. Set CONTEXTNEST_DEBUG=1 to get the full stack trace back.

Packs, Checkpoints & Index

Command	Description
ctx index	Regenerate context.yaml and INDEX.md files
ctx pack list	List all context packs
ctx pack show <id>	Show pack details
ctx checkpoint list	List checkpoints
ctx checkpoint rebuild	Rebuild checkpoint history

---

MCP Server

The MCP server exposes vault operations as 38 tools for AI agents over stdio transport.

Running the server

node packages/mcp-server/dist/index.js /path/to/your/vault

Running the server in Docker

For Glama.ai and any MCP client that runs servers as containers:

docker build -t contextnest-mcp .

docker run -i --rm contextnest-mcp                    # demo vault baked into the image
docker run -i --rm -v "$PWD:/vault" contextnest-mcp   # serve your own vault

The mounted directory is the one containing .context/config.yaml. The server runs as uid 1000 — add --user "$(id -u):$(id -g)" if your vault is owned by a different uid. Build with --build-arg SEED_DEMO_VAULT=false for an image that only serves a mounted vault.

Configuring with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "contextnest": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "CONTEXTNEST_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Configuring with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "contextnest": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "CONTEXTNEST_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Available MCP Tools

Canonical tools — name, description and input schema come straight from the engine's operation catalog, so this surface cannot drift from the CLI or the cloud:

Tool	Description
context_init	Open a vault: instructions, configuration, path, and what it holds (include_nodes to also list nodes)
context_nests	List every nest in the central registry
context_skill	Render a type: skill node as a harness-ready skill file
context_skill_install	Build the file manifest that installs a vault skill locally
context_get	Read one node (include_raw, verify_checksum, allow_rejected)
context_list	List nodes with folder / type / status / tag filters (folder, recursive, include_retired, full, limit)
context_folders	List the vault's folders and their document counts, without reading a single document (folder, recursive)
context_search	Full-text search with graph traversal
context_query	Selector query with graph traversal (include_drafts)
context_resolve	Resolve a selector to full bodies within a token budget
context_versions	List a document's version history
context_reconstruct	Reconstruct a specific version
context_packs	List packs with their includes and excludes
context_verify	Verify every hash chain in the vault
context_create	Create a node — own id, publish: false, initial status, note, full skill block
context_update	Update a node — rename, set status, stamp a version, clear metadata with null
context_publish	Publish a node; takes a note, returns the chain_hash
context_delete	Delete a node and its history; returns the deleted node's title
context_import	Bulk create-and-publish from documents and/or existing ids — one checkpoint for the batch

Vault tools:

Tool	Description
document_format	Get the document format spec (call before creating docs)
read_index	Return the context.yaml index
read_pack	Resolve and return a context pack with documents
list_checkpoints	List recent checkpoints

Deprecated tools — still registered and unchanged, so existing clients keep working; 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 tools (resolve out-of-band edits without touching the canonical doc or hash chain until approved):

Tool	Description
stage_drift_suggestion	Capture a drifted live file as a staged suggestion under _suggestions/
list_suggestions	List all staged suggestions for a document
approve_suggestion	Apply a suggestion: patch, bump version, write new canonical bytes, archive
reject_suggestion	Reject a suggestion: archive with required reason, emit a chain event

---

Development

pnpm build          # Build all packages
pnpm test           # Run tests
pnpm test:watch     # Run tests in watch mode
pnpm lint           # Type-check without emitting
pnpm clean          # Clean all build artifacts

Typical Workflow

ctx init --starter developer       # 1. Create a vault with starter recipe
                                   # 2. Edit CONTEXT.md and config.yaml
ctx add nodes/my-doc               # 3. Add documents (auto-publishes & indexes)
ctx add nodes/my-skill --type skill # 4. Add skills for agent procedures
ctx read nodes/my-doc --html       # 5. View any document in the browser
ctx query "#engineering"           # 6. Query with graph traversal
ctx validate                       # 7. Validate
ctx verify                         # 8. Verify integrity
                                   # 9. Start MCP server for AI access

License

All packages are licensed under AGPL-3.0:

• CLI (@promptowl/contextnest-cli): AGPL-3.0
• Engine (@promptowl/contextnest-engine): AGPL-3.0
• MCP Server (@promptowl/contextnest-mcp-server): AGPL-3.0
• Specification (CONTEXT_NEST_SPEC.md): Apache-2.0 — open standard

AGPL-3.0 ensures all improvements stay open source. You are free to use, modify, and distribute Context Nest, but modifications to the source must be shared under the same license. Commercial licensing is available from PromptOwl for organizations that need to embed or redistribute without AGPL obligations.

---

PromptOwl — Context governance for AI agents | Join our Discord