mcp-framework/docs/generate.md

Génération depuis mcp.toml

La commande mcp-framework generate génère la glue Go dérivée du manifeste racine d'un projet existant.

Usage

Depuis la racine du projet Go :

mcp-framework generate

La commande lit ./mcp.toml, valide son contenu avec le package manifest, et génère :

mcpgen/
  manifest.go
  metadata.go
  update.go
  secretstore.go
  config.go        # si [[config.fields]] existe

Le package généré expose le loader de manifeste :

func LoadManifest(startDir string) (manifest.File, string, error)

Cette fonction appelle manifest.LoadDefaultOrEmbedded. En développement, un mcp.toml présent sur disque reste prioritaire. Pour un binaire copié seul, elle utilise le contenu du manifeste embarqué au moment de la génération.

Il expose aussi des helpers dérivés du manifeste :

const BinaryName = "my-mcp"
const DefaultDescription = "..."
const DocsURL = "..."

func BootstrapInfo(startDir string) (manifest.BootstrapMetadata, string, error)
func ScaffoldInfo(startDir string) (manifest.ScaffoldMetadata, string, error)

Pour l'auto-update :

func UpdateOptions(version string, stdout io.Writer) (update.Options, error)
func UpdateOptionsFrom(startDir string, version string, stdout io.Writer) (update.Options, error)
func RunUpdate(ctx context.Context, args []string, version string, stdout io.Writer) error
func RunUpdateFrom(ctx context.Context, args []string, startDir string, version string, stdout io.Writer) error

RunUpdate parse les flags de la commande update, refuse les arguments positionnels, charge le manifeste via LoadManifest, puis appelle update.Run.

Pour les secrets :

type SecretStoreOptions struct {
	ServiceName string
	LookupEnv   func(string) (string, bool)
}

func OpenSecretStore(options SecretStoreOptions) (secretstore.Store, error)
func DescribeSecretRuntime(options SecretStoreOptions) (secretstore.RuntimeDescription, error)
func PreflightSecretStore(options SecretStoreOptions) (secretstore.PreflightReport, error)

SecretStoreOptions contient aussi les options techniques du package secretstore (KWalletAppID, KWalletFolder, BitwardenCommand, BitwardenDebug, Shell, ExecutableResolver). Si ServiceName est vide, le nom du binaire déclaré dans le manifeste est utilisé.

Si le manifest déclare [[config.fields]], le package généré expose aussi :

type ConfigFlags struct { /* champs internes */ }

func AddConfigFlags(fs *flag.FlagSet) ConfigFlags
func ConfigFlagValues(flags ConfigFlags) map[string]string
func ResolveFieldSpecs(profile string) []cli.FieldSpec
func SetupFields(existing map[string]string) []cli.SetupField

AddConfigFlags branche les flags déclarés sur le FlagSet du projet. ConfigFlagValues retourne uniquement les valeurs de flags non vides. ResolveFieldSpecs génère les specs à passer à cli.ResolveFields, en remplaçant {profile} dans les templates de secrets. SetupFields génère les champs attendus par cli.RunSetup; le paramètre existing permet de fournir les secrets déjà stockés par nom de champ.

Flags

• --manifest : chemin du mcp.toml à lire. Par défaut, ./mcp.toml.
• --package-dir : répertoire du package généré. Par défaut, mcpgen.
• --package-name : nom du package Go généré. Par défaut, dérivé du dossier.
• --check : mode CI, échoue si les fichiers générés sont absents ou obsolètes.

Exemple CI :

mcp-framework generate --check

Utilisation dans l'application

Importer le package généré depuis le module de l'application :

import "example.com/my-mcp/mcpgen"

Charger le manifeste :

file, source, err := mcpgen.LoadManifest(".")
if err != nil {
	return err
}
_ = file
_ = source

Construire les options d'update :

opts, err := mcpgen.UpdateOptions(version, os.Stdout)
if err != nil {
	return err
}

Ouvrir le secret store configuré par le manifeste :

store, err := mcpgen.OpenSecretStore(mcpgen.SecretStoreOptions{
	LookupEnv: os.LookupEnv,
})
if err != nil {
	return err
}
_ = store

Après génération, un simple go build ./... suffit. La compilation ne dépend pas de la commande mcp-framework.