LocalNest MCP

A local-first MCP server that gives AI agents safe access to your codebase, plus optional local memory and semantic indexing for high-quality retrieval.

Documentation: https://wmt-mobile.github.io/localnest/

Current beta package: 0.0.4-beta.6

Engineering docs for contributors:

• guides/README.md

• guides/repository-structure.md

• guides/architecture.md

• guides/code-standards.md

What It Does

• File discovery — scoped, safe reads under configured roots

• Lexical search — fast ripgrep-backed pattern/symbol search

• Semantic indexing — sqlite-vec or JSON backend, fully local

• Hybrid retrieval — lexical + semantic fusion with RRF ranking

• Project introspection — roots, projects, tree, summaries

• Local agent memory — durable project knowledge, preferences, and recall, stored on your machine

All data stays on your machine. No external indexing service required.

Requirements

• Node.js >=18

• ripgrep (rg) recommended for fastest lexical search (server still starts without it)

Install ripgrep:

Installation

Global install (recommended):

npm install -g localnest-mcp
localnest setup
localnest doctor

npx fallback (if global install is unavailable):

npx -y localnest-mcp-setup
npx -y localnest-mcp-doctor

Global install is preferred — it gives more deterministic dependency resolution and avoids transient npx cache issues.

Check the installed CLI version:

localnest version

Upgrade command:

localnest upgrade
localnest upgrade 0.0.4-beta.6
localnest upgrade install 0.0.4-beta.6

Model download readiness (recommended per user account):

localnest doctor --verbose
localnest setup

• Setup warms embedding/reranker models on first run (downloads into ~/.localnest/cache by default).

• If ~/.localnest/cache is not writable, LocalNest automatically falls back to a per-user temp cache path.

• Cache fallback is informational when startup still succeeds, but model files will not persist in the preferred cache location until the preferred path is writable again.

• If your environment is offline/restricted, skip warmup and run it later:

localnest setup --skip-model-download=true

• If default cache path is not writable, set a user-writable cache path before setup:

export LOCALNEST_EMBED_CACHE_DIR="$HOME/.cache/localnest-models"
export LOCALNEST_RERANKER_CACHE_DIR="$HOME/.cache/localnest-models"
localnest setup

MCP Client Configuration

After running setup, LocalNest tries to detect supported AI tools on the current machine and writes or updates their LocalNest MCP entry automatically. It also saves ~/.localnest/config/mcp.localnest.json for manual copy or clients you want to configure yourself:

{
  "mcpServers": {
    "localnest": {
      "command": "localnest-mcp",
      "startup_timeout_sec": 30,
      "env": {
        "MCP_MODE": "stdio",
        "LOCALNEST_CONFIG": "~/.localnest/config/localnest.config.json",
        "LOCALNEST_INDEX_BACKEND": "sqlite-vec",
        "LOCALNEST_DB_PATH": "~/.localnest/data/localnest.db",
        "LOCALNEST_INDEX_PATH": "~/.localnest/data/localnest.index.json",
        "LOCALNEST_MEMORY_ENABLED": "false",
        "LOCALNEST_MEMORY_BACKEND": "auto",
        "LOCALNEST_MEMORY_DB_PATH": "~/.localnest/data/localnest.memory.db"
      }
    }
  }
}

Windows: Setup writes the correct command for the host platform in mcp.localnest.json — use the generated file directly.

Restart your MCP client after updating the config.

If your client reports MCP startup timeout (for example 10s default), increase it:

[mcp_servers.localnest]
startup_timeout_sec = 30

Supported Auto-Configured AI Tools

Setup currently auto-detects and updates these tools when their config directories are present:

• Codex

• Cursor

• Windsurf

• Windsurf (Codeium-managed config)

• Gemini CLI / Antigravity

• Kiro

Setup writes a backup under ~/.localnest/backups/ before modifying a detected client config.

Direct Binary vs npx

Prefer the direct binary when localnest-mcp is installed globally:

{
  "command": "localnest-mcp"
}

Use npx only as a fallback when a global install is unavailable:

{
  "command": "npx",
  "args": ["-y", "localnest-mcp"]
}

If MCP startup fails before initialize, check whether:

• the client is still launching through npx

• npm cache permissions are broken for the current user

• startup_timeout_sec is too low for the current machine

• localnest-mcp --version works directly

Tools

All tools support response_format: "json" (default) or "markdown". Only canonical localnest_* tool names are exposed (no short aliases) to keep MCP clients clean and non-duplicative. Each MCP response also includes meta.schema_version so clients can detect contract revisions explicitly.

List tools return pagination fields: total_count, count, limit, offset, has_more, next_offset, items.

Fast agent workflow (recommended default):

localnest_search_files (max_results: 20-30)
→ localnest_search_code (project_path + glob + max_results: 20-40 + context_lines: 2)
→ localnest_read_file (top 1-3 hits)

Use localnest_search_hybrid only when lexical search misses or you need concept-level retrieval. Keep use_reranker=false unless you need a final precision pass.

Deep-task workflow (debug/refactor/review):

localnest_server_status → localnest_task_context → localnest_index_status
→ localnest_search_hybrid (optionally use_reranker=true)
→ localnest_read_file
→ localnest_capture_outcome

Successful Execution vs Meaningful Evidence

A tool can execute successfully and still return weak evidence.

• Successful execution means the MCP call completed without transport or runtime failure.

• Meaningful evidence means the response contains useful matches, file lines, or actionable diagnostics for the current task.

Examples:

• localnest_search_code returning [] is a successful execution, but not meaningful evidence.

• localnest_read_file returning actual line content is meaningful evidence.

• localnest_update_status returning cached metadata is meaningful if it still tells the client whether an update is actionable.

For release checks and agent workflows, prefer responses that contain non-empty evidence over treating process success alone as sufficient.

Index Backend

Choose during setup or via env var:

localnest_index_status and localnest_server_status now expose:

• upgrade_recommended

• upgrade_reason

When backend=json and upgrade_recommended=true, migrate to sqlite-vec for production-scale indexing.

Configuration Reference

Setup writes two files:

• ~/.localnest/config/localnest.config.json — roots and project settings

• ~/.localnest/config/mcp.localnest.json — ready-to-paste MCP client config block

• ~/.localnest/data/ — sqlite/json index files and memory database

• ~/.localnest/cache/update-status.json — cached npm update status

• ~/.localnest/backups/ — migration and config backups

This keeps the LocalNest home directory readable:

• config/ for editable config and generated MCP snippets

• data/ for SQLite/JSON runtime data

• cache/ for refreshable metadata

• backups/ for migration history

Config priority:

1. PROJECT_ROOTS environment variable

2. LOCALNEST_CONFIG file

3. Current working directory (fallback)

Optional env vars:

Performance tips:

• Keep retrieval scoped with project_path and a narrow glob whenever possible.

• Keep max_results small first (20-40), then widen only when needed.

• Keep reranking off by default and enable it only for final answer quality on ambiguous queries.

• Avoid indexing all roots for one-off tasks; prefer project-scoped indexing.

Installed Runtime Release Testing

Before publishing a new build, run the installed-runtime release harness against the globally installed binary:

node scripts/release/release-test-installed-runtime.mjs --version-label 0.0.4-beta.6

The harness writes both markdown and JSON reports under reports/ and is intended to verify the installed runtime, not just the repo checkout.

Local Memory

Memory is opt-in during localnest setup. When enabled, LocalNest stores durable project knowledge and preferences in a local SQLite database.

• Memory currently requires Node 22.13+ for built-in node:sqlite

• Node 18/20 continue to support the rest of LocalNest, but memory stays unavailable on those runtimes

• If memory backend initialization fails, existing code search and read tools still work

For agents, the intended flow is:

localnest_task_context
→ work with code/search tools
→ localnest_capture_outcome

Use the lower-level localnest_memory_status, localnest_memory_recall, and localnest_memory_capture_event tools only when you need finer control than the bundled high-level flow.

localnest_memory_capture_event is still available for automatic/background use by AI tools. High-signal events such as bug fixes, decisions, reviews, and user preferences are promoted into durable memories; weak exploratory events are recorded and ignored.

Auto-Migration

On startup, LocalNest auto-migrates older config schemas and the older flat ~/.localnest home layout into config/, data/, cache/, and backups/. Non-destructive config backups are written under ~/.localnest/backups/. No manual setup rerun is needed for normal upgrades.

If an older MCP client config still points LOCALNEST_CONFIG at ~/.localnest/localnest.config.json, LocalNest falls forward to the new ~/.localnest/config/localnest.config.json path automatically.

Skill Distribution

LocalNest ships with a bundled AI agent skill (localnest-mcp) for Claude Code, Cursor, Codex, and other supported clients.

Run after npm install:

localnest-mcp-install-skill
# Force reinstall:
localnest-mcp-install-skill --force

localnest-mcp-install-skill now checks the installed skill version first. If the target skill is already current, it reports that instead of replacing files unnecessarily. Use --force to resync anyway.

For deterministic shell hooks or client automation, LocalNest also ships:

localnest-mcp-task-context --task "debug auth refresh" --project-path /path/to/project
localnest-mcp-capture-outcome --task "fix auth refresh" --summary "Serialized refresh requests" --project-path /path/to/project --files-changed 2 --has-tests true

Both commands also accept JSON on stdin.

Install from GitHub via skills.sh:

npx skills add https://github.com/wmt-mobile/localnest --skill localnest-mcp

Contributing

See CONTRIBUTING.md. Engineering standards and architecture references live under guides/.

Thanks to Contributors

Thanks to everyone who contributes code, docs, reviews, testing, and issue reports to LocalNest. Your work directly improves reliability and developer experience for the entire community.

Docs Site

The Docusaurus documentation site lives in localnest-docs/.

cd localnest-docs
npm install
npm run start

Trust And Security Testing

LocalNest follows the common OSS security pipeline pattern used across GitHub repos.

• CI quality gate: quality.yml

• OpenSSF Scorecard scan + SARIF upload: scorecards.yml

• CodeQL static analysis: codeql.yml

• Dependency and GitHub Actions update automation: .github/dependabot.yml

• Public Scorecard report (when indexed/public): https://scorecard.dev/viewer/?uri=github.com/wmt-mobile/localnest