feat: add --scope flag to gram install command (#819)

## Summary
- Add `--scope` flag to `gram install` command to control MCP server
installation location
- Support both `user` (default) and `project` scope levels
- Apply scope across Claude Code and Gemini CLI installations

## Changes
- **New flag**: `--scope` with values `user` (default) or `project`
- `user`: Installs to `~/.claude/settings.local.json` (user-level
config)
- `project`: Installs to `.mcp.json` in current directory (project-level
config)
- **Claude Code**: Updated to pass scope to both native `claude` CLI and
fallback config file writer
  - Maps `project` → `local` for Claude CLI compatibility
- **Gemini CLI**: Updated to pass scope parameter to `gemini mcp add`
command
- **Default behavior**: Changed to `user` scope for better portability
across projects

## Usage Examples
```bash
# Install to user-level config (default)
gram install claude-code --toolset my-toolset

# Install to project-level config
gram install claude-code --toolset my-toolset --scope project

# Install using Gemini CLI
gram install gemini-cli --toolset my-toolset --scope user
```

## Test plan
- [x] Build succeeds: `mise build:cli`
- [x] Linting passes: `mise lint:cli`
- [x] Manual testing with Claude Code installation (both scopes)
- [x] Manual testing with Gemini CLI installation (both scopes)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <[email protected]>

Author: simplesagar

.changeset/four-shirts-cheer.md

@@ -0,0 +1,5 @@
+---
+"cli": patch
+---
+
+feat: add --scope flag to gram install command to determine whether the mcp config is added to the user, project or local config locations. 

cli/internal/app/install.go

@@ -36,6 +36,11 @@ var installFlags = []cli.Flag{
 		Name:  "env-var",
 		Usage: "Environment variable name to use for API key substitution (e.g., MCP_API_KEY). If provided, uses ${VAR} syntax instead of hardcoding the key",
 	},
+	&cli.StringFlag{
+		Name:  "scope",
+		Usage: "Configuration scope: 'project' for .mcp.json in current directory, 'user' for ~/.claude/settings.local.json (defaults to user)",
+		Value: "user",
+	},
 }
 
 func newInstallCommand() *cli.Command {

cli/internal/app/install_claude_code.go

@@ -30,6 +30,8 @@ func doInstallClaudeCode(c *cli.Context) error {
 	}
 
 	useEnvVar := info.EnvVarName != ""
+	scope := c.String("scope")
+
 	if useEnvVar {
 		logger.InfoContext(ctx, "using environment variable substitution",
 			slog.String("var", info.EnvVarName),
@@ -38,9 +40,10 @@ func doInstallClaudeCode(c *cli.Context) error {
 
 	// Try to use native claude CLI with HTTP transport first
 	if mcp.IsClaudeCLIAvailable() {
-		logger.InfoContext(ctx, "using claude CLI with native HTTP transport")
+		logger.InfoContext(ctx, "using claude CLI with native HTTP transport",
+			slog.String("scope", scope))
 
-		if err := mcp.InstallViaClaudeCLI(info, useEnvVar); err != nil {
+		if err := mcp.InstallViaClaudeCLI(info, useEnvVar, scope); err != nil {
 			logger.WarnContext(ctx, "claude CLI installation failed, falling back to config file",
 				slog.String("error", err.Error()))
 		} else {
@@ -69,10 +72,26 @@ func doInstallClaudeCode(c *cli.Context) error {
 	if err != nil {
 		return fmt.Errorf("failed to get config locations: %w", err)
 	}
-	configPath := locations[0].Path
+
+	// Determine config path based on scope flag (already declared above)
+	var configPath string
+	var configDesc string
+
+	switch scope {
+	case "project":
+		configPath = locations[0].Path
+		configDesc = locations[0].Description
+	case "user":
+		configPath = locations[1].Path
+		configDesc = locations[1].Description
+	default:
+		return fmt.Errorf("invalid scope '%s': must be 'project' or 'user'", scope)
+	}
+
 	logger.InfoContext(ctx, "using config location",
 		slog.String("path", configPath),
-		slog.String("type", locations[0].Description))
+		slog.String("type", configDesc),
+		slog.String("scope", scope))
 
 	config, err := claudecode.ReadConfig(configPath)
 	if err != nil {

cli/internal/app/install_gemini_cli.go

@@ -28,16 +28,19 @@ func doInstallGeminiCLI(c *cli.Context) error {
 	}
 
 	useEnvVar := info.EnvVarName != ""
+	scope := c.String("scope")
+
 	if useEnvVar {
 		logger.InfoContext(ctx, "using environment variable substitution",
 			slog.String("var", info.EnvVarName),
 			slog.String("header", info.HeaderName))
 	}
 
-	// Execute: gemini mcp add --transport http "name" "url" --header "Header:${VAR}"
-	logger.InfoContext(ctx, "installing via gemini CLI with native HTTP transport")
+	// Execute: gemini mcp add --transport http --scope <scope> "name" "url" --header "Header:${VAR}"
+	logger.InfoContext(ctx, "installing via gemini CLI with native HTTP transport",
+		slog.String("scope", scope))
 
-	if err := mcp.InstallViaGeminiCLI(info, useEnvVar); err != nil {
+	if err := mcp.InstallViaGeminiCLI(info, useEnvVar, scope); err != nil {
 		return fmt.Errorf("failed to install via gemini CLI: %w", err)
 	}
 

cli/internal/mcp/claude_cli.go

@@ -12,9 +12,10 @@ func IsClaudeCLIAvailable() bool {
 }
 
 // InstallViaClaudeCLI installs an MCP server using the native claude CLI
-// Uses: claude mcp add --transport http "name" "url" --header "Header:${VAR}"
+// Uses: claude mcp add --transport http --scope <scope> "name" "url" --header "Header:${VAR}"
+// scope: "project" (maps to claude CLI's "local") or "user"
 // Returns an error if the claude CLI is not available
-func InstallViaClaudeCLI(info *ToolsetInfo, useEnvVar bool) error {
+func InstallViaClaudeCLI(info *ToolsetInfo, useEnvVar bool, scope string) error {
 	var headerValue string
 
 	if useEnvVar {
@@ -25,11 +26,20 @@ func InstallViaClaudeCLI(info *ToolsetInfo, useEnvVar bool) error {
 		headerValue = fmt.Sprintf("%s:%s", info.HeaderName, info.APIKey)
 	}
 
-	// Build command: claude mcp add --transport http "name" "url" --header "Header:value"
+	// Map our scope terminology to claude CLI's scope terminology
+	// Our "project" -> Claude CLI's "local" (.mcp.json in current directory)
+	// Our "user" -> Claude CLI's "user" (~/.claude/settings.local.json)
+	claudeScope := scope
+	if scope == "project" {
+		claudeScope = "local"
+	}
+
+	// Build command: claude mcp add --transport http --scope <scope> "name" "url" --header "Header:value"
 	args := []string{
 		"mcp",
 		"add",
 		"--transport", "http",
+		"--scope", claudeScope,
 		info.Name,
 		info.URL,
 		"--header", headerValue,

cli/internal/mcp/gemini_cli.go

@@ -12,8 +12,9 @@ func IsGeminiCLIAvailable() bool {
 }
 
 // InstallViaGeminiCLI installs an MCP server using the native gemini CLI
-// Uses: gemini mcp add --transport http "name" "url" --header "Header:${VAR}"
-func InstallViaGeminiCLI(info *ToolsetInfo, useEnvVar bool) error {
+// Uses: gemini mcp add --transport http --scope <scope> "name" "url" --header "Header:${VAR}"
+// scope: "project" or "user" (will be passed as-is if gemini CLI supports it)
+func InstallViaGeminiCLI(info *ToolsetInfo, useEnvVar bool, scope string) error {
 	var headerValue string
 
 	if useEnvVar {
@@ -24,11 +25,13 @@ func InstallViaGeminiCLI(info *ToolsetInfo, useEnvVar bool) error {
 		headerValue = fmt.Sprintf("%s:%s", info.HeaderName, info.APIKey)
 	}
 
-	// Build command: gemini mcp add --transport http "name" "url" --header "Header:value"
+	// Build command: gemini mcp add --transport http --scope <scope> "name" "url" --header "Header:value"
+	// Note: scope support depends on gemini CLI version
 	args := []string{
 		"mcp",
 		"add",
 		"--transport", "http",
+		"--scope", scope,
 		info.Name,
 		info.URL,
 		"--header", headerValue,