semantic-code-mcp

Overview Schema Source Related Servers Discussions Admin

index_codebase

Index a codebase's Python, Rust, and Markdown chunks for search, with incremental or forced full re-indexing to support locating relevant code by text or meaning.

Instructions

Index a codebase's words for search.

Splits Python, Rust and Markdown files into functions, classes, methods, module docstrings and document sections, and stores them with their words; it embeds nothing, and a server set to search by meaning too embeds them on its next search. search_code indexes on its own; call this only to re-index everything.

With force: true, it re-indexes everything even if files haven't changed; a model whose weights nothing pins, as a local path, has its vectors dropped too, so a server set to search by meaning embeds every chunk again on its next search. Otherwise, only new and modified files are indexed (incremental).

Args: project_path: Absolute path to the project; a directory inside a git repository indexes the whole repository, unless the repository ignores it or holds the user's home directory. Left out, the client's workspace root, which must lie in a git repository. force: Re-index all files regardless of changes.

Returns: The root of the project indexed, and what the run indexed and deleted.

Input Schema

Name	Required	Description	Default
`force`	No
`project_path`	No	Absolute path to the project, or to a directory inside its git repository. Left out, the client's workspace root: the directory Claude Code was started in, which must lie in a git repository.

Output Schema

Name	Required	Description
`project_root`	Yes	The root of the project whose index this is: a directory inside a git repository is indexed, and reported, with its whole repository.
`files_deleted`	Yes
`files_indexed`	Yes
`chunks_indexed`	Yes
`duration_seconds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedv0.5.0Nov 4, 2026

addedInput schema / properties / project_path / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / project_path / default
```
Added value: +null
```

addedInput schema / properties / project_path / description

Added value: +"Absolute path to the project, or to a directory inside its git repository. Left out, the client's workspace root: the directory Claude Code was started in, which must lie in a git repository."

removedInput schema / properties / project_path / type
```
Removed value: -"string"
```
removedInput schema / required
```
Removed value: -[
-  "project_path"
-]
```

removedOutput schema / $defs

Removed value: -{
-  "ErrorResponse": {
-    "description": "Error response for tool failures.",
-    "properties": {
-      "error": {
-        "title": "Error",
-        "type": "string"
-      }
-    },
-    "required": [
-      "error"
-    ],
-    "title": "ErrorResponse",
-    "type": "object"
-  },
-  "IndexCodebaseResponse": {
-    "description": "Response from index_codebase tool.",
-    "properties": {
-      "chunks_indexed": {
-        "title": "Chunks Indexed",
-        "type": "integer"
-      },
-      "duration_seconds": {
-        "title": "Duration Seconds",
-        "type": "number"
-      },
-      "files_deleted": {
-        "title": "Files Deleted",
-        "type": "integer"
-      },
-      "files_indexed": {
-        "title": "Files Indexed",
-        "type": "integer"
-      }
-    },
-    "required": [
-      "files_indexed",
-      "chunks_indexed",
-      "files_deleted",
-      "duration_seconds"
-    ],
-    "title": "IndexCodebaseResponse",
-    "type": "object"
-  }
-}

addedOutput schema / description

Added value: +"The answer of `index_codebase`."

addedOutput schema / properties / chunks_indexed

Added value: +{
+  "title": "Chunks Indexed",
+  "type": "integer"
+}

addedOutput schema / properties / duration_seconds

Added value: +{
+  "title": "Duration Seconds",
+  "type": "number"
+}

addedOutput schema / properties / files_deleted

Added value: +{
+  "title": "Files Deleted",
+  "type": "integer"
+}

addedOutput schema / properties / files_indexed

Added value: +{
+  "title": "Files Indexed",
+  "type": "integer"
+}

addedOutput schema / properties / project_root

Added value: +{
+  "description": "The root of the project whose index this is: a directory inside a git repository is indexed, and reported, with its whole repository.",
+  "title": "Project Root",
+  "type": "string"
+}

removedOutput schema / properties / result

Removed value: -{
-  "anyOf": [
-    {
-      "$ref": "#/$defs/IndexCodebaseResponse"
-    },
-    {
-      "$ref": "#/$defs/ErrorResponse"
-    }
-  ],
-  "title": "Result"
-}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "project_root",
+  "files_indexed",
+  "chunks_indexed",
+  "files_deleted",
+  "duration_seconds"
+]

changedOutput schema / title

Previous value: -"index_codebaseOutput"New value: +"IndexCodebaseResponse"

First observedv0.1.0Feb 21, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: it discloses that no embeddings are computed here, that a meaning-search server embeds chunks lazily on its next search, and that force drops existing vectors for unpinned models. It stops short of cost, duration, or concurrency behavior for large repositories, so it is rich but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is front-loaded and organized with Args/Returns sections, but the embedding behavior is explained twice in near-duplicate sentences, and phrasing like "a model whose weights nothing pins, as a local path" is convoluted enough to slow parsing. It is informative but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and the description still summarizes the return value (indexed root, what was indexed and deleted), and it handles the tricky path-resolution edge cases an agent would otherwise get wrong. Only operational scale questions (time, resource use on large repos) are left open.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50% (force has no schema description), and the Args section compensates fully for force and adds real meaning beyond the schema for project_path: a directory inside a git repo indexes the whole repository, with exceptions for ignored paths and the user's home directory. That repository-expansion rule is not inferable from the schema at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Index a codebase's words for search") and immediately scopes what is parsed (Python, Rust, Markdown into functions, classes, docstrings, sections) and what is not done ("it embeds nothing"). It also explicitly separates itself from the sibling search_code, so an agent can choose between them without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not: "`search_code` indexes on its own; call this only to re-index everything." The force parameter section then defines the second usage mode (full re-index vs. incremental), so both branches of when-to-call are covered with the named alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server