semantic-code-mcp

Instructions

Implementation Reference

• src/semantic_code_mcp/server.py:159-193 (handler)

  The index_status tool handler function. Registered with @mcp.tool() decorator, it validates the project_path parameter, creates an IndexService, calls get_status() to retrieve the current index status, and returns an IndexStatusResponse with is_indexed, last_updated, files_count, and chunks_count fields.

  @mcp.tool()
  @profile_async("index_status")
  async def index_status(
      project_path: str,
      ctx: Context[ServerSession, None],
  ) -> IndexStatusResponse | ErrorResponse:
      """Get the index status for a project.
  
      Returns information about whether the project is indexed, when it was last
      updated, and how many files and chunks are indexed.
  
      Note: search_code automatically re-indexes stale files before searching,
      so there is no need to check or act on staleness manually.
  
      Args:
          project_path: Absolute path to the project root directory.
  
      Returns:
          Index status including files count and chunks count.
      """
      path = Path(project_path)
      if not path.exists():
          await ctx.warning(f"Project path does not exist: {project_path}")
          return ErrorResponse(error=f"Path does not exist: {project_path}")
  
      container = get_container()
      index_service = container.create_index_service(path)
      status = index_service.get_status(path)
  
      return IndexStatusResponse(
          is_indexed=status.is_indexed,
          last_updated=status.last_updated.isoformat() if status.last_updated else None,
          files_count=status.files_count,
          chunks_count=status.chunks_count,
      )

• src/semantic_code_mcp/server.py:159-160 (registration)

  Tool registration: The @mcp.tool() decorator registers the index_status function as an MCP tool with FastMCP. The profiling decorator @profile_async("index_status") tracks performance metrics.

  @mcp.tool()
  @profile_async("index_status")

• src/semantic_code_mcp/services/index_service.py:288-327 (handler)

  Core implementation logic in IndexService.get_status(). This method checks if the cache directory exists, scans project files, detects stale files, retrieves indexer stats, and returns an IndexStatus domain object with is_indexed, last_updated, files_count, chunks_count, and stale_files.

  def get_status(self, project_path: Path) -> IndexStatus:
      """Get the index status for a project.
  
      Args:
          project_path: Root directory of the project.
  
      Returns:
          IndexStatus with current state information.
      """
      project_path = project_path.resolve()
      cache_dir = resolve_cache_dir(self.settings, project_path, self._cache_dir)
  
      if not cache_dir.exists():
          return IndexStatus(
              is_indexed=False,
              last_updated=None,
              files_count=0,
              chunks_count=0,
              stale_files=[],
          )
  
      cache = FileChangeCache(cache_dir)
  
      current_files = self.scan_files(project_path)
      stale_files = cache.get_stale_files(current_files)
  
      indexed_files, chunks_count = self.indexer.get_store_stats()
  
      cache_file = cache_dir / CACHE_FILENAME
      last_updated = None
      if cache_file.exists():
          last_updated = datetime.fromtimestamp(cache_file.stat().st_mtime, tz=UTC)
  
      return IndexStatus(
          is_indexed=len(indexed_files) > 0,
          last_updated=last_updated,
          files_count=len(indexed_files),
          chunks_count=chunks_count,
          stale_files=stale_files,
      )

• src/semantic_code_mcp/models/responses.py:121-127 (schema)

  API response schema: IndexStatusResponse defines the structure of the tool's output returned to the MCP client, with fields for is_indexed, last_updated (as ISO string), files_count, and chunks_count.

  class IndexStatusResponse(BaseModel):
      """Response from index_status tool."""
  
      is_indexed: bool
      last_updated: str | None
      files_count: int
      chunks_count: int

• src/semantic_code_mcp/models/domain.py:63-70 (schema)

  Domain model schema: IndexStatus is the internal domain object used within the service layer to represent index status, containing is_indexed, last_updated (datetime), files_count, chunks_count, and stale_files (list of paths).

  class IndexStatus(BaseModel):
      """Status of the index for a codebase."""
  
      is_indexed: bool
      last_updated: datetime | None
      files_count: int
      chunks_count: int
      stale_files: list[str]