home / skills / bobmatnyc / claude-mpm-skills / vector-search-workflows

vector-search-workflows skill

safe

/toolchains/ai/techniques/vector-search-workflows

This skill helps you index, search, and auto-index codebases with MCP Vector Search and ChromaDB, streamlining setup, reindexing, and MCP integration.

npx playbooks add skill bobmatnyc/claude-mpm-skills --skill vector-search-workflows

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.7 KB

---
name: vector-search-workflows
description: Vector search indexing and querying workflows using MCP Vector Search, including setup, reindexing, auto-index strategies, and MCP integration.
version: 1.0.0
category: toolchain
author: Claude MPM Team
license: MIT
progressive_disclosure:
  entry_point:
    summary: "Index a codebase with mcp-vector-search, keep it fresh with auto-indexing, and query via CLI or MCP integration."
    when_to_use: "Building semantic search for codebases, setting up MCP search tools, or troubleshooting indexing and reindexing workflows."
    quick_start: "1. mcp-vector-search setup 2. mcp-vector-search search \"query\" 3. mcp-vector-search index --force when schema changes"
tags:
  - vector-search
  - embeddings
  - indexing
  - search
  - mcp
---

# Vector Search Workflows (MCP Vector Search)

## Overview

Use `mcp-vector-search` to index codebases into ChromaDB and search via semantic embeddings. The recommended flow is `setup` (init + index + MCP integration), then `search`, and use `index` or `auto-index` to keep data fresh.

## Quick Start

```bash
pip install mcp-vector-search
mcp-vector-search setup
mcp-vector-search search "authentication logic"
```

`setup` detects languages, initializes config, indexes the repo, and configures MCP integrations (Claude Code, Cursor, etc.).

## Core Commands

### Indexing

```bash
mcp-vector-search index
mcp-vector-search index --force
mcp-vector-search index reindex --all --force
mcp-vector-search index reindex path/to/file.py
```

### Auto-Index Strategies

```bash
mcp-vector-search auto-index setup --method all
mcp-vector-search auto-index status
mcp-vector-search auto-index check --auto-reindex --max-files 10
mcp-vector-search auto-index teardown --method all
```

### Search

```bash
mcp-vector-search search "error handling patterns"
mcp-vector-search search "vector store initialization"
```

### Status + Doctor

```bash
mcp-vector-search status
mcp-vector-search doctor
```

## MCP Integration Pattern

`setup` uses native `claude mcp add` when available, otherwise falls back to `.mcp.json`.

Typical `.mcp.json` entry:

```json
{
  "mcpServers": {
    "mcp-vector-search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp-vector-search", "mcp"],
      "env": {
        "MCP_ENABLE_FILE_WATCHING": "true"
      }
    }
  }
}
```

## Reindex Triggers

- Dependency updates or parser changes
- Large refactors
- Adding new languages or file extensions
- Tool upgrades (version tracking triggers reindex)

## Local Patterns

- Use `uv` for dev installs: `uv sync --dev`
- Use `setup --force` to rebuild config + index after tool upgrades
- Keep file watching on via `MCP_ENABLE_FILE_WATCHING=true`

## Related Skills

- `toolchains/ai/protocols/mcp`
- `universal/main/mcp-builder`

Overview

This skill provides end-to-end workflows for indexing and querying codebases with MCP Vector Search. It guides setup, MCP integration, and strategies for maintaining fresh semantic indexes using ChromaDB and embeddings. The goal is reliable semantic search across repositories with automated reindexing options.

How this skill works

The skill initializes configuration, detects languages and file types, and builds an embedding-based index stored in ChromaDB. It supports one-off indexing, targeted reindexing, and an auto-index system that watches for changes and triggers reindexes. MCP integration is handled via native MCP commands when available or by adding a .mcp.json entry to enable the vector search service inside an MCP toolchain.

When to use it

Enable semantic search across a codebase for faster discovery of implementation patterns and examples.
After major refactors, dependency updates, or language additions that require a refreshed index.
When integrating vector search into an MCP-driven local developer workflow or toolchain.
To automate continuous indexing for active repositories where files change frequently.
During development when testing different index configurations or embedding models.

Best practices

Run setup once per repository to detect languages, initialize config, and create the initial index.
Use --force for index and setup commands after tool upgrades or breaking parser changes.
Enable file watching (MCP_ENABLE_FILE_WATCHING=true) for low-latency auto-indexing in active projects.
Limit auto-reindex checks with --max-files or scoped paths to avoid excessive processing on large repos.
Keep MCP integration consistent: prefer native claude mcp add when available, otherwise maintain a .mcp.json entry.

Example use cases

Search for authentication logic across multiple services to consolidate or refactor security code.
Reindex only modified files after a pull request to keep semantic search current without full rebuilds.
Set up auto-indexing in a CI environment to trigger reindexes when dependencies or parsers change.
Use status and doctor commands to validate index health and troubleshoot embedding or storage issues.
Add the vector-search MCP server to a local toolchain to share search capabilities across developer tools.

FAQ

How do I trigger a full reindex?

Run mcp-vector-search index reindex --all --force to rebuild the entire index from scratch.

What if my MCP runtime lacks native commands?

Use the .mcp.json entry pattern to register the vector-search service with type, command, args, and env settings.