Switch gRPC admin API to Unix socket only, add client package

- Remove TCP listener support from gRPC server; Unix socket is now the
  only transport for the admin API (access controlled via filesystem
  permissions)
- Add standard gRPC health check service (grpc.health.v1.Health)
- Implement MCPROXY_* environment variable overrides for config
- Create client/mcproxy package with full API coverage and tests
- Update ARCHITECTURE.md and dev config (srv/mc-proxy.toml)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

internal/config/config.go

@@ -23,11 +23,7 @@ type Database struct {
 }
 
 type GRPC struct {
-	Addr     string `toml:"addr"`
-	TLSCert  string `toml:"tls_cert"`
-	TLSKey   string `toml:"tls_key"`
-	CACert   string `toml:"ca_cert"`   // CA cert for verifying the server (client-side)
-	ClientCA string `toml:"client_ca"` // CA cert for verifying clients (server-side mTLS)
+	Addr string `toml:"addr"` // Unix socket path (e.g., "/var/run/mc-proxy.sock")
 }
 
 type Listener struct {
@@ -64,13 +60,7 @@ type Duration struct {
 	time.Duration
 }
 
-// IsUnixSocket returns true if the gRPC address refers to a Unix domain socket.
-func (g GRPC) IsUnixSocket() bool {
-	path := strings.TrimPrefix(g.Addr, "unix:")
-	return strings.Contains(path, "/")
-}
-
-// SocketPath returns the filesystem path for a Unix socket address,
+// SocketPath returns the filesystem path for the Unix socket,
 // stripping any "unix:" prefix.
 func (g GRPC) SocketPath() string {
 	return strings.TrimPrefix(g.Addr, "unix:")
@@ -93,6 +83,10 @@ func Load(path string) (*Config, error) {
 		return nil, fmt.Errorf("parsing config: %w", err)
 	}
 
+	if err := cfg.applyEnvOverrides(); err != nil {
+		return nil, fmt.Errorf("applying env overrides: %w", err)
+	}
+
 	if err := cfg.validate(); err != nil {
 		return nil, fmt.Errorf("invalid config: %w", err)
 	}
@@ -100,6 +94,69 @@ func Load(path string) (*Config, error) {
 	return &cfg, nil
 }
 
+// applyEnvOverrides applies environment variable overrides to the config.
+// Variables use the MCPROXY_ prefix with underscore-separated paths.
+func (c *Config) applyEnvOverrides() error {
+	// Database
+	if v := os.Getenv("MCPROXY_DATABASE_PATH"); v != "" {
+		c.Database.Path = v
+	}
+
+	// gRPC
+	if v := os.Getenv("MCPROXY_GRPC_ADDR"); v != "" {
+		c.GRPC.Addr = v
+	}
+
+	// Firewall
+	if v := os.Getenv("MCPROXY_FIREWALL_GEOIP_DB"); v != "" {
+		c.Firewall.GeoIPDB = v
+	}
+	if v := os.Getenv("MCPROXY_FIREWALL_RATE_LIMIT"); v != "" {
+		var n int64
+		if _, err := fmt.Sscanf(v, "%d", &n); err != nil {
+			return fmt.Errorf("MCPROXY_FIREWALL_RATE_LIMIT: %w", err)
+		}
+		c.Firewall.RateLimit = n
+	}
+	if v := os.Getenv("MCPROXY_FIREWALL_RATE_WINDOW"); v != "" {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return fmt.Errorf("MCPROXY_FIREWALL_RATE_WINDOW: %w", err)
+		}
+		c.Firewall.RateWindow = Duration{d}
+	}
+
+	// Proxy timeouts
+	if v := os.Getenv("MCPROXY_PROXY_CONNECT_TIMEOUT"); v != "" {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return fmt.Errorf("MCPROXY_PROXY_CONNECT_TIMEOUT: %w", err)
+		}
+		c.Proxy.ConnectTimeout = Duration{d}
+	}
+	if v := os.Getenv("MCPROXY_PROXY_IDLE_TIMEOUT"); v != "" {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return fmt.Errorf("MCPROXY_PROXY_IDLE_TIMEOUT: %w", err)
+		}
+		c.Proxy.IdleTimeout = Duration{d}
+	}
+	if v := os.Getenv("MCPROXY_PROXY_SHUTDOWN_TIMEOUT"); v != "" {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return fmt.Errorf("MCPROXY_PROXY_SHUTDOWN_TIMEOUT: %w", err)
+		}
+		c.Proxy.ShutdownTimeout = Duration{d}
+	}
+
+	// Log
+	if v := os.Getenv("MCPROXY_LOG_LEVEL"); v != "" {
+		c.Log.Level = v
+	}
+
+	return nil
+}
+
 func (c *Config) validate() error {
 	if c.Database.Path == "" {
 		return fmt.Errorf("database.path is required")
@@ -139,11 +196,11 @@ func (c *Config) validate() error {
 		return fmt.Errorf("firewall.rate_window is required when rate_limit is set")
 	}
 
-	// Validate gRPC config: if enabled, TLS cert and key are required
-	// (unless using a Unix socket, which doesn't need TLS).
-	if c.GRPC.Addr != "" && !c.GRPC.IsUnixSocket() {
-		if c.GRPC.TLSCert == "" || c.GRPC.TLSKey == "" {
-			return fmt.Errorf("grpc: tls_cert and tls_key are required when grpc.addr is a TCP address")
+	// Validate gRPC config: if enabled, addr must be a Unix socket path.
+	if c.GRPC.Addr != "" {
+		path := c.GRPC.SocketPath()
+		if !strings.Contains(path, "/") {
+			return fmt.Errorf("grpc.addr must be a Unix socket path (e.g., /var/run/mc-proxy.sock)")
 		}
 	}