Version 1

Auto-generated from config struct types and tags.

Config

Config is the root of .mcpsmithy.yaml. It has four top-level sections: project identifies the codebase and declares content sources; conventions map file-path patterns to docs and rules; tools define what the AI can call at runtime.

Field	Type	Required	Default	Description
`version`	string	yes	—	Config schema version. Must be "1".
`project`	Project	yes	—	Project identity, description, and content sources.
`conventions`	map[string]Convention	yes	—	Rules and docs the AI should follow, keyed by name.
`tools`	map[string]Tool	yes	—	Tools the AI can call, keyed by tool name (the name the AI sees).

Project

Project tells the AI what this codebase is. Name and description appear in tool responses (e.g. project_info). Sources declare where code, docs, and other content live — the AI uses them for search and orientation.

Field	Type	Required	Default	Description
`name`	string	yes	—	Human-readable project name shown in tool responses.
`description`	string	yes	—	Brief summary of what this project does. Shown alongside the name.
`sources`	ProjectSources	no	—	Content sources that tell the AI where things live. Sources with index: true (default) are searchable via search_for; sources with index: false describe project structure without being searchable.

Convention

Convention maps a file-path pattern to documentation and rules. When the AI calls conventions_for with a file path, matching conventions return their description, linked docs, tags, and relations — giving the AI the context it needs before generating or reviewing code.

The map key is the convention's unique name, used in relations and tool responses.

Field	Type	Required	Default	Description
`scope`	string	no	—	Glob pattern that matches file paths this convention applies to. When the AI calls conventions_for with a file path, only conventions whose scope matches are returned. Supported patterns: * — matches any path (use as a global/catch-all convention) — matches any number of path segments within a larger pattern src/ — all files under src/ .go — Go files in the root only **/.go — all Go files at any depth Omit scope entirely to make a convention search-only: it will never be matched by file path but remains findable via search_for.
`docs`	DocRef[]	no	—	Documentation the AI should read when this convention is matched. Each entry references a declared source by name, optionally narrowed to specific paths.
`description`	string	yes	—	Inline summary returned to the AI alongside matched docs. Also used as the search corpus when the AI searches conventions by keyword.
`tags`	string[]	no	—	Keywords that improve search relevance when the AI searches for conventions.
`relations`	ConventionRelations[]	no	—	Links to related conventions, so the AI discovers that changing one area may require reading or following rules from another.

Tool

Tool defines an operation the AI can invoke. Each tool has a template that produces text output, optional input parameters the AI fills in per call, and optional static options the config author controls. The map key becomes the tool name the AI sees in tool listings.

Field	Type	Required	Default	Description
`description`	string	yes	—	Description the AI sees when listing available tools. Write what the tool does and when to call it, not just what it returns.
`template`	TemplateString	yes	—	Template body producing the tool's output.
`params`	ToolParam[]	no	—	Input parameters the LLM varies per call — queries, file paths, search terms.
`options`	map[string]any	no	—	Static key-value pairs set by the config author, invisible to the LLM. Injected into the template context alongside params at runtime. Use options for values fixed per tool: token budgets, result limits, base URLs, feature flags. For example, wire maxResults from options (e.g. `{{ search_for .query .maxResults }}`) so the config author controls the budget, not the LLM. Reserved option: urlAllowList ([]string) — when set, http_get, http_post, and http_put reject any URL whose scheme://host is not in the list.
`log_params`	boolean	no	—	When false params are not logged at DEBUG level. Default (nil/unset) logs params.
`maxOutputKB`	integer	no	1024	Maximum output size for this tool in KB. Defaults to 1024 (1 MB). (min: 1)

ProjectSources

ProjectSources groups content the AI can search or reference. Each source type (local, scrape, git, http) is a named map — the names are used in convention docs entries to link conventions to specific content.

Sources serve two purposes:

Structure — sources with index: false describe where things live.
Search — sources with index: true (default) are indexed for full-text search.

Field	Type	Required	Default	Description
`pullPolicy`	PullPolicy	no	ifNotPresent	Global pull policy for all sources. Per-source values override this.
`syncInterval`	integer	no	0	Background sync interval in minutes. When > 0, the server starts immediately after indexing local sources; remote sources load in the background. Re-fetch runs every N minutes. (min: 0)
`local`	map[string]LocalSource	no	—	Files on disk, keyed by name. Reference these names in convention docs.
`scrape`	map[string]ScrapeSource	no	—	Web pages to fetch and optionally follow links from, keyed by name.
`git`	map[string]GitSource	no	—	Git repositories to clone, keyed by name.
`http`	map[string]HTTPSource	no	—	HTTP endpoints to fetch (archives, APIs, artifact stores), keyed by name.

DocRef

DocRef links a convention to content from a declared source. The source field must match a key under project.sources (local, scrape, git, or http). Paths optionally narrow to specific files within that source.

Field	Type	Required	Default	Exclusivity	Description
`source`	string	yes	—		Source name — must match a key in project.sources (local, scrape, git, or http). (must reference a declared key in: project.sources.local, project.sources.scrape, project.sources.git, project.sources.http)
`paths`	string[]	no	—		Optional paths within the source to specific files.

ConventionRelations

ConventionRelations links two conventions so the AI discovers that working in one area may require awareness of another. For example, an API convention might relate to a testing convention because every endpoint needs integration tests.

Field	Type	Required	Default	Exclusivity	Description
`target`	string	yes	—		Convention name (must match a conventions map key). (must reference a declared key in: conventions)
`description`	string	no	—		How this convention relates to the target.

ToolParam

ToolParam declares an input the AI provides when calling a tool. Params appear in the tool's input schema — the AI sees names, types, and descriptions before deciding what values to pass.

Field	Type	Required	Default	Description
`name`	string	yes	—	Parameter name. (must not be a reserved engine name)
`type`	ParamType	yes	—	Parameter type.
`required`	boolean	no	false	Whether the parameter is mandatory.
`description`	string	no	—	Shown to the AI. Use it to explain the expected format or how to transform what the user provides into what the template expects.
`default`	any	no	—	Default value when not supplied. The YAML type must match the param type (e.g. integer for int, boolean for bool).
`constraints`	ParamConstraints	no	—	Constraints on the parameter value (enum or min/max).

LocalSource

LocalSource points to files on disk relative to the project root. Commonly used for source code, docs, configs, and test files. Indexed for search by default; set index: false to expose them as structure without indexing.

Field	Type	Required	Default	Description
`paths`	string[]	yes	—	Glob patterns relative to project root.
`description`	string	no	—	Explains what these files are. Shown to the AI in project overviews.
`index`	boolean	no	true	When true (default), content is searchable via search_for. Set to false for sources that describe structure only.
`pullPolicy`	PullPolicy	no	—	Per-source pull policy override (falls back to global when unset).

ScrapeSource

ScrapeSource fetches web pages by URL. Useful for external API docs, wikis, or any HTML content. Set maxDepth > 0 to follow links from seed URLs and build a wider search corpus.

Field	Type	Required	Default	Description
`urls`	string[]	yes	—	HTTP(S) URLs to fetch.
`description`	string	no	—	Explains what these pages are. Shown to the AI in project overviews.
`index`	boolean	no	true	When true (default), content is searchable via search_for. Set to false for sources that describe structure only.
`maxDepth`	integer	no	0	Max link-following depth from seed URLs. (min: 0)
`maxPageSize`	integer	no	2048	Max KB per page. (min: 0)
`maxPages`	integer	no	20	Max URLs to fetch (seeds + discovered pages combined). (min: 0)
`pullPolicy`	PullPolicy	no	—	Per-source pull policy override (falls back to global when unset).

GitSource

GitSource specifies a git repository to clone and optionally index. Requires the git binary on PATH. Credentials come from the environment (SSH keys, git credential helpers, .netrc).

For HTTP archive downloads without the git binary, use an HTTPSource with the forge's archive URL instead.

Field	Type	Required	Default	Description
`repo`	string	yes	—	Git repository URL (HTTPS or SSH).
`ref`	string	no	—	Branch or tag to fetch.
`paths`	string[]	yes	—	Glob patterns within the repo.
`description`	string	no	—	Explains what this repo provides. Shown to the AI in project overviews.
`depth`	integer	no	1	Git clone depth. Use 1 (default) for content only; increase if history is needed. (min: 1)
`index`	boolean	no	true	When true (default), content is searchable via search_for. Set to false for sources that describe structure only.
`pullPolicy`	PullPolicy	no	—	Per-source pull policy override (falls back to global when unset).

HTTPSource

HTTPSource fetches content from a URL and optionally extracts tar.gz archives. Works with any authenticated HTTP(S) endpoint: forge archive URLs, private APIs, artifact stores, etc.

Authentication is automatic via .netrc; custom headers can be added for bearer tokens or API keys.

Field	Type	Required	Default	Description
`url`	string	yes	—	HTTP(S) URL to fetch.
`headers`	map[string]string	no	—	Custom HTTP headers (e.g. Authorization). Applied alongside .netrc credentials; explicit headers take precedence.
`paths`	string[]	yes	—	Glob patterns within the fetched content. For archives these match extracted files; for single files they match the saved filename.
`description`	string	no	—	Explains what this endpoint provides. Shown to the AI in project overviews.
`extract`	boolean	no	—	Extract tar.gz archives. Auto-detected from Content-Type or URL suffix (.tar.gz/.tgz) when unset.
`index`	boolean	no	true	When true (default), content is searchable via search_for. Set to false for sources that describe structure only.
`pullPolicy`	PullPolicy	no	—	Per-source pull policy override (falls back to global when unset).

ParamConstraints

ParamConstraints limits what the AI can supply for a parameter. Use enum for a fixed set of valid values, or min/max for numeric bounds. Constraints are enforced server-side and surfaced in the tool's input schema so the AI knows the valid range upfront.

Field	Type	Required	Default	Exclusivity	Description
`enum`	any[]	no	—	mutually exclusive with `min`; mutually exclusive with `max`	Fixed set of valid values. Compatible with string, integer, and number param types.
`min`	number	no	—	mutually exclusive with `enum`	Minimum value (inclusive). Applies to integer and number param types only.
`max`	number	no	—	mutually exclusive with `enum`	Maximum value (inclusive). Applies to integer and number param types only.

Enum Reference

PullPolicy

PullPolicy controls when remote sources are fetched.

Value	Description
`always`	Fetch sources on every server start.
`ifNotPresent`	Fetch only when the local cache is missing.
`never`	Never fetch — only use sources already on disk.

ParamType

ParamType names the valid parameter types for tool definitions. Use one of these as the type: value in a tool parameter.

The classification methods (IsNumeric, IsStringLike, IsBoolean) and Compatible implement TypeClassifier, enabling the schema engine to validate typed-as constraints without per-version logic.

Value	Description
`string`	JSON Schema string.
`number`	JSON Schema number (float64).
`bool`	JSON Schema boolean.
`array`	JSON Schema array.
`project_file_path`	String validated as a file path inside the project sandbox.

BuiltinFunc

BuiltinFunc names a template function available inside tool templates. These are the only functions callable from template bodies — they cover convention lookup, content search, file reading, HTTP fetching, and text filtering.

Value	Description
`conventions_for`	func(path string) string — Returns conventions matching a file path, including description and linked docs.
`file_read`	func(path string, [maxFileSize int]) string — Reads local files matching a glob pattern within the project sandbox.
`grep`	func(pattern string, before float64, after float64, input string) string — Filters input by regex pattern with context lines.
`http_get`	func(url string, [maxReadKB int]) (string, error) — HTTP GET with .netrc auth and ANSI stripping. Caps the response body at maxReadKB KB (default 10240). Set the urlAllowList option to restrict which hosts can be reached.
`http_post`	func(url string, body string, [contentType string], [maxReadKB int]) (string, error) — HTTP POST with .netrc auth. Sends body with the given content type (default "application/json"), accepts any 2xx response, caps the response body at maxReadKB KB (default 10240). Set the urlAllowList option to restrict which hosts can be reached.
`http_put`	func(url string, body string, [contentType string], [maxReadKB int]) (string, error) — HTTP PUT with .netrc auth. Sends body with the given content type (default "application/json"), accepts any 2xx response, caps the response body at maxReadKB KB (default 10240). Set the urlAllowList option to restrict which hosts can be reached.
`search_for`	func(query string, [maxResults int], [maxResultSize int]) string — Full-text search over indexed sources.

Type Reference

TemplateString

TemplateString is the template body for a tool. It uses Go text/template syntax with access to the project context via {{ .mcpsmithy }}, declared params and options as {{ .paramName }}, and built-in functions like conventions_for, search_for, file_read, http_get, and grep.

Config​

Project​

Convention​

Tool​

ProjectSources​

DocRef​

ConventionRelations​

ToolParam​

LocalSource​

ScrapeSource​

GitSource​

HTTPSource​

ParamConstraints​

PullPolicy​

ParamType​

BuiltinFunc​

TemplateString​