feat(mcp): move MCP tests + update integ imports + docs (3/3)

[fede-kamel]

Strategy: 3-PR stack for a large refactor

Issue #1431 asks for two things at once: relocating the MCP package AND preserving backwards compatibility. An atomic implementation of both is ~2000 lines of changes (mostly because git can't detect a rename when both paths must keep working). Instead, the work is split into three stacked PRs:

Step	PR	What it does	Size
1 / 3	#2148	Introduce strands.mcp as a pure re-export of strands.tools.mcp. Additive only.	+42 / -0
2 / 3	#2152	Move implementation to strands.mcp via git mv; strands.tools.mcp becomes a sys.modules-based deprecation shim.	+38 / -28 (git -M)
3 / 3	#2158 (this PR)	Move tests, add backcompat-aliases suite, update tests_integ/mcp, README, and AGENTS.md.	+149 / -63

Each step leaves main in a valid state, is independently revertable, and is independently reviewable. The order matters:

• Step 1 must precede step 2 so that strands.mcp is part of the public API before the implementation moves.
• Step 2 must precede this one because the integration tests and docs can't reference the new canonical path until the code actually lives there.

Role of this PR in the stack

Step 2 delivered the semantic move: the implementation lives at strands.mcp and strands.tools.mcp is a thin sys.modules-aliasing shim. But it deliberately stopped there to keep its diff honest (pure renames + one shim file). This PR finishes the story by bringing the repo's own tests and documentation in line with the canonical path:

• Unit tests relocate alongside the code.
• A new test_deprecated_aliases.py suite lives at the old location (next to the alias it tests), locking in the four backcompat guarantees as regression tests.
• Integration tests under tests_integ/mcp/ swap their imports to the canonical path.
• README and AGENTS.md show users the new import path.

---

Summary

Third and final stacked PR for #1431. Depends on #2152.

Moves the MCP unit tests into tests/strands/mcp/, adds a dedicated deprecated-aliases test suite at the legacy location, and updates integration tests, README, and AGENTS.md to reference the new canonical import path.

What this PR does

• Move unit tests — tests/strands/tools/mcp/* → tests/strands/mcp/* (7 files, git-detected renames; conftest.py, test_mcp_client.py, test_mcp_agent_tool.py, test_mcp_client_contextvar.py, test_mcp_client_tasks.py, test_mcp_client_tool_provider.py, test_mcp_instrumentation.py) with import-path updates inside each file (strands.tools.mcp → strands.mcp).
• Add tests/strands/tools/mcp/test_deprecated_aliases.py — covers the four backcompat guarantees from feat(mcp): move MCP implementation to strands.mcp, deprecate old path (2/3) #2152:
  • Package import emits DeprecationWarning.
  • Public API identity with strands.mcp.
  • Legacy submodule imports (from strands.tools.mcp import mcp_client) resolve via sys.modules to the canonical modules.
  • Deep submodule imports (from strands.tools.mcp.mcp_client import X) return the same objects as the canonical path.
• Update tests/strands/mcp/test_canonical_import_path.py — post-move, the test verifies strands.tools.mcp aliases strands.mcp (previously the other direction, reflecting the pre-move feat(mcp): add strands.mcp as canonical MCP import path (1/3) #2148 intermediate state).
• Update tests_integ/mcp/* imports — 7 files, one-line import swap each, from the legacy path to the canonical path.
• Update README.md — the MCP example at line 111 now uses from strands.mcp import MCPClient.
• Update AGENTS.md — the TasksConfig snippet now uses from strands.mcp import MCPClient, TasksConfig.
• Update tests/strands/tools/test_registry.py — internal import swap.

Diff size

19 files changed, +149 / -63 per git diff --stat -M. The moves are git-tracked renames; the only material additions are the new test_deprecated_aliases.py suite (~78 lines) and the test-body import updates.

Tests run locally (Python 3.13)

Check	Command	Result
Full unit suite	hatch test --python 3.13 tests/	2618 passed (+4 from #2152: the new deprecated-aliases tests)
Lint	hatch fmt --linter --check	ruff clean
Type check	mypy ./src via hatch-static-analysis	Success, 143 source files
MCP-scoped suite	hatch test tests/strands/mcp/ tests/strands/tools/mcp/ tests/strands/tools/test_registry.py	184 passed
Integration (MCP-only)	AWS_DEFAULT_REGION=us-east-1 hatch test tests_integ/mcp/test_mcp_client_tasks.py tests_integ/mcp/test_mcp_output_schema.py tests_integ/mcp/test_mcp_resources.py	12 passed (real stdio MCP server round-trips)
E2E new path vs tests_integ/mcp/echo_server.py	python demo_new_path.py	0 DeprecationWarnings, tools called
E2E legacy path vs tests_integ/mcp/echo_server.py	python demo_backcompat.py	1 DeprecationWarning at import, identity holds, submodule imports resolve
Agent + MCP integration (new path, non-Bedrock model via API key)	ad-hoc smoke script	✅ agent invoked echo tool, returned expected string
Agent + MCP integration (legacy path, non-Bedrock model via API key)	ad-hoc smoke script	✅ same flow, 1 DeprecationWarning at import

Notes for reviewers

• test_deprecated_aliases.py is deliberately placed under tests/strands/tools/mcp/ (the legacy location) so it lives alongside the alias it tests. It will move/disappear when the alias is removed in a future release.
• test_canonical_import_path.py lives under the canonical tests/strands/mcp/ and locks in the identity contract from the canonical direction.
• Agent-based integration tests (test_mcp_client.py, test_mcp_client_structured_content_and_metadata.py, test_mcp_elicitation.py, test_mcp_tool_provider.py) require Bedrock credentials and were not run locally. They're covered by the maintainer CI's STRANDS_INTEG_TEST_ROLE. The ad-hoc Agent+MCP smoke tests above use a non-Bedrock model provider via API key to exercise the same code path.

Closes #1431