Tools

The tools of the Smarter Project MCP server.

Each tool is a SmarterProjectTool: a name, a description, a Pydantic model of its arguments, from which its MCP inputSchema is generated, and SmarterProjectTool.run(), which returns its result as Markdown text for the LLM. Every tool is read-only.

get_repository_overview: what a repository contains, its layout, and its README.
search_documentation: ranked passages of the documentation.
search_code: ranked files of source code, with their matching lines.
read_file: a file, or a range of its lines, with line numbers.
list_files: the folders and files under a folder.

A tool works on the repositories of its SmarterProjectScope. The MCP server of one repository serves the tools without a repository argument, and the MCP server of all of the repositories adds one, whose values are the repositories’ names.

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.tools.GetRepositoryOverviewTool(scope)[source]

Bases: SmarterProjectTool

What a repository contains, how it is laid out, and its README.

all_repositories()[source]

Return a table of every repository of the scope.

Return type:: str

description: ClassVar[str] = 'Describe a repository of The Smarter Project: what it contains, its GitHub url, its indexed commit, its top-level folders and files, and its README. Use it for questions about a repository as a whole, not to answer a specific question, which the search tools answer directly.'

name: ClassVar[str] = 'get_repository_overview'

run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str] = 'Repository overview'

class smarter.apps.mcpserver.tools.ListFilesTool(scope)[source]

Bases: SmarterProjectTool

List a folder.

arguments_model: alias of ListFilesArguments

description: ClassVar[str] = "List the folders and indexed files in a folder of a repository of The Smarter Project, with the number of files in each folder. Use it to explore a repository's layout."

entries(index, folder)[source]

Return the folders and files directly in a folder, as Markdown list items.

Parameters:

index (RepositoryIndex) – The repository’s index.
folder (str) – The folder, or an empty string for the top level.

Return type:

list[str]

Returns:

The folders, then the files, each sorted by name.

name: ClassVar[str] = 'list_files'

requires_repository: ClassVar[bool] = True: Whether a call to the MCP server of all of the repositories must name one.

run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str] = 'List files'

class smarter.apps.mcpserver.tools.ReadFileTool(scope)[source]

Bases: SmarterProjectTool

Read a file.

arguments_model: alias of ReadFileArguments

description: ClassVar[str] = 'Read a file of a repository of The Smarter Project, with line numbers, from the paths that the search tools and list_files return. Long files are read 400 lines at a time: use start_line and end_line to read more.'

name: ClassVar[str] = 'read_file'

not_found(index, repository, path)[source]

Return an error message that suggests the files that the LLM may have meant.

Return type:: str

requires_repository: ClassVar[bool] = True: Whether a call to the MCP server of all of the repositories must name one.

run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str] = 'Read file'

class smarter.apps.mcpserver.tools.SearchCodeTool(scope)[source]

Bases: SearchTool

Search the source code.

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.'

kind: ClassVar[str] = 'code'

name: ClassVar[str] = 'search_code'

noun: ClassVar[str] = 'code'

run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str] = 'Search code'

class smarter.apps.mcpserver.tools.SearchDocumentationTool(scope)[source]

Bases: SearchTool

Search the 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.'

kind: ClassVar[str] = 'documentation'

name: ClassVar[str] = 'search_documentation'

noun: ClassVar[str] = 'documentation'

run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str] = 'Search documentation'

class smarter.apps.mcpserver.tools.SmarterProjectScope(**data)[source]

Bases: BaseModel

The repositories that one Smarter Project MCP server serves.

Parameters:: repository – The one repository of the server, or None for all of them.

property is_single: bool: Whether the server serves one repository.

model_config = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property names: list[str]: The names of the repositories.

repositories: tuple[ProjectRepository, ...]

repository: ProjectRepository | None

resolve(name, required)[source]

Return the repository that a tool call names.

Parameters:

name (str | None) – The tool call’s repository argument.
required (bool) – Whether the tool needs one repository.

Return type:

ProjectRepository | None

Returns:

The server’s one repository, the named repository, or None for all of them.

Raises:

SmarterMCPServerToolError – If the name is not one of the scope’s repositories, or a required name is missing.

class smarter.apps.mcpserver.tools.SmarterProjectTool(scope)[source]

Bases: ABC

A tool of the Smarter Project MCP server.

Parameters:: scope (SmarterProjectScope) – The repositories of the MCP server.

__init__(scope)[source]

arguments_model: alias of ToolArguments

call(arguments)[source]

Validate a tool call’s arguments, and run the tool.

Parameters:: arguments (dict[str, Any] | None) – The tool call’s arguments.
Return type:: str
Returns:: The result, as Markdown.
Raises:: SmarterMCPServerToolError – If the arguments are not valid, or the tool fails.

definition()[source]

Return the tool, as tools/list lists it.

Return type:: Tool

description: ClassVar[str]

input_schema()[source]

Return the tool’s MCP inputSchema.

Return type:: dict[str, Any]
Returns:: A JSON schema of type object. The MCP server of one repository omits repository, and that of all of them lists the repositories’ names.

name: ClassVar[str]

requires_repository: ClassVar[bool] = False: Whether a call to the MCP server of all of the repositories must name one.

abstractmethod run(arguments)[source]

Run the tool.

Parameters:: arguments (ToolArguments) – The validated arguments, an instance of arguments_model.
Return type:: str
Returns:: The result, as Markdown.

title: ClassVar[str]

smarter.apps.mcpserver.tools.TOOL_CLASSES: tuple[type[SmarterProjectTool], ...] = (<class 'smarter.apps.mcpserver.tools.GetRepositoryOverviewTool'>, <class 'smarter.apps.mcpserver.tools.SearchDocumentationTool'>, <class 'smarter.apps.mcpserver.tools.SearchCodeTool'>, <class 'smarter.apps.mcpserver.tools.ReadFileTool'>, <class 'smarter.apps.mcpserver.tools.ListFilesTool'>)

Every tool of the Smarter Project MCP server, in the order that tools/list lists them.

(
    <class 'smarter.apps.mcpserver.tools.GetRepositoryOverviewTool'>,
    <class 'smarter.apps.mcpserver.tools.SearchDocumentationTool'>,
    <class 'smarter.apps.mcpserver.tools.SearchCodeTool'>,
    <class 'smarter.apps.mcpserver.tools.ReadFileTool'>,
    <class 'smarter.apps.mcpserver.tools.ListFilesTool'>,
)