Index Tools

The tools that answer from the index of the repositories and the blog.

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.
search_blog: ranked passages of the posts of the blog, blog.smarter.sh.
read_blog_post: a post of the blog, with line numbers.

The blog’s tools have no repository argument, and only the MCP server of all of the repositories serves them. A tool that is called on a repository that is not indexed yet says so, and queues the repository for indexing.

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.index.tools.GetRepositoryOverviewTool(scope, github_token=None)[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.index.tools.ListFilesTool(scope, github_token=None)[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.index.tools.ReadBlogPostTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Read a post of the blog.

arguments_model: alias of ReadBlogPostArguments

description: ClassVar[str] = "Read a post of The Smarter Project's blog, blog.smarter.sh, as text with line numbers, from the paths or urls that search_blog returns. Long posts are read 400 lines at a time: use start_line and end_line to read more."

name: ClassVar[str] = 'read_blog_post'

project_wide: ClassVar[bool] = True: Whether only the MCP server of all of the repositories serves the tool.

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 blog post'

uses_repository: ClassVar[bool] = False: Whether the tool takes a repository argument on the MCP server of all of the repositories.

class smarter.apps.mcpserver.index.tools.ReadFileTool(scope, github_token=None)[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.index.tools.SearchBlogTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Search the blog’s posts.

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

static format_hit(number, hit)[source]

Return one hit, as Markdown.

Return type:: str

name: ClassVar[str] = 'search_blog'

project_wide: ClassVar[bool] = True: Whether only the MCP server of all of the repositories serves the tool.

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

uses_repository: ClassVar[bool] = False: Whether the tool takes a repository argument on the MCP server of all of the repositories.

class smarter.apps.mcpserver.index.tools.SearchCodeTool(scope, github_token=None)[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.index.tools.SearchDocumentationTool(scope, github_token=None)[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'

smarter.apps.mcpserver.index.tools.queue_indexing_key(name)[source]

Return the cache key that remembers that a repository was queued for indexing.

Return type:: str