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 consommateur :

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

Migration d'un wrapper manuel

Pour remplacer un wrapper local du type internal/manifest :

1. Déplacer le manifeste projet vers mcp.toml à la racine.
2. Lancer mcp-framework generate.
3. Remplacer les imports du wrapper local par le package généré, par exemple example.com/my-mcp/mcpgen.
4. Remplacer les appels manifest.Load(...) du wrapper par mcpgen.LoadManifest(...).
5. Remplacer les reconstructions locales d'options update par mcpgen.UpdateOptions(...) ou mcpgen.RunUpdate(...).
6. Remplacer les wrappers secret store qui ne font que brancher le loader par mcpgen.OpenSecretStore, mcpgen.DescribeSecretRuntime et mcpgen.PreflightSecretStore.
7. Supprimer l'ancien wrapper manuel.

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