Browser-Use MCP Server

# Session Handoff: Implement Integration Tests ## 1. Primary Request and Intent The user requested a comprehensive improvement of the mcp-browser-use repository: 1. **Documentation Overhaul** (COMPLETE): Fixed contradictions in README files, aligned documentation with actual code behavior 2. **Security Improvements** (COMPLETE): Added CDP connection support, header redaction, SSRF blocking, auth token support 3. **Task Management** (COMPLETE): Implemented task_cancel MCP tool with cancellation support 4. **Project Setup** (COMPLETE): Adopted fastmcp-style configuration with AGENTS.md, justfile, pre-commit hooks 5. **Integration Tests** (NEXT STEP): Create integration tests for each MCP tool following fastmcp patterns ## 2. Key Technical Concepts - **FastMCP**: The MCP framework used - `@server.tool()` decorators, `Client` for testing - **MCP Tools**: run_browser_agent, run_deep_research, skill_*, health_check, task_* - **HTTP Transport**: Server runs HTTP-only on port 8383 (stdio deprecated) - **Task Registry**: Global `_running_tasks: Dict[str, asyncio.Task]` for cancellation - **Pydantic Settings**: Configuration via `pydantic_settings` with env var prefixes - **pytest-asyncio**: `asyncio_mode = "auto"` configured globally - **Test Markers**: `e2e`, `integration`, `slow` defined in pyproject.toml ## 3. Files and Code Sections ### src/mcp_server_browser_use/server.py **Why important**: Contains all 9 MCP tools that need integration tests ```python # Tools to test: @server.tool() async def run_browser_agent(task: str, ...) -> str # 60-120s @server.tool() async def run_deep_research(topic: str, ...) -> str # 2-5 min @server.tool() async def skill_list() -> str # <1s @server.tool() async def skill_get(name: str) -> str # <1s @server.tool() async def skill_delete(name: str) -> str # <1s @server.tool() async def health_check() -> str # <1s @server.tool() async def task_list(...) -> str # <1s @server.tool() async def task_get(task_id: str) -> str # <1s @server.tool() async def task_cancel(task_id: str) -> str # NEW, <1s ``` ### tests/test_mcp_tools.py (EXISTING - Reference for patterns) **Why important**: Shows current testing pattern with FastMCP Client ```python from fastmcp import Client @pytest.fixture async def client(): """Create a test client connected to the server.""" server = create_server() async with Client(server) as client: yield client class TestListTools: @pytest.mark.anyio async def test_list_tools(self, client: Client): tools = await client.list_tools() tool_names = [tool.name for tool in tools] assert "run_browser_agent" in tool_names assert "task_cancel" in tool_names assert len(tool_names) == 9 ``` ### pyproject.toml (Test Configuration) ```toml [tool.pytest.ini_options] asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" testpaths = ["tests"] timeout = 120 markers = [ "e2e: End-to-end tests requiring real API keys and browser", "integration: Integration tests with mocked LLM but real browser automation", "slow: Tests that take longer to run", ] ``` ### FastMCP Integration Test Patterns (Reference) From the user-provided fastmcp examples: ```python # tests/integration_tests/conftest.py pattern @pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): """Convert rate limit failures to skips for integration tests.""" outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: if _is_rate_limit_error(call.excinfo, report): report.outcome = "skipped" # tests/integration_tests/test_*.py pattern pytestmark = pytest.mark.xfail( not API_KEY, reason="API key not set", ) @pytest.fixture async def client(): return Client(StreamableHttpTransport(url=SERVER_URL)) async def test_list_tools(self, client): async with client: tools = await client.list_tools() assert isinstance(tools, list) ``` ## 4. Problem Solving (Completed This Session) - Fixed port mismatch (README said 8000, code uses 8383) - Fixed broken uvx install (changed to `uv sync --dev`) - Implemented missing cdp_url and auth_token config options - Added task_cancel MCP tool with task registry - Enabled pre-commit hooks with appropriate ignores for Typer patterns - All existing tests pass ## 5. Next Step: Create Integration Tests Create integration tests folder structure and tests for each MCP tool: ### Structure to Create: ``` tests/ ├── integration_tests/ │ ├── __init__.py │ ├── conftest.py # Shared fixtures, markers │ ├── test_health.py # health_check tests │ ├── test_tasks.py # task_list, task_get, task_cancel tests │ ├── test_skills.py # skill_list, skill_get, skill_delete tests │ └── test_browser.py # run_browser_agent, run_deep_research (e2e) ``` ### Tests to Implement: 1. **test_health.py** (fast, no external deps): - `test_health_check_returns_status` - `test_health_check_includes_uptime` 2. **test_tasks.py** (fast, no external deps): - `test_task_list_empty` - `test_task_list_with_filter` - `test_task_get_not_found` - `test_task_cancel_not_running` 3. **test_skills.py** (fast, uses fixture skills): - `test_skill_list_empty` - `test_skill_list_with_skills` - `test_skill_get_existing` - `test_skill_get_not_found` - `test_skill_delete_existing` 4. **test_browser.py** (slow, e2e, requires API key): - `test_run_browser_agent_simple_task` - `test_run_browser_agent_with_max_steps` - `test_run_deep_research_basic` ### Key Fixtures to Create: ```python @pytest.fixture async def mcp_client(): """In-memory client for fast tests.""" from mcp_server_browser_use.server import create_server server = create_server() async with Client(server) as client: yield client @pytest.fixture def temp_skills_dir(tmp_path): """Temporary skills directory for isolation.""" skills_dir = tmp_path / "browser-skills" skills_dir.mkdir() return skills_dir ``` ### Commands to Run Tests: ```bash # Fast integration tests only uv run pytest tests/integration_tests -m "not e2e" # All integration tests (requires API key) uv run pytest tests/integration_tests # Specific test file uv run pytest tests/integration_tests/test_health.py -v ```