Reading Tools

The public tools that read the index: get_repository_overview, read_file, list_files and read_blog_post.

Each tool validates its arguments, calls smarter.apps.mcpserver.services.reading, and formats what it returns as Markdown. They are served at the MCPServer’s public endpoint (smarter.apps.mcpserver.protocol.public). read_blog_post 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.

A file, folder or post that does not exist is a tool error that suggests what the LLM may have meant, or else which tool finds it.

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.reading.GetRepositoryOverviewTool(scope, github_token=None)[source]

Bases: PublicTool

The get_repository_overview tool: what a repository contains, how it is laid out, and its README.

Without a repository, it lists every repository of the endpoint, with whether each is indexed.

all_repositories()[source]

Return a table of every repository of the scope, with whether each one is indexed.

Side effects: see repositories_state().

Return type:

str

Returns:

The table, as Markdown, and where the documentation and the blog are.

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

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'get_repository_overview'

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

run(arguments)[source]

Describe the named repository, with repository_overview(), or list them all if none is named.

Side effects: database queries, and, for a repository that is not indexed yet, a Celery task queued to index it.

Parameters:

arguments (PublicToolArguments) – The validated arguments.

Return type:

str

Returns:

The overview, as Markdown.

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

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

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

Bases: PublicTool

The list_files tool: the folders and indexed files directly in a folder of a repository.

Only indexed files are listed, so a folder of only binaries or vendored files does not appear.

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

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'list_files'

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

requires_repository: ClassVar[bool] = True

Whether a call to the public endpoint of every repository must name one.

run(arguments)[source]

List the folder that the arguments name, or the top-level folder, with list_files().

Side effects: database queries, and, for a repository that is not indexed yet, a Celery task queued to index it.

Parameters:

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

Return type:

str

Returns:

The folder’s name, its GitHub url, and its entries, as Markdown.

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

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

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

Bases: PublicTool

The read_blog_post tool: a post of the blog, or a range of its lines, as text with line numbers.

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

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'read_blog_post'

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]

Read the lines of the post that the arguments name, by its path or its url, with read_blog_post().

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 ReadBlogPostArguments.

Return type:

str

Returns:

The post’s url, and its lines in a code block, as Markdown.

Raises:
title: ClassVar[str] = 'Read blog post'

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.reading.ReadFileTool(scope, github_token=None)[source]

Bases: PublicTool

The read_file tool: a file of a repository, or a range of its lines, with line numbers.

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

What the tool does, and when to call it.

The LLM reads it to decide which tool to call.

name: ClassVar[str] = 'read_file'

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

requires_repository: ClassVar[bool] = True

Whether a call to the public endpoint of every repository must name one.

run(arguments)[source]

Read the lines of the file that the arguments name, with read_file().

The result starts with the file’s GitHub url at the indexed commit, and its published documentation page, if it is one.

Side effects: database queries, and, for a repository that is not indexed yet, a Celery task queued to index it.

Parameters:

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

Return type:

str

Returns:

The lines, in a code block, as Markdown.

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

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