Merge pull request #155 from buildkite/feat_1password_key_loader

feat: added support for retrieving tokens directly from 1password

Author: wolfeidau

README.md

@@ -481,11 +481,80 @@ This is particularly useful when you want to grant AI assistants access to query
 
 | Variable | Description | Default | Usage |
 |----------|-------------|---------|-------|
-| `BUILDKITE_API_TOKEN` | Your Buildkite API access token | Required | Authentication for all API requests |
+| `BUILDKITE_API_TOKEN` | Your Buildkite API access token | Required* | Authentication for all API requests |
+| `BUILDKITE_API_TOKEN_FROM_1PASSWORD` | 1Password item reference for API token | - | Alternative to `BUILDKITE_API_TOKEN`. Format: `op://vault/item/field` |
 | `BUILDKITE_TOOLSETS` | Comma-separated list of toolsets to enable | `all` | Controls which tool groups are available |
 | `BUILDKITE_READ_ONLY` | Enable read-only mode (filters out write operations) | `false` | Security setting for AI assistants |
 | `HTTP_LISTEN_ADDR` | Address for HTTP server to listen on | `localhost:3000` | Used with `http` command |
 
+*Either `BUILDKITE_API_TOKEN` or `BUILDKITE_API_TOKEN_FROM_1PASSWORD` must be specified, but not both.
+
+---
+
+## 🔐 1Password Integration
+
+For enhanced security, you can store your Buildkite API token in [1Password](https://1password.com/) and reference it using the 1Password CLI instead of exposing it as a plain environment variable.
+
+### Prerequisites
+
+- [1Password CLI](https://developer.1password.com/docs/cli/get-started/) installed and authenticated
+- Your Buildkite API token stored in a 1Password item
+
+### Usage
+
+Instead of using `BUILDKITE_API_TOKEN`, use `BUILDKITE_API_TOKEN_FROM_1PASSWORD` with a 1Password item reference:
+
+**Environment Variable:**
+```bash
+export BUILDKITE_API_TOKEN_FROM_1PASSWORD="op://Private/Buildkite API Token/credential"
+buildkite-mcp-server stdio
+```
+
+**Command Line:**
+```bash
+buildkite-mcp-server stdio --api-token-from-1password="op://Private/Buildkite API Token/credential"
+```
+
+> **Note:** The server will call `op read -n <reference>` to fetch the token. Ensure your 1Password CLI is properly authenticated before starting the server.
+
+### Client Configuration Examples
+
+<details>
+<summary>Claude Desktop with 1Password</summary>
+
+```jsonc
+{
+  "mcpServers": {
+    "buildkite": {
+      "command": "buildkite-mcp-server",
+      "args": ["stdio"],
+      "env": {
+        "BUILDKITE_API_TOKEN_FROM_1PASSWORD": "op://Private/Buildkite API Token/credential"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>VS Code with 1Password</summary>
+
+```jsonc
+{
+  "servers": {
+    "buildkite": {
+      "command": "buildkite-mcp-server",
+      "args": ["stdio"],
+      "env": {
+        "BUILDKITE_API_TOKEN_FROM_1PASSWORD": "op://Private/Buildkite API Token/credential"
+      }
+    }
+  }
+}
+```
+</details>
+
 ---
 
 <a name="tools"></a>

cmd/buildkite-mcp-server/main.go

@@ -20,16 +20,17 @@ var (
 	version = "dev"
 
 	cli struct {
-		Stdio        commands.StdioCmd `cmd:"" help:"stdio mcp server."`
-		HTTP         commands.HTTPCmd  `cmd:"" help:"http mcp server. (pass --use-sse to use SSE transport"`
-		Tools        commands.ToolsCmd `cmd:"" help:"list available tools." hidden:""`
-		APIToken     string            `help:"The Buildkite API token to use." env:"BUILDKITE_API_TOKEN"`
-		BaseURL      string            `help:"The base URL of the Buildkite API to use." env:"BUILDKITE_BASE_URL" default:"https://api.buildkite.com/"`
-		CacheURL     string            `help:"The blob storage URL for job logs cache." env:"BKLOG_CACHE_URL"`
-		Debug        bool              `help:"Enable debug mode." env:"DEBUG"`
-		OTELExporter string            `help:"OpenTelemetry exporter to enable. Options are 'http/protobuf', 'grpc', or 'noop'." enum:"http/protobuf, grpc, noop" env:"OTEL_EXPORTER_OTLP_PROTOCOL" default:"noop"`
-		HTTPHeaders  []string          `help:"Additional HTTP headers to send with every request. Format: 'Key: Value'" name:"http-header" env:"BUILDKITE_HTTP_HEADERS"`
-		Version      kong.VersionFlag
+		Stdio                 commands.StdioCmd `cmd:"" help:"stdio mcp server."`
+		HTTP                  commands.HTTPCmd  `cmd:"" help:"http mcp server. (pass --use-sse to use SSE transport"`
+		Tools                 commands.ToolsCmd `cmd:"" help:"list available tools." hidden:""`
+		APIToken              string            `help:"The Buildkite API token to use." env:"BUILDKITE_API_TOKEN"`
+		APITokenFrom1Password string            `help:"The 1Password item to read the Buildkite API token from. Format: 'op://vault/item/field'" env:"BUILDKITE_API_TOKEN_FROM_1PASSWORD"`
+		BaseURL               string            `help:"The base URL of the Buildkite API to use." env:"BUILDKITE_BASE_URL" default:"https://api.buildkite.com/"`
+		CacheURL              string            `help:"The blob storage URL for job logs cache." env:"BKLOG_CACHE_URL"`
+		Debug                 bool              `help:"Enable debug mode." env:"DEBUG"`
+		OTELExporter          string            `help:"OpenTelemetry exporter to enable. Options are 'http/protobuf', 'grpc', or 'noop'." enum:"http/protobuf, grpc, noop" env:"OTEL_EXPORTER_OTLP_PROTOCOL" default:"noop"`
+		HTTPHeaders           []string          `help:"Additional HTTP headers to send with every request. Format: 'Key: Value'" name:"http-header" env:"BUILDKITE_HTTP_HEADERS"`
+		Version               kong.VersionFlag
 	}
 )
 
@@ -64,8 +65,14 @@ func run(ctx context.Context, cmd *kong.Context) error {
 	// Parse additional headers into a map
 	headers := commands.ParseHeaders(cli.HTTPHeaders)
 
+	// resolve the api token from either the token or 1password flag
+	apiToken, err := commands.ResolveAPIToken(cli.APIToken, cli.APITokenFrom1Password)
+	if err != nil {
+		return fmt.Errorf("failed to resolve Buildkite API token: %w", err)
+	}
+
 	client, err := gobuildkite.NewOpts(
-		gobuildkite.WithTokenAuth(cli.APIToken),
+		gobuildkite.WithTokenAuth(apiToken),
 		gobuildkite.WithUserAgent(commands.UserAgent(version)),
 		gobuildkite.WithHTTPClient(trace.NewHTTPClientWithHeaders(headers)),
 		gobuildkite.WithBaseURL(cli.BaseURL),

internal/commands/command.go

@@ -1,11 +1,14 @@
 package commands
 
 import (
+	"errors"
 	"fmt"
+	"os/exec"
 	"runtime"
 
 	buildkitelogs "github.com/buildkite/buildkite-logs"
 	gobuildkite "github.com/buildkite/go-buildkite/v4"
+	"github.com/rs/zerolog/log"
 )
 
 type Globals struct {
@@ -20,3 +23,42 @@ func UserAgent(version string) string {
 
 	return fmt.Sprintf("buildkite-mcp-server/%s (%s; %s)", version, os, arch)
 }
+
+func ResolveAPIToken(token, tokenFrom1Password string) (string, error) {
+	if token != "" && tokenFrom1Password != "" {
+		return "", fmt.Errorf("cannot specify both --api-token and --api-token-from-1password")
+	}
+	if token == "" && tokenFrom1Password == "" {
+		return "", fmt.Errorf("must specify either --api-token or --api-token-from-1password")
+	}
+	if token != "" {
+		return token, nil
+	}
+
+	// Fetch the token from 1Password
+	opToken, err := fetchTokenFrom1Password(tokenFrom1Password)
+	if err != nil {
+		return "", fmt.Errorf("failed to fetch API token from 1Password: %w", err)
+	}
+	return opToken, nil
+}
+
+func fetchTokenFrom1Password(opID string) (string, error) {
+	// read the token using the 1Password CLI with `-n` to avoid a trailing newline
+	out, err := exec.Command("op", "read", "-n", opID).Output()
+	if err != nil {
+		return "", expandExecErr(err)
+	}
+
+	log.Info().Msg("Fetched API token from 1Password")
+
+	return string(out), nil
+}
+
+func expandExecErr(err error) error {
+	var exitErr *exec.ExitError
+	if errors.As(err, &exitErr) {
+		return fmt.Errorf("command failed: %s", string(exitErr.Stderr))
+	}
+	return err
+}