Documentation
¶
Overview ¶
Package mcpsurface introspects the registered MCP surface for the generator commands.
Several commands under cmd/ need the same thing: the tools, prompts and resources the server actually registers, read over a real MCP round-trip rather than described by hand, and against a surface that does not depend on the ambient environment. The server chooses its catalog from TOOL_SURFACE and its client from GITLAB_URL/GITLAB_TOKEN, so a generator that read either would emit different files on a developer machine than in CI. Every constructor here pins the surface explicitly and talks to an in-process stub instead, which is what makes the committed artifacts reproducible.
Index ¶
- Constants
- func DynamicCatalog(client *gitlabclient.Client, enterprise bool) (*actioncatalog.Catalog, error)
- func DynamicTools(client *gitlabclient.Client) ([]*mcp.Tool, error)
- func NewGitLabComClient() (*gitlabclient.Client, error)
- func NewStubClient() (*gitlabclient.Client, func(), error)
- func ProjectRoot() (string, error)
- func Prompts(client *gitlabclient.Client) ([]*mcp.Prompt, error)
- func Resources(client *gitlabclient.Client) ([]*mcp.Resource, []*mcp.ResourceTemplate, error)
- func Session(setup func(*mcp.Server) error) (session *mcp.ClientSession, cleanup func(), err error)
- func SortDynamicTools(dynamicTools []*mcp.Tool)
- func ValidateDynamicToolContract(dynamicTools []*mcp.Tool) error
Constants ¶
const ( DynamicFindToolName = "gitlab_find_action" DynamicExecuteActionToolName = "gitlab_execute_action" )
The dynamic surface is the default a user gets with no configuration, and it is a fixed two-tool contract. Generators name the pair so a rename shows up as a failed generation rather than as silently different output.
const StubToken = "gen-surface-token" //#nosec G101 -- not a real credential, in-process stub only
StubToken is the dummy credential the generators authenticate their stub client with. It is never sent to a real GitLab instance: NewStubClient points the client at an in-process HTTP server. A generator must not fall back to GITLAB_TOKEN, or a machine that exports one would produce different output from a machine that does not.
Variables ¶
This section is empty.
Functions ¶
func DynamicCatalog ¶
func DynamicCatalog(client *gitlabclient.Client, enterprise bool) (*actioncatalog.Catalog, error)
DynamicCatalog builds the canonical action catalog behind the dynamic find/execute surface, including the standalone actions that are not part of any domain meta-tool. enterprise selects the Premium/Ultimate catalog.
func DynamicTools ¶
func DynamicTools(client *gitlabclient.Client) ([]*mcp.Tool, error)
DynamicTools returns the visible two-tool dynamic catalog from a real MCP tools/list session, in find-then-execute order.
func NewGitLabComClient ¶
func NewGitLabComClient() (*gitlabclient.Client, error)
NewGitLabComClient returns a client pinned to the public GitLab.com URL. The catalog registers the GitLab.com-only tools (Orbit) against it, so generated documentation can describe the full capability set rather than whatever the ambient GITLAB_URL points at.
func NewStubClient ¶
func NewStubClient() (*gitlabclient.Client, func(), error)
NewStubClient returns a GitLab client backed by an in-process stub that answers every request with a fixed version payload, plus the cleanup func that shuts the stub down. Catalog construction needs a client but performs no real request, so this keeps generation offline and identical on every machine.
func ProjectRoot ¶
ProjectRoot walks up from the working directory to the directory holding go.mod, so a generator works from anywhere in the repository.
func Prompts ¶
func Prompts(client *gitlabclient.Client) ([]*mcp.Prompt, error)
Prompts returns every registered MCP prompt definition over a real prompts/list round-trip.
func Resources ¶
func Resources(client *gitlabclient.Client) ([]*mcp.Resource, []*mcp.ResourceTemplate, error)
Resources returns the static resources and resource templates advertised by the MCP server, including the surface-aware tool manifest template. The manifest is rendered for the dynamic surface because that is what a user gets by default.
func Session ¶
Session creates an in-memory MCP server+client pair, applies setup to the server, and returns the connected client session together with a cleanup function the caller must invoke.
func SortDynamicTools ¶
SortDynamicTools orders the dynamic surface find-then-execute, which is the order a model should use them in, and sorts anything unexpected by name so the output stays deterministic.
func ValidateDynamicToolContract ¶
ValidateDynamicToolContract fails when the dynamic surface is no longer exactly find plus execute, so a rename or an extra tool aborts generation instead of quietly rewriting every generated artifact.
Types ¶
This section is empty.
Source Files