Summary

This PR delivers Batch 4 hardening for scope/permission consistency and includes a small follow-up for docstring lint compliance.

Issue Breakdown

• C-22: Tag discovery scope consistency

  • Updated tag discovery endpoints to derive request scope and pass it through to the tag service.
  • Updated tag service queries to apply visibility filtering (public/team/owner/unrestricted admin context) rather than global tag aggregation.
  • Updated admin tags endpoint to use the same scoped behavior so admin API/UI and protocol paths remain consistent.
  • Added regression tests for public-only, team-scoped, and unrestricted admin contexts.

• C-24: Completion scope consistency

  • Updated /protocol/completion/complete and RPC completion/complete to pass scoped caller context into completion service.
  • Updated completion service prompt/resource lookups to enforce visibility-aware filtering.
  • Added regression tests covering deny paths and allowed scoped paths for prompt/resource completion.

• C-27: Admin middleware token-scope enforcement

  • Updated admin middleware to treat public-only token scope (teams=[]) as restricted for /admin/*.
  • Preserved explicit unrestricted admin behavior only for explicit unrestricted context.
  • Added regression tests for deny/allow behavior on admin paths.

• C-32: Granular admin token-scoping permissions

  • Replaced coarse admin path mapping with granular admin route-to-permission mapping.
  • Added default-deny behavior for unmapped /admin/* routes.
  • Added negative and positive tests to verify cross-domain permission boundaries.

• C-23: Verification and guard coverage

  • Re-verified current behavior and did not reproduce the claimed multi-team collapse issue.
  • Added guard test to ensure multi-team API tokens do not collapse to a single team_id in fallback auth path.

• Flake8 follow-up: DAR docstring completeness

  • Added missing docstring params/returns entries in touched files to satisfy DAR checks.
  • No runtime behavior changes in this follow-up section.

Key Files Updated

• mcpgateway/main.py
• mcpgateway/admin.py
• mcpgateway/middleware/token_scoping.py
• mcpgateway/services/completion_service.py
• mcpgateway/services/tag_service.py
• tests/unit/mcpgateway/test_main.py
• tests/unit/mcpgateway/test_main_extended.py
• tests/unit/mcpgateway/test_admin.py
• tests/unit/mcpgateway/test_auth.py
• tests/unit/mcpgateway/middleware/test_token_scoping.py
• tests/unit/mcpgateway/services/test_completion_service.py
• tests/unit/mcpgateway/services/test_tag_service.py

Validation

• uv run pytest tests/unit/mcpgateway/test_main.py tests/unit/mcpgateway/test_main_extended.py tests/unit/mcpgateway/test_admin.py tests/unit/mcpgateway/test_auth.py tests/unit/mcpgateway/middleware/test_token_scoping.py tests/unit/mcpgateway/services/test_completion_service.py tests/unit/mcpgateway/services/test_tag_service.py
• uv run pytest tests/unit/mcpgateway/services/test_tag_service.py tests/unit/mcpgateway/test_main.py::TestTagEndpoints tests/unit/mcpgateway/test_admin.py::test_admin_list_tags tests/unit/mcpgateway/test_admin.py::test_admin_list_tags_admin_bypass_context
• uv run pytest tests/unit/mcpgateway/services/test_completion_service.py tests/unit/mcpgateway/test_main.py::TestProtocolEndpoints::test_handle_completion_endpoint tests/unit/mcpgateway/test_main.py::TestProtocolEndpoints::test_handle_completion_endpoint_admin_bypass tests/unit/mcpgateway/test_main.py::TestRPCEndpoints::test_rpc_completion_complete
• uv run pytest tests/unit/mcpgateway/test_main_extended.py::TestAdminAuthMiddleware::test_admin_auth_public_only_admin_token_denied tests/unit/mcpgateway/test_main_extended.py::TestAdminAuthMiddleware::test_admin_auth_explicit_null_teams_admin_bypass_allowed
• uv run pytest tests/unit/mcpgateway/middleware/test_token_scoping.py -k "admin_permissions_use_canonical_constants or regex_pattern_precision_admin"
• uv run pytest tests/unit/mcpgateway/test_auth.py::TestFallbackPathWithRequest::test_fallback_multi_team_api_token_does_not_set_single_team_id
• make flake8