# How semantic_search_nodes_tool Works: Semantic Code Search in code-review-graph

> Discover how semantic_search_nodes_tool enables meaning-based code search. Understand vector embeddings and cosine similarity for efficient code-review-graph navigation.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: deep-dive
- Published: 2026-08-08

---

**semantic_search_nodes_tool is an MCP tool that performs meaning-based search across code graph nodes by comparing natural language queries against vector embeddings using cosine similarity.**

The `semantic_search_nodes_tool` is a core component of the `tirth8205/code-review-graph` project, an MCP (Model Context Protocol) implementation that builds a searchable graph representation of your codebase. This tool enables developers to locate specific functions, classes, and files using natural language descriptions rather than exact identifier matches, bridging the gap between human intent and code structure.

## What Is semantic_search_nodes_tool?

At its core, `semantic_search_nodes_tool` is a specialized utility defined in [`src/mcp/tools/semanticSearchNodesTool.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/tools/semanticSearchNodesTool.ts) that exposes semantic search capabilities to MCP clients. Unlike traditional text search that matches substrings or regular expressions, this tool understands the semantic meaning of your query by leveraging vector embeddings generated from the source code, documentation, and metadata of each node in the graph.

## How semantic_search_nodes_tool Works Internally

The tool operates through a multi-stage pipeline that transforms raw source code into searchable vector representations.

### Node Indexing and Corpus Generation

When the code graph is built, the indexer traverses the repository and generates a textual corpus for every node. According to the implementation in [`src/mcp/indexer.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/indexer.ts) and [`src/mcp/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/graph.ts), this corpus includes:

- The node's fully qualified identifier (e.g., `src/utils/math.ts::add`)
- The complete source code or a distilled summary
- JSDoc, TypeDoc, or other documentation comments
- Associated tags such as "utility" or "test"

### Embedding Generation

The textual corpus for each node is sent to an embedding model via [`src/mcp/embeddingsProvider.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/embeddingsProvider.ts). By default, the tool uses the OpenAI `text-embedding-3-small` model to generate high-dimensional vectors that capture semantic meaning. These embeddings are stored in the graph's SQLite backing store for fast retrieval.

### Query Processing and Similarity Search

When you invoke `semanticSearchNodesTool(query)`, the tool converts your natural language query into an embedding using the same model. It then performs a nearest-neighbor search using **cosine similarity** against all stored node embeddings. The implementation filters results based on a configurable similarity threshold and sorts them by descending relevance score.

### Result Shaping and Caching

Each matching node is wrapped in a `NodeSearchResult` object defined in [`src/mcp/types.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/types.ts), containing the node's ID, a code snippet or docstring, and the similarity score. The tool maintains an intelligent caching layer that preserves embeddings for unchanged nodes, automatically refreshing vectors only when the underlying source code is modified.

## Source Code Architecture

The semantic search functionality is distributed across several key files in the `tirth8205/code-review-graph` repository:

- **[`src/mcp/tools/semanticSearchNodesTool.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/tools/semanticSearchNodesTool.ts)** – Contains the core implementation of the semantic search algorithm, including embedding lookup, similarity computation, and caching logic.

- **[`src/mcp/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/graph.ts)** – Defines the `Node` objects, indexing logic, and SQLite storage handling for persisting vector embeddings.

- **[`src/mcp/indexer.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/indexer.ts)** – Traverses the codebase to extract documentation and comments, building the textual corpus used for embedding generation.

- **[`src/mcp/embeddingsProvider.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/embeddingsProvider.ts)** – Provides the wrapper around the OpenAI embedding API used by the tool to generate vectors.

- **[`src/mcp/types.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/types.ts)** – Contains TypeScript definitions for `NodeSearchResult` and related interfaces returned by the search tool.

## Usage Examples

The following examples demonstrate how to import and use the tool in TypeScript applications:

```typescript
// Import the tool from the MCP entry point
import { semanticSearchNodesTool } from '@code-review-graph/mcp';

// Basic semantic search for JWT validation logic
const results = await semanticSearchNodesTool('function that validates JWT tokens');

// Display the top 3 matches with similarity scores
results.slice(0, 3).forEach(r => {
  console.log(`🔎 ${r.nodeId} (score=${r.score.toFixed(2)})`);
  console.log(r.snippet);
  console.log('---');
});

```

```typescript
// Advanced configuration with result limiting and threshold tuning
const results = await semanticSearchNodesTool('read the configuration file', {
  maxResults: 5,
  minScore: 0.45,          // Only return hits with similarity >= 0.45
});

if (results.length === 0) {
  console.log('⚠️ No relevant nodes found.');
}

```

```typescript
// Integration example within a VS Code extension
import { queryGraphTool } from '@code-review-graph/mcp';
import { semanticSearchNodesTool } from '@code-review-graph/mcp';

export async function onSearchCommand(query: string) {
  const matches = await semanticSearchNodesTool(query, { maxResults: 10 });
  
  // Convert matches into VS Code locations for UI display
  const locations = matches.map(m => ({
    uri: queryGraphTool('uri_of_node', m.nodeId),
    range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
    tooltip: `Score ${m.score.toFixed(2)}`,
  }));
  
  // Display locations in the quick-pick UI...
}

```

## Summary

- **semantic_search_nodes_tool** is an MCP tool that enables natural language search over code graphs by comparing vector embeddings using cosine similarity.
- The tool processes queries through [`src/mcp/tools/semanticSearchNodesTool.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/tools/semanticSearchNodesTool.ts), utilizing OpenAI's `text-embedding-3-small` model by default via [`src/mcp/embeddingsProvider.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/embeddingsProvider.ts).
- Node embeddings are generated from combined source code, documentation, and metadata during the indexing phase handled by [`src/mcp/indexer.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/indexer.ts).
- Results are returned as `NodeSearchResult` objects containing node IDs, code snippets, and similarity scores, with intelligent caching to avoid recomputing unchanged nodes.
- Configuration options include `maxResults` to limit output and `minScore` to filter by relevance threshold.

## Frequently Asked Questions

### How does semantic_search_nodes_tool differ from traditional text search?

Traditional text search relies on substring matching or regular expressions against identifiers and file contents, requiring you to know exact function names or patterns. In contrast, `semantic_search_nodes_tool` uses vector embeddings to understand the conceptual meaning of your query, allowing you to find relevant code using descriptions like "function that refreshes user tokens" even when the actual function is named `renewAuthSession`.

### What embedding model does semantic_search_nodes_tool use?

According to the source code in [`src/mcp/embeddingsProvider.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/embeddingsProvider.ts), the tool defaults to the OpenAI `text-embedding-3-small` model for generating high-dimensional vectors. This model balances performance and accuracy for code search tasks, though the architecture supports swapping providers through the embeddings provider interface.

### Can I configure the similarity threshold for search results?

Yes, the tool accepts a `minScore` parameter in its options object that sets the minimum cosine similarity threshold for returned results. Values range from 0 to 1, where higher values require stricter semantic matches. You can also use `maxResults` to limit the number of matches returned regardless of their scores.

### Where are the vector embeddings stored?

The embeddings are persisted in a SQLite database managed by the graph layer defined in [`src/mcp/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/graph.ts). This backing store enables fast nearest-neighbor searches without re-embedding the entire codebase on every query, and the caching mechanism in [`src/mcp/tools/semanticSearchNodesTool.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/mcp/tools/semanticSearchNodesTool.ts) ensures only modified nodes get re-indexed.