Search Tools

The public tools that search the index: search_documentation, search_code and search_blog.

Each tool validates its arguments, calls smarter.apps.mcpserver.services.search, and formats the hits as Markdown, with links that the LLM can cite. They are served at the MCPServer’s public endpoint (smarter.apps.mcpserver.protocol.public). search_blog has no repository argument, and only the endpoint of every repository serves it. Every tool is read-only, so call() caches its results until an index changes.

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.protocol.tools.search.SearchArguments(**data)[source]

Bases: PublicToolArguments

The arguments of search_documentation and search_blog, and the base of those of search_code.

limit: int
model_config = {'extra': 'forbid'}

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

query: str
class smarter.apps.mcpserver.protocol.tools.search.SearchBlogTool(scope, github_token=None)[source]

Bases: PublicTool

The search_blog tool: ranked passages of the blog’s posts, with links to them.

arguments_model

alias of SearchArguments

description: ClassVar[str] = "Search the posts of The Smarter Project's blog, blog.smarter.sh: release announcements, with what changed in each version and how to upgrade, and articles about how and why Smarter was built, e.g. its security, logging, testing, caching and use of AI coding agents. Returns the best passages, with links to the posts. Use it, together with search_documentation, for why and how questions, design decisions, what changed in a release, and the project's history."

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

static format_hit(number, hit)[source]

Return one hit, as Markdown: a numbered heading, the post’s url, and its passage in a code block.

Parameters:

  • number (int) – The hit’s rank, from 1.

  • hit (SearchHit) – The hit.

Return type:

str

Returns:

The Markdown.

name: ClassVar[str] = 'search_blog'

The tool’s name, which the LLM calls it by, e.g. search_code.

project_wide: ClassVar[bool] = True

Whether only the public endpoint of every repository serves the tool.

run(arguments)[source]

Search the blog’s posts, with search_blog().

Side effects: database queries, and, if the blog is not indexed yet, a Celery task queued to index it.

Parameters:

arguments (PublicToolArguments) – The validated arguments, a SearchArguments.

Return type:

str

Returns:

The hits, best first, as Markdown, or a message that nothing matches.

Raises:

SmarterMCPServerServiceError – If the blog is not indexed yet.

title: ClassVar[str] = 'Search blog'

The tool’s human-readable name, which an MCP client may show.

uses_repository: ClassVar[bool] = False

Whether the tool takes a repository argument on the public endpoint of every repository.

class smarter.apps.mcpserver.protocol.tools.search.SearchCodeArguments(**data)[source]

Bases: SearchArguments

The arguments of search_code: those of search_documentation, and a folder to search under.

model_config = {'extra': 'forbid'}

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

path: str | None
class smarter.apps.mcpserver.protocol.tools.search.SearchCodeTool(scope, github_token=None)[source]

Bases: SearchTool

The search_code tool: ranked files of the repositories’ source code, with their matching lines.

arguments_model

alias of SearchCodeArguments

description: ClassVar[str] = 'Search the source code and configuration of The Smarter Project: Python, TypeScript, Go, YAML manifests, Helm charts, Terraform and more. Returns the best files, with their matching lines and GitHub links. Use it for how something is implemented, and to find a class, function, setting or manifest field by name.'

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'search_code'

The tool’s name, which the LLM calls it by, e.g. search_code.

noun = 'code'

What the tool’s results call the files, e.g. documentation or code.

search(arguments, repositories)[source]

Search the code, under the folder that the arguments name, if any, with search_code().

Parameters:
Return type:

SearchResults

Returns:

The hits, and the repositories that were not searched.

title: ClassVar[str] = 'Search code'

The tool’s human-readable name, which an MCP client may show.

class smarter.apps.mcpserver.protocol.tools.search.SearchDocumentationTool(scope, github_token=None)[source]

Bases: SearchTool

The search_documentation tool: ranked passages of the repositories’ documentation.

arguments_model

alias of SearchArguments

description: ClassVar[str] = 'Search the documentation of The Smarter Project: the Sphinx documentation published at docs.smarter.sh, READMEs, and other reStructuredText and Markdown files. Returns the best passages, with links to the published page and to the source. Use it for concepts, features, configuration, installation and how-to questions.'

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'search_documentation'

The tool’s name, which the LLM calls it by, e.g. search_code.

noun = 'documentation'

What the tool’s results call the files, e.g. documentation or code.

search(arguments, repositories)[source]

Search the documentation, with search_documentation().

Parameters:
Return type:

SearchResults

Returns:

The hits, and the repositories that were not searched.

title: ClassVar[str] = 'Search documentation'

The tool’s human-readable name, which an MCP client may show.

class smarter.apps.mcpserver.protocol.tools.search.SearchTool(scope, github_token=None)[source]

Bases: PublicTool

The base class of the search tools of the repositories, search_documentation and search_code.

A subclass sets the noun that its results call the files, and implements search().

format_hit(number, hit)[source]

Return one hit, as Markdown: a numbered heading, its links, and its lines in a code block.

Parameters:

  • number (int) – The hit’s rank, from 1.

  • hit (SearchHit) – The hit.

Return type:

str

Returns:

The Markdown. The heading names the repository on the endpoint of every repository.

noun = ''

What the tool’s results call the files, e.g. documentation or code.

run(arguments)[source]

Search the named repository, or every repository of the scope, and return the hits as Markdown.

A repository that is not indexed yet is queued for indexing, and named in a note after the results.

Side effects: see search_repositories().

Parameters:

arguments (PublicToolArguments) – The validated arguments.

Return type:

str

Returns:

The hits, best first, as Markdown, or a message that nothing matches.

Raises:
abstractmethod search(arguments, repositories)[source]

Search the repositories.

Parameters:
Return type:

SearchResults

Returns:

The hits, and the repositories that were not searched.