Search

Search of the indexed files of The Smarter Project’s repositories.

search_files() ranks the files of one or more repositories for a query, in the database, without embeddings:

  • The query is split into at most MAX_TERMS terms. A quoted phrase is one term, and so is an identifier such as smarter_settings.environment_platform_domain. Common English words are dropped.

  • A file is a candidate if its path or content contains any of the terms.

  • Each term is weighted by how rare it is among the files searched, its inverse document frequency, so that a rare identifier counts for more than a common word.

  • A file’s score adds up, for each term, a bonus for containing it, its number of occurrences, capped at MAX_COUNTED_OCCURRENCES so that long files do not win by length alone, and bonuses for matching the file’s path and title.

Occurrences are counted in SQL, as (LENGTH(LOWER(content)) - LENGTH(REPLACE(LOWER(content), term, ''))) / LENGTH(term), which every database that Django supports can evaluate. Only the best files are then read, to extract their matching lines.

Note

Experimental. The MCPServer was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.mcpserver.search.SearchHit(**data)[source]

Bases: BaseModel

A file that matches a search.

documentation_url: str | None
kind: RepositoryFileKind
lines: list[SearchLine]
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str
repository: str
score: float
title: str
url: str
class smarter.apps.mcpserver.search.SearchLine(**data)[source]

Bases: BaseModel

A line of a file, with its line number.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number: int
text: str
smarter.apps.mcpserver.search.query_terms(query)[source]

Split a search query into lowercase terms.

Parameters:

query (str) – The query, e.g. how does "custom domain" verification work.

Return type:

list[str]

Returns:

The terms, without duplicates or common words, e.g. ["custom domain", "verification", "work"].

smarter.apps.mcpserver.search.search_files(repositories, query, kind=None, path=None, limit=10)[source]

Search the indexed files of one or more repositories.

Parameters:

  • repositories (list[ProjectRepository]) – The repositories to search.

  • query (str) – The query.

  • kind (str | None) – Only documentation, or only code. Defaults to both.

  • path (str | None) – Only files under this folder, or with this path prefix, e.g. smarter/smarter/apps/llmclient.

  • limit (int) – The maximum number of hits.

Return type:

list[SearchHit]

Returns:

The best hits, best first. Empty if the query has no terms, or nothing matches.

Example usage:

hits = search_files([get_repository("smarter")], "custom domain verification", kind="documentation")
hits[0].documentation_url