|
| 1 | +package cmd |
| 2 | + |
| 3 | +import ( |
| 4 | + "context" |
| 5 | + "os" |
| 6 | + "strconv" |
| 7 | + |
| 8 | + "github.com/spf13/cobra" |
| 9 | + |
| 10 | + outpostmcp "github.com/hookdeck/hookdeck-cli/pkg/outpost/mcp" |
| 11 | + "github.com/hookdeck/hookdeck-cli/pkg/validators" |
| 12 | +) |
| 13 | + |
| 14 | +// allowWriteEnvVar enables write actions without a flag, for MCP clients whose |
| 15 | +// config makes environment variables easier to set than arguments. |
| 16 | +const allowWriteEnvVar = "HOOKDECK_MCP_ALLOW_WRITE" |
| 17 | + |
| 18 | +// publishAPIKeyEnvVar carries the Project API key the publish tool needs. |
| 19 | +// |
| 20 | +// It is deliberately distinct from HOOKDECK_API_KEY. That variable means |
| 21 | +// "exchange this for CLI credentials" everywhere else in the CLI, and is |
| 22 | +// commonly exported for CI; reusing it here would give one name two meanings and |
| 23 | +// let an ambient variable silently enable sending real events. |
| 24 | +const publishAPIKeyEnvVar = "HOOKDECK_OUTPOST_PUBLISH_API_KEY" |
| 25 | + |
| 26 | +type outpostMCPCmd struct { |
| 27 | + cmd *cobra.Command |
| 28 | + |
| 29 | + allowWrite bool |
| 30 | + readOnly bool |
| 31 | + apiKey string |
| 32 | +} |
| 33 | + |
| 34 | +func newOutpostMCPCmd() *outpostMCPCmd { |
| 35 | + mc := &outpostMCPCmd{} |
| 36 | + mc.cmd = &cobra.Command{ |
| 37 | + Use: "mcp", |
| 38 | + Args: validators.NoArgs, |
| 39 | + Short: ShortBeta("Start an MCP server for AI agent access to Outpost"), |
| 40 | + Long: LongBeta(`Starts a Model Context Protocol (MCP) server over stdio. |
| 41 | +
|
| 42 | +The server exposes Hookdeck Outpost resources — tenants, destinations, events, |
| 43 | +attempts, topics, metrics and project configuration — as MCP tools that AI |
| 44 | +agents and LLM-based clients can invoke. Tools are prefixed outpost_, so this |
| 45 | +server and 'hookdeck gateway mcp' can be configured in the same client. |
| 46 | +
|
| 47 | +The server starts read-only: tools advertise only the actions that read data, |
| 48 | +so an agent is never offered an action it cannot perform. Pass --allow-write to |
| 49 | +enable creating, changing and deleting. Two reads count as writes and are also |
| 50 | +gated, because both return a reusable credential: 'outpost_tenants token' mints |
| 51 | +a tenant-scoped access token, and 'outpost_tenants portal' returns a URL |
| 52 | +granting access to a tenant's portal. |
| 53 | +
|
| 54 | +Publishing needs a Hookdeck Project API key, which the credentials stored by |
| 55 | +'hookdeck login' cannot substitute for. Without one the publish tool is not |
| 56 | +registered at all; pass --publish-api-key or set HOOKDECK_OUTPOST_PUBLISH_API_KEY. |
| 57 | +
|
| 58 | +This deliberately does not read HOOKDECK_API_KEY, which elsewhere in the CLI |
| 59 | +means "a key to exchange for CLI credentials". Publishing sends real events to |
| 60 | +real destinations and cannot be undone, so it should not be switched on by a |
| 61 | +variable that happens to be exported for something else. |
| 62 | +
|
| 63 | +If the CLI is already authenticated, all tools are available immediately. If |
| 64 | +not, the server still starts and outpost_login initiates browser-based sign-in. |
| 65 | +Protocol traffic uses stdout only (JSON-RPC); status and errors from the CLI |
| 66 | +before the server runs go to stderr.`), |
| 67 | + Example: ` # Start the MCP server, read-only (stdio transport) |
| 68 | + hookdeck outpost mcp |
| 69 | +
|
| 70 | + # Allow tools that change data |
| 71 | + hookdeck outpost mcp --allow-write |
| 72 | +
|
| 73 | + # Allow writes, including publishing events |
| 74 | + hookdeck outpost mcp --allow-write --publish-api-key $HOOKDECK_OUTPOST_PUBLISH_API_KEY |
| 75 | +
|
| 76 | + # Pipe a JSON-RPC initialize request for testing |
| 77 | + echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}' | hookdeck outpost mcp`, |
| 78 | + RunE: mc.runOutpostMCPCmd, |
| 79 | + } |
| 80 | + |
| 81 | + mc.cmd.Flags().BoolVar(&mc.allowWrite, "allow-write", false, "Enable tools that create, change or delete data, and that return tenant credentials. Also read from "+allowWriteEnvVar+"; the flag wins.") |
| 82 | + // Users arriving from other MCP servers type --read-only reflexively. It is |
| 83 | + // already the default, so accept it rather than failing on an unknown flag. |
| 84 | + mc.cmd.Flags().BoolVar(&mc.readOnly, "read-only", false, "Run without write actions. This is the default; the flag is accepted so it can be passed explicitly, and wins over --allow-write.") |
| 85 | + // The env var is read at run time rather than used as the flag default, so a |
| 86 | + // key that is already in the environment is not printed back out by --help. |
| 87 | + mc.cmd.Flags().StringVar(&mc.apiKey, "publish-api-key", "", "Hookdeck Project API key, required by the publish tool. Also read from "+publishAPIKeyEnvVar+". HOOKDECK_API_KEY is deliberately not used here.") |
| 88 | + |
| 89 | + return mc |
| 90 | +} |
| 91 | + |
| 92 | +func addOutpostMCPCmdTo(parent *cobra.Command) { |
| 93 | + parent.AddCommand(newOutpostMCPCmd().cmd) |
| 94 | +} |
| 95 | + |
| 96 | +// resolveAllowWrite decides whether write actions are enabled. |
| 97 | +// |
| 98 | +// --read-only wins over everything so an explicit request for a safe session is |
| 99 | +// never overridden; otherwise --allow-write wins over the environment variable, |
| 100 | +// which is the more distant and easier-to-forget setting. |
| 101 | +func resolveAllowWrite(allowWriteFlag, allowWriteFlagSet, readOnly bool, envValue string) bool { |
| 102 | + if readOnly { |
| 103 | + return false |
| 104 | + } |
| 105 | + if allowWriteFlagSet { |
| 106 | + return allowWriteFlag |
| 107 | + } |
| 108 | + enabled, err := strconv.ParseBool(envValue) |
| 109 | + if err != nil { |
| 110 | + return false |
| 111 | + } |
| 112 | + return enabled |
| 113 | +} |
| 114 | + |
| 115 | +func (mc *outpostMCPCmd) runOutpostMCPCmd(cmd *cobra.Command, args []string) error { |
| 116 | + // Always build the client — it may have an empty APIKey if the CLI is not |
| 117 | + // yet authenticated. The server handles that by registering outpost_login |
| 118 | + // rather than failing to start. |
| 119 | + // |
| 120 | + // This must be the Outpost client: the projects and login tools set the |
| 121 | + // project on the client they are given, and setting it on the Gateway client |
| 122 | + // would leave every Outpost call pointed at the previous project. |
| 123 | + client := Config.GetOutpostAPIClient() |
| 124 | + |
| 125 | + // Deliberately not HOOKDECK_API_KEY. That variable means "exchange this for |
| 126 | + // CLI credentials" for `hookdeck ci` and `listen`, and the CLI encourages |
| 127 | + // exporting it for CI — so reading it here would let an unrelated ambient |
| 128 | + // variable silently grant an agent the ability to send real events. |
| 129 | + publishAPIKey := mc.apiKey |
| 130 | + if publishAPIKey == "" { |
| 131 | + publishAPIKey = os.Getenv(publishAPIKeyEnvVar) |
| 132 | + } |
| 133 | + |
| 134 | + writeEnabled := resolveAllowWrite( |
| 135 | + mc.allowWrite, |
| 136 | + cmd.Flags().Changed("allow-write"), |
| 137 | + mc.readOnly, |
| 138 | + os.Getenv(allowWriteEnvVar), |
| 139 | + ) |
| 140 | + |
| 141 | + srv := outpostmcp.NewServer(outpostmcp.ServerOptions{ |
| 142 | + Client: client, |
| 143 | + // Listing projects and validating credentials are account-level calls |
| 144 | + // that the Outpost host does not serve, so they go to the main API. |
| 145 | + AccountClient: Config.GetAPIClient(), |
| 146 | + Config: &Config, |
| 147 | + WriteEnabled: writeEnabled, |
| 148 | + PublishAPIKey: publishAPIKey, |
| 149 | + }) |
| 150 | + return srv.RunStdio(context.Background()) |
| 151 | +} |
0 commit comments