Quick Start Guide

Get Index Server running with HTTPS and semantic search in 5 minutes.

Prerequisites

• Node.js >= 22 LTS
• npm (included with Node.js)
• An MCP client — VS Code with Copilot, Claude Desktop, or similar

1. Install

Recommended: use the published package and setup wizard

npx -y @jagilber-org/index-server@latest --setup

This generates MCP client configuration for VS Code, Copilot CLI, or Claude Desktop and keeps the install flow MCP-native from the start.

Prefer a stable command on PATH? Install globally instead: npm install -g @jagilber-org/index-server, then index-server --setup. (GitHub Packages mirror requires authentication.)

Alternative: install or build locally

npm install @jagilber-org/index-server

Or build from source:

git clone https://github.com/jagilber-org/index-server.git
cd index-server
npm install
npm run build
npm run setup               # interactive configuration wizard

Re-run setup later

The wizard is idempotent — you can re-run it any time to change profile, port, TLS, or regenerate MCP client configs. It updates the existing data root in place rather than reinstalling.

npx -y @jagilber-org/index-server@latest --setup      # works without a global install
index-server --setup                                  # if installed globally

--configure is an alias for --setup. For scripted reconfiguration:

npx @jagilber-org/index-server --setup --non-interactive --profile enhanced

The path printed as Root: at the end of setup (e.g. C:/Users/<you>/AppData/Local/index-server) is the server's data root, not the binary location. The index-server command itself lives in npm's global bin folder — if it's not found after npm i -g, add the output of npm prefix -g to your PATH.

2. Configure MCP Client

If you used --setup, it can generate this for you. Otherwise add this to your VS Code .vscode/mcp.json:

{
  "servers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jagilber-org/index-server@latest",
        "--dashboard",
        "--dashboard-port=8787"
      ],
      "env": {
        "INDEX_SERVER_LOG_LEVEL": "info",
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions"
      }
    }
  }
}

Replace C:/mcp/index-data/instructions with your preferred persistent data directory.

Best practice: keep INDEX_SERVER_DIR in a stable data location outside VS Code and MCP client config paths so backups and reinstalls do not disturb your instruction catalog.

3. Enable HTTPS (Optional)

# Interactive (arrow-key menus)
npm run setup

# Non-interactive
node scripts/setup-wizard.mjs --non-interactive --tls --port 8787

# Or, one-shot CLI bootstrap (requires openssl on PATH):
index-server --init-cert --start --dashboard

This generates self-signed certificates in .certs/ and configures the dashboard for HTTPS.

The --init-cert switch is the lightweight CLI alternative: it generates a self-signed cert+key under ~/.index-server/certs/ and (with --start) auto-wires --dashboard-tls so no extra flags are needed. See docs/cert_init.md for the full reference.

Or manually:

# Set environment variables
INDEX_SERVER_TLS_CERT=.certs/server.crt
INDEX_SERVER_TLS_KEY=.certs/server.key
INDEX_SERVER_ALLOW_INSECURE_TLS=1   # For self-signed certs in local dev

4. Enable Semantic Search (Optional)

Add to your MCP env config:

{
  "env": {
    "INDEX_SERVER_SEMANTIC_ENABLED": "1"
  }
}

Only INDEX_SERVER_SEMANTIC_ENABLED is required — everything else has sensible defaults:

Variable	Default	Description
INDEX_SERVER_SEMANTIC_ENABLED	0	Enable semantic (embedding-based) search
INDEX_SERVER_SEMANTIC_MODEL	Xenova/all-MiniLM-L6-v2	Hugging Face model for embeddings
INDEX_SERVER_SEMANTIC_DEVICE	cpu	Inference device: cpu, dml (DirectML/GPU on Windows), cuda
INDEX_SERVER_SEMANTIC_CACHE_DIR	data/models/	Directory for downloaded model files
INDEX_SERVER_EMBEDDING_PATH	data/embeddings.json	Persisted embedding cache
INDEX_SERVER_SEMANTIC_LOCAL_ONLY	0	Skip model download, use pre-cached model only

Example with GPU acceleration (Windows DirectML):

{
  "env": {
    "INDEX_SERVER_SEMANTIC_ENABLED": "1",
    "INDEX_SERVER_SEMANTIC_DEVICE": "dml",
    "INDEX_SERVER_SEMANTIC_CACHE_DIR": "C:/path/to/shared/model-cache"
  }
}

On first search, the server downloads a ~90 MB embedding model from Hugging Face (one-time). After that, all searches default to semantic mode — no mode parameter needed. Set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=1 for air-gapped/offline environments (requires pre-cached model).

5. Verify

1. Restart VS Code / your MCP client
2. The server should appear in the MCP server list
3. Open http://localhost:8787 (or https://) for the dashboard
4. Run a health check — ask your agent: "use health_check to verify index-server is running"
5. Verify bootstrap status: "use bootstrap to check initialization status"
6. If your client supports MCP prompts, run prompts/list and confirm setup_index_server, configure_index_server, and verify_index_server appear
7. If your client supports MCP resources, run resources/list and read index://guides/quickstart

Tip: On a fresh install, bootstrap may report gated status until the bootstrapper instruction is loaded. This is normal — index_add and other mutation tools are available immediately.

Read-only setup guidance surface

Index Server now exposes a minimal Stage 2 MCP-native guidance surface for clients that support prompts/resources:

• Prompts: setup_index_server, configure_index_server, verify_index_server
• Resources: index://guides/quickstart, index://guides/client-config, index://guides/verification

Use these read-only surfaces for installation help, config review, and troubleshooting. If your client does not surface prompts/resources yet, continue with the standard tools/list + health_check flow above.

6. Add Your First Instruction

Ask your agent:

Use index_add to create an instruction with id "my-first-guide",
title "Getting Started Guide", and body with your team's onboarding steps.

Or via the dashboard: navigate to Instructions → + New.

Verify it was created:

Use index_search with keywords "getting started" to find your new instruction.

How to Invoke Tools

Different MCP clients discover tools differently:

Client	How to invoke tools
VS Code	Type #index-server in Copilot Chat to attach tools, then ask naturally
Copilot CLI	Tools are auto-discovered from ~/.copilot/mcp-config.json — just ask
Claude Desktop	Tools are auto-discovered from claude_desktop_config.json — just ask
Dashboard	Navigate to the Tools panel and invoke directly

VS Code tip: You can also invoke tools without #index-server if the server is in your .vscode/mcp.json — Copilot will auto-discover available MCP tools.

Upgrading and Uninstalling

Upgrade to the latest release

npm install -g @jagilber-org/index-server@latest
index-server --version

Wizard-driven uninstall (recommended)

The fastest way to clean up — selectively or completely — is the bundled wizard:

# Interactive: three checkbox prompts (data paths, MCP client configs, package installs)
index-server --uninstall              # aliases: --remove, --clean

# Non-interactive: wipe everything
index-server --uninstall --non-interactive --all

# Non-interactive: targeted (comma-separated keys)
index-server --uninstall --non-interactive --remove npm-global,stale-local,mcp-vscode-global

What the wizard can remove (each selectable independently):

Group	Items
Data	instructions, feedback, state, messaging, audit, logs, metrics, model-cache, embeddings, sqlite, certs, env, backups, base (entire base directory)
MCP configs	mcp-vscode-global, mcp-copilot-cli, mcp-claude — removes the index-server entry only, backs up the original file
Packages	npm-global (runs npm uninstall -g @jagilber-org/index-server), stale-local (removes $HOME/node_modules/@jagilber-org/index-server)

backups is treated separately from base so off-disk backups (recommended in the setup wizard) are not deleted when you wipe the base directory.

Clean uninstall (manual / fallback)

If index-server --setup fails with errors like env contains unsupported INDEX_SERVER key: … or Cannot find module …\node_modules\@jagilber-org\index-server\dist\server\index-server.js, you almost certainly have a stale non-global install shadowing the upgraded global one. The wizard above handles this with --remove npm-global,stale-local. To do it by hand:

# 1. Remove the global install
npm uninstall -g @jagilber-org/index-server

# 2. Clear the npm cache (forces a fresh download)
npm cache clean --force

# 3. Remove any stray non-global install in your home directory
#    (left behind by an earlier `npm install` without -g)
Remove-Item "$env:USERPROFILE\node_modules\@jagilber-org" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\index-server.ps1","$env:USERPROFILE\index-server.cmd","$env:USERPROFILE\index-server" -Force -ErrorAction SilentlyContinue

# 4. Reinstall fresh
npm install -g @jagilber-org/index-server@latest

# 5. Verify the resolution points at your npm global prefix
Get-Command index-server -All | Format-Table Source
node -e "console.log(require('@jagilber-org/index-server/package.json').version)"

On macOS / Linux replace step 3 with rm -rf ~/node_modules/@jagilber-org ~/.local/bin/index-server.

Why this happens: a previous npm install @jagilber-org/index-server (without -g) creates ~/node_modules/@jagilber-org/index-server. Node's CommonJS resolver walks parent directories from the cwd and finds that copy before the global prefix, so future global upgrades appear to "not take effect". npm uninstall -g does not touch the home-directory copy.

What's Next

• Use Case Scenarios — Real-world examples
• MCP Configuration — Advanced patterns (profiles, multi-instance)
• Tools Reference — Complete tool catalog
• Docker Deployment — Container deployment with TLS
• Dashboard Guide — Admin UI features

Teach Your Agents

Add this to your global copilot-instructions.md (or repo-level) so agents know about Index Server:

## Index Server

- Use index-server for validated cross-repo knowledge, not for reading current file contents.
- Start with `index_search` to find relevant instructions, then `index_dispatch get` for details.
- After learning something reusable, promote it with `index_add`.
- Prefer the local-first flow: repo files → .instructions/ → index-server → external docs.