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>

pkg/tool/tool_test.go

@@ -83,7 +83,7 @@ func TestTools(t *testing.T) {
 			flag.ReadOnly = tt.readOnly
 			flag.AllowedTools = tt.allowed
 
-			tr := New()
+			tr := New("scope1")
 			for _, n := range tt.read {
 				tr.RegisterRead(makeTool(n))
 			}
@@ -98,3 +98,130 @@ func TestTools(t *testing.T) {
 		})
 	}
 }
+
+func TestToolsScopeFiltering(t *testing.T) {
+	tests := []struct {
+		name          string
+		toolScope     string
+		readOnly      bool
+		allowedScopes map[string]struct{}
+		allowedTools  map[string]struct{}
+		read          []string
+		write         []string
+		want          []string
+	}{
+		{
+			name:      "no scope or tool filters returns all",
+			toolScope: "repository",
+			read:      []string{"r1"},
+			write:     []string{"w1"},
+			want:      []string{"w1", "r1"},
+		},
+		{
+			name:          "matching scope keeps everything",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"repository": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{"w1", "r1"},
+		},
+		{
+			name:          "non-matching scope drops everything not in allowed tools",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"file": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{},
+		},
+		{
+			name:         "tools-only allowlist behaves as before scopes existed",
+			toolScope:    "repository",
+			allowedTools: map[string]struct{}{"r1": {}},
+			read:         []string{"r1", "r2"},
+			write:        []string{"w1"},
+			want:         []string{"r1"},
+		},
+		{
+			name:          "scope and tools allowlists are unioned",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"file": {}},
+			allowedTools:  map[string]struct{}{"r1": {}},
+			read:          []string{"r1", "r2"},
+			write:         []string{"w1"},
+			want:          []string{"r1"},
+		},
+		{
+			name:          "matching scope combined with read-only drops write entries",
+			toolScope:     "repository",
+			readOnly:      true,
+			allowedScopes: map[string]struct{}{"repository": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{"r1"},
+		},
+		{
+			name:          "unknown scope name matches nothing",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"unknown_scope": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			origRO, origAllowScopes, origAllowTools := flag.ReadOnly, flag.AllowedScopes, flag.AllowedTools
+			t.Cleanup(func() {
+				flag.ReadOnly, flag.AllowedScopes, flag.AllowedTools = origRO, origAllowScopes, origAllowTools
+			})
+			flag.ReadOnly = tt.readOnly
+			flag.AllowedScopes = tt.allowedScopes
+			flag.AllowedTools = tt.allowedTools
+
+			tr := New(tt.toolScope)
+			for _, n := range tt.read {
+				tr.RegisterRead(makeTool(n))
+			}
+			for _, n := range tt.write {
+				tr.RegisterWrite(makeTool(n))
+			}
+
+			got := names(tr.Tools())
+			if !slices.Equal(got, tt.want) {
+				t.Errorf("Tools() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestScope(t *testing.T) {
+	tr := New("repository")
+	if got := tr.Scope(); got != "repository" {
+		t.Errorf("Scope() = %q, want %q", got, "repository")
+	}
+}
+
+func TestWarnUnmatchedAllowedScopes(t *testing.T) {
+	origAllowScopes := flag.AllowedScopes
+	t.Cleanup(func() {
+		flag.AllowedScopes = origAllowScopes
+	})
+
+	repoTool := New("repository")
+	fileTool := New("file")
+
+	t.Run("empty allowlist is a no-op", func(t *testing.T) {
+		flag.AllowedScopes = nil
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+
+	t.Run("known scopes produce no warning", func(t *testing.T) {
+		flag.AllowedScopes = map[string]struct{}{"repository": {}, "file": {}}
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+
+	t.Run("unknown scope is tolerated", func(t *testing.T) {
+		flag.AllowedScopes = map[string]struct{}{"not_a_real_scope": {}}
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+}