GitHub Tools

The tools that search, open and comment on the GitHub issues of The Smarter Project.

search_issues: the GitHub issues of the repositories, live. Anyone may call it.
read_issue: one issue and its latest comments, live. Anyone may call it.
create_issue: opens a GitHub issue in a repository, as the caller, optionally with labels.
comment_on_issue: adds a comment to an existing issue, as the caller.
close_issue: closes an issue that a merged pull request resolved, with a comment, as the caller.
create_pull_request: commits a change to a new branch, and opens a pull request, as the caller.

create_issue, comment_on_issue, close_issue and create_pull_request are served only when the request carries the caller’s GitHub classic personal access token, and their results are never cached. See smarter.apps.mcpserver.github.issues and smarter.apps.mcpserver.github.pulls.

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.github.tools.CloseIssueTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Close an issue that a merged pull request resolved, as the caller.

arguments_model: alias of CloseIssueArguments

description: ClassVar[str] = "Close an open GitHub issue of a repository of The Smarter Project, under the user's own GitHub account, when a merged pull request resolved it. It adds the comment, which says why, and closes the issue as completed, only if GitHub confirms that the pull request was merged. Read the issue and the pull request with read_issue first, and close the issue only if the pull request fixes exactly what the issue reports. It is public, and the issue's participants are notified: call it only when the user asks you to."

name: ClassVar[str] = 'close_issue'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

read_only: ClassVar[bool] = False

Whether the tool only reads.

A tool that writes is annotated so, and its results are never cached.

requires_github_token: ClassVar[bool] = True: Whether the tool is served only to a request that carries the caller’s GitHub token.

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] = 'Close GitHub issue'

class smarter.apps.mcpserver.github.tools.CommentOnIssueTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Add a comment to a GitHub issue, as the caller.

arguments_model: alias of CommentOnIssueArguments

description: ClassVar[str] = "Add a comment to an existing GitHub issue of a repository of The Smarter Project, under the user's own GitHub account, e.g. to confirm a bug that search_issues found, rather than open it again. Read the issue with read_issue first, and comment only to add what it does not already say. It is public, and the issue's participants are notified: call it only when the user asks you to, after showing them the issue and the comment, and never more than once for the same comment."

name: ClassVar[str] = 'comment_on_issue'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

read_only: ClassVar[bool] = False

Whether the tool only reads.

A tool that writes is annotated so, and its results are never cached.

requires_github_token: ClassVar[bool] = True: Whether the tool is served only to a request that carries the caller’s GitHub token.

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] = 'Comment on GitHub issue'

class smarter.apps.mcpserver.github.tools.CreateIssueTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Open a GitHub issue in a repository, as the caller.

arguments_model: alias of CreateIssueArguments

description: ClassVar[str] = "Open a GitHub issue in a repository of The Smarter Project, under the user's own GitHub account, to report a bug or request a feature. It creates a public issue that maintainers are notified of: call it only when the user asks you to, after showing them the repository, title and body, and never more than once for the same issue. Search the code and documentation first, so that the issue is specific, choose the repository that owns the problem, and call search_issues first: if the issue already exists, use comment_on_issue instead."

name: ClassVar[str] = 'create_issue'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

read_only: ClassVar[bool] = False

Whether the tool only reads.

A tool that writes is annotated so, and its results are never cached.

requires_github_token: ClassVar[bool] = True: Whether the tool is served only to a request that carries the caller’s GitHub token.

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] = 'Create GitHub issue'

class smarter.apps.mcpserver.github.tools.CreatePullRequestTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Commit a change to a new branch, and open a pull request, as the caller.

arguments_model: alias of CreatePullRequestArguments

description: ClassVar[str] = "Propose a change to a repository of The Smarter Project, under the user's own GitHub account: one commit, with each changed file's whole new content, on a new branch from base, and a pull request from it. It never changes an existing branch, nor files under .github/. It is public, and maintainers are notified: call it only when the user asks you to, after showing them the files, title and description, and never twice for the same change. Read every file that you change with read_file first, from the base branch, and keep the change as small as the fix."

name: ClassVar[str] = 'create_pull_request'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

read_only: ClassVar[bool] = False

Whether the tool only reads.

A tool that writes is annotated so, and its results are never cached.

requires_github_token: ClassVar[bool] = True: Whether the tool is served only to a request that carries the caller’s GitHub token.

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] = 'Create GitHub pull request'

class smarter.apps.mcpserver.github.tools.ReadIssueTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Read a GitHub issue and its latest comments, live.

arguments_model: alias of ReadIssueArguments

cache_ttl: ClassVar[int | None] = 60: Seconds that a read-only tool’s result is cached, or None for TOOL_RESULT_CACHE_TTL.

description: ClassVar[str] = 'Read one GitHub issue of a repository of The Smarter Project: its state, labels and body, and its latest comments, oldest first. Call it before comment_on_issue, so that a comment adds what the issue does not already say, and to see whether a closed issue was fixed or declined.'

static format_comment(comment)[source]

Return one comment, as Markdown.

Return type:: str

classmethod format_thread(repository, thread)[source]

Return the issue and its comments, as Markdown, within MAX_READ_CHARACTERS.

When the result is too long, the issue’s body is shortened first, and then the oldest comments are left out, because the latest say what is known now.

Return type:: str

name: ClassVar[str] = 'read_issue'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

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 GitHub issue'

class smarter.apps.mcpserver.github.tools.SearchIssuesTool(scope, github_token=None)[source]

Bases: SmarterProjectTool

Search the repositories’ GitHub issues, live.

arguments_model: alias of SearchIssuesArguments

cache_ttl: ClassVar[int | None] = 60: Seconds that a read-only tool’s result is cached, or None for TOOL_RESULT_CACHE_TTL.

description: ClassVar[str] = "Search the GitHub issues of The Smarter Project's repositories: known bugs, feature requests, and whether they are fixed. Returns the best matches, with their state, number of comments, and url. Use it when a user reports a problem, and always before create_issue, so that an issue is not opened twice: comment on an existing one instead."

static format_hit(number, hit)[source]

Return one issue, as Markdown.

Return type:: str

name: ClassVar[str] = 'search_issues'

open_world: ClassVar[bool] = True: Whether the tool reaches beyond the index, e.g. to GitHub, rather than the platform’s own data.

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 GitHub issues'