150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# 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 :
|
|
|
|
```bash
|
|
mcp-framework generate
|
|
```
|
|
|
|
La commande lit `./mcp.toml`, valide son contenu avec le package `manifest`, et
|
|
génère :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```go
|
|
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 :
|
|
|
|
```go
|
|
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 :
|
|
|
|
```go
|
|
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 :
|
|
|
|
```go
|
|
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 :
|
|
|
|
```go
|
|
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 :
|
|
|
|
```bash
|
|
mcp-framework generate --check
|
|
```
|
|
|
|
## Utilisation dans l'application
|
|
|
|
Importer le package généré depuis le module de l'application :
|
|
|
|
```go
|
|
import "example.com/my-mcp/mcpgen"
|
|
```
|
|
|
|
Charger le manifeste :
|
|
|
|
```go
|
|
file, source, err := mcpgen.LoadManifest(".")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
_ = file
|
|
_ = source
|
|
```
|
|
|
|
Construire les options d'update :
|
|
|
|
```go
|
|
opts, err := mcpgen.UpdateOptions(version, os.Stdout)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
```
|
|
|
|
Ouvrir le secret store configuré par le manifeste :
|
|
|
|
```go
|
|
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`.
|