feat(cmd): add -S/--scope to load only selected tool scopes (#219)

`-O` / `--tools` can already narrow the exposed tool set, but it needs every tool spelled out by name. `-S` / `--scope` (`GITEA_SCOPES`) complements it by selecting whole scopes, using the same names the `Scope` column of the tool tables documents.

```bash
gitea-mcp -S issue,pull_request                     # only those scopes
gitea-mcp --scope repository,branch --tools get_me   # those scopes plus one extra tool
```

## What changed

- Each scope is one `tool.Tool` registry carrying a canonical name, so `operation/repo` is split into the six scopes its files already imply: `repository` (`repo.go` + `tree.go`), `file`, `branch`, `tag`, `commit`, `release`. The other twelve packages map 1:1, giving 18 scopes.
- The two allowlists combine as a **union**: with neither set every tool loads; with only `--tools` set behaviour is unchanged; with both set, the selected scopes' tools plus the individually named tools load. `-r` / `GITEA_READONLY` still hides write tools on top.
- Scope names are normalized on input (case, spaces, hyphens), so `Pull Request`, `pull-request` and `PULL_REQUEST` all resolve to `pull_request`. Unknown names only warn and list the valid scopes, mirroring how `--tools` treats unknown tool names.
- The `Scope` column of all three READMEs now uses the canonical names verbatim, so it doubles as the reference for `--scope`, and `TestReadmeToolTables` compares that column against the registry in both directions — no translation table needed.
- Flag parsing moves from `cmd.init()` into `Execute()`. `main()` only ever calls `Execute()`, so this is behaviourally equivalent, and it makes the `cmd` package testable at all: previously the `init()` parse of `os.Args` hit `flag.CommandLine`'s `ExitOnError` on `go test`'s own `-test.*` flags.

## Verification

`make fmt`, `make lint-go` (0 issues) and `go test ./...` all pass. New tests cover the filter matrix (no filters / scope-only / tools-only regression / union / read-only interaction / unknown scope), scope-name uniqueness across `domainTools`, and the flag+env parsing and normalization.

Smoke-tested `tools/list` over stdio against the built binary:

| flags | tools exposed |
| :-- | :-- |
| _none_ | 54 (identical to `main`) |
| `-S branch` | `create_branch`, `delete_branch`, `list_branches` |
| `--scope 'Pull Request,TAG'` | the 4 `pull_request` + 4 `tag` tools |
| `-O get_me` | `get_me` (unchanged) |
| `-S commit -O get_me` | `get_commit`, `list_commits`, `get_me` |
| `-S file -r` | `get_dir_contents`, `get_file_contents` |
| `-S bogus,issue` | the 4 `issue` tools, plus a warning naming the valid scopes |

Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/219
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: yp05327 <576951401@qq.com>

cmd/cmd.go

@@ -20,16 +20,13 @@ var (
 	port                            int
 	token                           string
 	tools                           string
+	scopes                          string
 	version                         bool
 	maxInlineAttachmentBytes        int
 	maxInlineAttachmentBytesFlagSet bool
 	osExit                          = os.Exit
 )
 
-func init() {
-	initFlagSet(flag.CommandLine, os.Args[1:], os.Getenv, os.ReadFile, os.Stderr)
-}
-
 func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, readFile func(string) ([]byte, error), stderr io.Writer) {
 	fs.StringVar(&flagPkg.Mode, "t", "stdio", "")
 	fs.StringVar(&flagPkg.Mode, "transport", "stdio", "")
@@ -44,6 +41,9 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 	defaultTools := getenv("GITEA_TOOLS")
 	fs.StringVar(&tools, "O", defaultTools, "")
 	fs.StringVar(&tools, "tools", defaultTools, "")
+	defaultScopes := getenv("GITEA_SCOPES")
+	fs.StringVar(&scopes, "S", defaultScopes, "")
+	fs.StringVar(&scopes, "scope", defaultScopes, "")
 	fs.BoolVar(&flagPkg.Debug, "d", false, "")
 	fs.BoolVar(&flagPkg.Debug, "debug", false, "")
 	fs.BoolVar(&flagPkg.Insecure, "k", false, "")
@@ -72,6 +72,7 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 		fmt.Fprintf(w, "  -T, -token <token>\tPersonal access token\n")
 		fmt.Fprintf(w, "  -r, -read-only\tExpose only read-only tools\n")
 		fmt.Fprintf(w, "  -O, -tools <names>\tComma-separated list of tool names to expose\n")
+		fmt.Fprintf(w, "  -S, -scope <names>\tComma-separated list of tool scopes to expose\n")
 		fmt.Fprintf(w, "  -d, -debug\tEnable debug mode\n")
 		fmt.Fprintf(w, "  -k, -insecure\tIgnore TLS certificate errors\n")
 		fmt.Fprintf(w, "  -max-inline-attachment-bytes <bytes>\tInline image attachments up to this size (default: 5242880)\n")
@@ -85,6 +86,7 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 		fmt.Fprintf(w, "  GITEA_INSECURE\tSet to 'true' to ignore TLS errors\n")
 		fmt.Fprintf(w, "  GITEA_MAX_INLINE_ATTACHMENT_BYTES\tOverride inline image attachment size limit in bytes\n")
 		fmt.Fprintf(w, "  GITEA_READONLY\tSet to 'true' for read-only mode\n")
+		fmt.Fprintf(w, "  GITEA_SCOPES\tComma-separated list of tool scopes to expose\n")
 		fmt.Fprintf(w, "  GITEA_TOOLS\tComma-separated list of tool names to expose\n")
 		fmt.Fprintf(w, "  MCP_MODE\tOverride transport mode\n")
 		_ = w.Flush()
@@ -131,6 +133,16 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 	if len(allowed) > 0 {
 		flagPkg.AllowedTools = allowed
 	}
+
+	allowedScopes := map[string]struct{}{}
+	for s := range strings.SplitSeq(scopes, ",") {
+		if s = normalizeScope(s); s != "" {
+			allowedScopes[s] = struct{}{}
+		}
+	}
+	if len(allowedScopes) > 0 {
+		flagPkg.AllowedScopes = allowedScopes
+	}
 	if getenv("GITEA_DEBUG") == "true" {
 		flagPkg.Debug = true
 	}
@@ -149,7 +161,19 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 	}
 }
 
+// normalizeScope trims whitespace, lowercases, and converts internal spaces
+// and hyphens to underscores, so "Pull Request", "pull-request", and
+// "PULL_REQUEST" all normalize to "pull_request".
+func normalizeScope(s string) string {
+	s = strings.TrimSpace(s)
+	s = strings.ToLower(s)
+	s = strings.ReplaceAll(s, " ", "_")
+	s = strings.ReplaceAll(s, "-", "_")
+	return s
+}
+
 func Execute() {
+	initFlagSet(flag.CommandLine, os.Args[1:], os.Getenv, os.ReadFile, os.Stderr)
 	if version {
 		fmt.Fprintln(os.Stdout, flagPkg.Version)
 		return