Repositories

The Smarter Project’s GitHub repositories, and its blog, which the MCPServer’s public endpoint reads.

Each ProjectRepository is one public repository of the smarter-sh GitHub organization. The MCP server serves each repository at its own endpoint, /api/v1/mcp/smarter-project/<name>/, and all of them together at /api/v1/mcp/smarter-project/. The repositories are a fixed part of the platform, declared here rather than in a manifest, because the MCP server is an internal utility of the platform, not a resource that accounts create.

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.services.repositories.ProjectBlog(**data)[source]

Bases: BaseModel

The Smarter Project’s blog, a WordPress site, whose posts the MCP server reads.

It has the same name, title, description, file_url() and documentation_url() as a ProjectRepository, so that the search tools can treat the blog as one more source (see ProjectSource). The model is frozen: the blog is declared once, in SMARTER_PROJECT_BLOG.

Its posts are indexed like a repository’s documentation, by smarter.apps.mcpserver.services.indexing.blog.index_blog(), under the blog’s name. A post’s path is its permalink’s path, e.g. 2026/10/26/release-smarter-api-v0-6.

Example usage:

blog = project_blog()
blog.post_url("2026/10/26/release-smarter-api-v0-6")
# 'https://blog.smarter.sh/2026/10/26/release-smarter-api-v0-6/'

description: str: What the blog contains, and what questions it answers, which the MCP server shows the LLM.

documentation_url(path)[source]

Return the url of a post, which is its published page.

The signature is that of ProjectRepository.documentation_url(). Every post is a published page, so the url is never None.

Parameters:: path (str) – The post’s path, e.g. 2026/10/26/release-smarter-api-v0-6.
Return type:: str | None
Returns:: The post’s url.

file_url(commit_sha, path, start_line=None, end_line=None)[source]

Return the url of a post, for smarter.apps.mcpserver.services.search.search_files().

The signature is that of ProjectRepository.file_url(). A post has no commit, and its page has no line anchors, so only path is used.

Parameters:

commit_sha (str | None) – Ignored.
path (str) – The post’s path, e.g. 2026/10/26/release-smarter-api-v0-6.
start_line (int | None) – Ignored.
end_line (int | None) – Ignored.

Return type:

str

Returns:

The post’s url.

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

name: str

The name of the blog’s index, e.g. blog.smarter.sh.

It is the repository of the blog’s RepositoryIndex, and is never the name of a repository.

post_path(url_or_path)[source]

Return the path of a post, from its url or its path.

The blog’s url, over https or http, is removed, and so are a fragment (#...), a query (?...) and the slashes at either end. An LLM may give either form, so the tools accept both.

Parameters:: url_or_path (str) – e.g. https://blog.smarter.sh/2026/10/26/release-smarter-api-v0-6/.
Return type:: str
Returns:: The path, e.g. 2026/10/26/release-smarter-api-v0-6.

post_url(path)[source]

Return the url of a post.

Parameters:: path (str) – The post’s path, e.g. 2026/10/26/release-smarter-api-v0-6.
Return type:: str
Returns:: The post’s url.

property posts_api_url: str

The url of the WordPress REST api’s posts, e.g. https://blog.smarter.sh/wp-json/wp/v2/posts.

The blog’s indexer pages through it to read every published post.

title: str: What the blog contains, in a few words, e.g. the Smarter blog.

url: str: The blog’s url, without a trailing slash, e.g. https://blog.smarter.sh.

class smarter.apps.mcpserver.services.repositories.ProjectRepository(**data)[source]

Bases: BaseModel

A public GitHub repository of The Smarter Project.

It says where the repository is, which branch is indexed, and, for a repository with Sphinx documentation, where its pages are published. Its methods build the links that the MCP server’s tools give the LLM: to a file on GitHub, to a range of its lines, and to the published page that a documentation source file becomes. The model is frozen: the repositories are declared once, in SMARTER_PROJECT_REPOSITORIES.

Example usage:

repository = get_repository("smarter-cli")
repository.github_url  # 'https://github.com/smarter-sh/smarter-cli'
repository.file_url("0123abc", "README.md", 1, 20)

archive_url(commit_sha)[source]

Return the url of the repository’s gzipped tar archive at a commit.

Parameters:: commit_sha (str) – The commit.
Return type:: str
Returns:: The url, e.g. https://codeload.github.com/smarter-sh/smarter-cli/tar.gz/0123abc.

property commit_api_url: str

The GitHub api url of the latest commit of ref.

The indexer requests it to find out whether the branch has moved since it was indexed.

description: str

What the repository contains, and what questions it answers.

The MCP server shows it to the LLM, so that it can choose which repository to search.

docs_root: str | None: The folder of the Sphinx documentation’s source files, e.g. docs/source, or None if it has none.

docs_url: str | None

The url of the published Sphinx documentation that is built from docs_root, with a trailing slash.

It is None if the repository has no published documentation.

documentation_url(path)[source]

Return the url of the published documentation page that a source file becomes.

Parameters:: path (str) – The file’s path in the repository, e.g. docs/source/smarter-resources/smarter-mcpclient.rst.
Return type:: str | None
Returns:: The page’s url, e.g. https://docs.smarter.sh/smarter-resources/smarter-mcpclient.html, or None if the file is not a page of the repository’s published documentation.

file_url(commit_sha, path, start_line=None, end_line=None)[source]

Return the GitHub url of a file, optionally of a range of its lines.

Parameters:

commit_sha (str | None) – The commit, for a permanent link. Defaults to ref.
path (str) – The file’s path in the repository.
start_line (int | None) – The first line to highlight.
end_line (int | None) – The last line to highlight. Ignored unless it is after start_line.

Return type:

str

Returns:

The url, e.g. https://github.com/smarter-sh/smarter-cli/blob/0123abc/README.md#L1-L20.

property full_name: str: The repository’s GitHub name, e.g. smarter-sh/smarter-cli.

property github_url: str: The repository’s GitHub url, e.g. https://github.com/smarter-sh/smarter-cli.

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

name: str

The repository’s name in its organization, e.g. smarter-cli.

It is also the last part of its MCP endpoint, /api/v1/mcp/smarter-project/<name>/, and the repository of its RepositoryIndex.

owner: str: The GitHub organization that owns the repository, SMARTER_PROJECT_GITHUB_ORGANIZATION by default.

ref: str: The branch that is indexed, main by default, and that links without a commit point to.

title: str: What the repository contains, in a few words, e.g. the Smarter command-line interface.

smarter.apps.mcpserver.services.repositories.ProjectSource = smarter.apps.mcpserver.services.repositories.ProjectRepository | smarter.apps.mcpserver.services.repositories.ProjectBlog

a repository, or the blog.

Type:: A source of the MCP server’s index

smarter.apps.mcpserver.services.repositories.SMARTER_PROJECT_BLOG = ProjectBlog(name='blog.smarter.sh', title='the Smarter blog', description='The Smarter blog, https://blog.smarter.sh: release announcements of the platform, the cli, the SDKs and the other packages, with what changed and how to upgrade, and articles about how and why Smarter was built.', url='https://blog.smarter.sh'): The blog that the MCP server reads.

smarter.apps.mcpserver.services.repositories.SMARTER_PROJECT_REPOSITORIES: tuple[ProjectRepository, ...] = (ProjectRepository(name='smarter', title='the Smarter platform, and its documentation', description='The Smarter platform: its Django backend, SAM manifests and resources (LLMClients, Plugins, MCPClients, Guardrails, Secrets, ...), its api, its React web console and its npm packages (SmarterChat, the React chat component of LLMClients, as @smarter.sh/ui-chat, and @smarter.sh/ui-widgets), its Helm chart, and the source of its documentation, https://docs.smarter.sh, in docs/source.', owner='smarter-sh', ref='main', docs_root='docs/source', docs_url='https://docs.smarter.sh/'), ProjectRepository(name='smarter-cli', title='the Smarter command-line interface', description='The smarter command-line interface, written in Go, which applies, gets, describes and deletes manifests.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-python', title='the Smarter Python SDK', description="The official Python library for the Smarter platform's api, published to PyPI as smarter-api.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-nodejs', title='the Smarter Node.js SDK', description="The official Node.js library for the Smarter platform's api, written in TypeScript, published to npm as @smarter.sh/api.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-golang', title='the Smarter Go SDK', description="The official Go library for the Smarter platform's api, the module github.com/smarter-sh/smarter-golang.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-vscode-yaml', title='the VS Code extension for Smarter manifests', description='The VS Code extension that validates and completes Smarter yaml manifests.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-infrastructure', title='the Smarter cloud infrastructure', description='The Terraform and Kubernetes code of the cloud infrastructure that the Smarter platform runs on.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-deploy', title='the Smarter platform quick start, with Docker', description='The quick start that runs the Smarter platform on a computer with Docker Compose.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='example-manifests', title='the example manifests that every platform applies', description='Working example manifests of every Smarter resource kind, ready to apply, read and copy: LLMClients, Plugins, MCPClients, Guardrails, Proxies, LLMHosts, Vectorstores, Budgets and more. Every Smarter platform applies them when it is initialized.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='stackademy', title='Stackademy, the example project', description="Stackademy, an AI course advisor for a fictional online code academy, built with Smarter's no-code tool calling over a private database, and managed with git and GitHub: the example project of the documentation.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-wordpress', title='Smarter Chat for WordPress', description='The WordPress plugin that adds a Smarter chatbot to a site: a chat launcher, a block and a shortcode.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-drupal', title='Smarter Chat for Drupal', description='The Drupal module that adds a Smarter chatbot to a site: a chat launcher, and a block for any region.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-shopify', title='Smarter Chat for Shopify', description='The Shopify theme app extension that adds a Smarter chatbot to a store: a chat launcher, and an app block.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-gtm-template', title='Smarter Chat for Google Tag Manager', description='The Google Tag Manager tag template that adds a Smarter chatbot to any site with a GTM web container.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-docs-site-generators', title='Smarter Chat for documentation sites', description='The packages that add a Smarter chatbot to every page of a Docusaurus, MkDocs, Sphinx or VitePress site.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='extensions-registry', title='the Smarter Extension registry', description="The registry of Smarter Extensions, the installable Python packages that add tools to a platform's LLMs: their publishers, releases and signed index, and how to publish a release.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-extension-calculator', title='the Calculator extension', description='The official Smarter Extension whose calculator tool evaluates math expressions exactly.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-extension-date-calculator', title='the Date Calculator extension', description='The official Smarter Extension whose date_calculator tool does date arithmetic exactly.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='smarter-extension-weather', title='the Weather extension', description='The official Smarter Extension whose get_weather tool gives the current weather and a forecast.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None), ProjectRepository(name='cache-results', title='cache-results, the Django caching decorator', description="cache-results, on PyPI: the @cache_results() Django decorator that caches a function's results by its arguments, and lazy_cache. Smarter caches with it.", owner='smarter-sh', ref='main', docs_root='docs/source', docs_url='https://docs.cache-results.smarter.sh/'), ProjectRepository(name='smarter-types', title='the shared Smarter type definitions', description='smarter-types, on PyPI: the plain-Python type definitions that the platform and the Python SDK share.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None))

Every repository that the MCP server reads.

(
    ProjectRepository(name='smarter', title='the Smarter platform, and its documentation', description='The Smarter platform: its Django backend, SAM manifests and resources (LLMClients, Plugins, MCPClients, Guardrails, Secrets, ...), its api, its React web console and its npm packages (SmarterChat, the React chat component of LLMClients, as @smarter.sh/ui-chat, and @smarter.sh/ui-widgets), its Helm chart, and the source of its documentation, https://docs.smarter.sh, in docs/source.', owner='smarter-sh', ref='main', docs_root='docs/source', docs_url='https://docs.smarter.sh/'),
    ProjectRepository(name='smarter-cli', title='the Smarter command-line interface', description='The smarter command-line interface, written in Go, which applies, gets, describes and deletes manifests.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-python', title='the Smarter Python SDK', description="The official Python library for the Smarter platform's api, published to PyPI as smarter-api.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-nodejs', title='the Smarter Node.js SDK', description="The official Node.js library for the Smarter platform's api, written in TypeScript, published to npm as @smarter.sh/api.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-golang', title='the Smarter Go SDK', description="The official Go library for the Smarter platform's api, the module github.com/smarter-sh/smarter-golang.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-vscode-yaml', title='the VS Code extension for Smarter manifests', description='The VS Code extension that validates and completes Smarter yaml manifests.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-infrastructure', title='the Smarter cloud infrastructure', description='The Terraform and Kubernetes code of the cloud infrastructure that the Smarter platform runs on.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-deploy', title='the Smarter platform quick start, with Docker', description='The quick start that runs the Smarter platform on a computer with Docker Compose.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='example-manifests', title='the example manifests that every platform applies', description='Working example manifests of every Smarter resource kind, ready to apply, read and copy: LLMClients, Plugins, MCPClients, Guardrails, Proxies, LLMHosts, Vectorstores, Budgets and more. Every Smarter platform applies them when it is initialized.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='stackademy', title='Stackademy, the example project', description="Stackademy, an AI course advisor for a fictional online code academy, built with Smarter's no-code tool calling over a private database, and managed with git and GitHub: the example project of the documentation.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-wordpress', title='Smarter Chat for WordPress', description='The WordPress plugin that adds a Smarter chatbot to a site: a chat launcher, a block and a shortcode.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-drupal', title='Smarter Chat for Drupal', description='The Drupal module that adds a Smarter chatbot to a site: a chat launcher, and a block for any region.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-shopify', title='Smarter Chat for Shopify', description='The Shopify theme app extension that adds a Smarter chatbot to a store: a chat launcher, and an app block.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-gtm-template', title='Smarter Chat for Google Tag Manager', description='The Google Tag Manager tag template that adds a Smarter chatbot to any site with a GTM web container.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-docs-site-generators', title='Smarter Chat for documentation sites', description='The packages that add a Smarter chatbot to every page of a Docusaurus, MkDocs, Sphinx or VitePress site.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='extensions-registry', title='the Smarter Extension registry', description="The registry of Smarter Extensions, the installable Python packages that add tools to a platform's LLMs: their publishers, releases and signed index, and how to publish a release.", owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-extension-calculator', title='the Calculator extension', description='The official Smarter Extension whose calculator tool evaluates math expressions exactly.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-extension-date-calculator', title='the Date Calculator extension', description='The official Smarter Extension whose date_calculator tool does date arithmetic exactly.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='smarter-extension-weather', title='the Weather extension', description='The official Smarter Extension whose get_weather tool gives the current weather and a forecast.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
    ProjectRepository(name='cache-results', title='cache-results, the Django caching decorator', description="cache-results, on PyPI: the @cache_results() Django decorator that caches a function's results by its arguments, and lazy_cache. Smarter caches with it.", owner='smarter-sh', ref='main', docs_root='docs/source', docs_url='https://docs.cache-results.smarter.sh/'),
    ProjectRepository(name='smarter-types', title='the shared Smarter type definitions', description='smarter-types, on PyPI: the plain-Python type definitions that the platform and the Python SDK share.', owner='smarter-sh', ref='main', docs_root=None, docs_url=None),
)

smarter.apps.mcpserver.services.repositories.get_repository(name)[source]

Return one of SMARTER_PROJECT_REPOSITORIES, by name.

Parameters:: name (str) – The repository’s name, e.g. smarter-cli.
Return type:: ProjectRepository | None
Returns:: The repository, or None if there is no such repository.

smarter.apps.mcpserver.services.repositories.project_blog()[source]

Return SMARTER_PROJECT_BLOG.

Every module reads the blog through this function, so that tests can replace it with a throwaway blog, whose index does not collide with the real one.

Return type:: ProjectBlog
Returns:: The blog.

smarter.apps.mcpserver.services.repositories.project_repositories()[source]

Return SMARTER_PROJECT_REPOSITORIES.

Every module reads the repositories through this function, so that tests can replace them with throwaway repositories, whose indexes do not collide with the real ones.

Return type:: tuple[ProjectRepository, ...]
Returns:: The repositories, in the order that the MCP server lists them.

smarter.apps.mcpserver.services.repositories.repository_names()[source]

Return the names of SMARTER_PROJECT_REPOSITORIES.

The indexing task and the index_smarter_project command use them to index every repository.

Return type:: list[str]
Returns:: The names, e.g. ["smarter", "smarter-cli", ...], in the order that they are declared.