web-agent-protocol

Web Agent Protocol (WAP) provides a workflow to record browser interactions, convert them into replay-ready lists, and then expose those lists as MCP servers for reuse by agents. This repository demonstrates a Python-based MCP workflow that starts with data collection from the WAP Chrome extension, then converts the captured actions into MCP-ready formats, and finally enables replay via a dedicated MCP server. Once generated, you can run the MCP server locally, connect with the MCP client, and prompt the system to execute browser actions through the WAP Replay protocol. Tools involved include the WAP data-collection server (action_collect_server.py), WAP replay utilities, and the python-based MCP server generator and runner (wap_service.py, mcp_client.py, and generate_mcp_server.py).

Prerequisites:

• Python 3.11 (recommended by the WAP setup) or a compatible Python environment
• Optional: Conda for creating isolated environments
• Internet access to install dependencies from requirements.txt

Step-by-step:

1. Clone the repository or download the project files.
2. Create a dedicated environment (optional but recommended):
   • Conda: conda create -n wap python=3.11
   • Then activate: conda activate wap
3. Install Python dependencies:
   • pip install -r requirements.txt
4. Set up environment variables (example):
   • OPENAI_API_KEY=sk-...
   • DEEPSEEK_API_KEY=sk-...
   • (Optional) PYTHONPATH may be needed to point to the project root on some systems:
     • Windows: set PYTHONPATH=C:/path/to/webagentprotocol
     • Linux/macOS: export PYTHONPATH=/path/to/webagentprotocol
5. Start the data collection server (for WAP):
   • python action_collect_server.py
6. Generate MCP server from a task after recording:
   • python wap_replay\generate_mcp_server.py --task_id <task_id>
   • The generated MCP server artifacts will appear under the mcp_servers folder.
7. Run the MCP server to enable replay via MCP clients:
   • python wap_service.py
   • In a second terminal: python mcp_client.py
   • Then provide your natural language prompt to drive the replay (example: find a top rated keyboard on amazon.ca using smart replay).

Notes:

• Ensure the extension is recording a full session and that task-start/task-finish records exist for MCP generation.
• The default data sink for recordings is data/YYYYMMDD/taskid/summary_event_<timestamp>.json.
• The WAP server and MCP flow rely on OpenAI and other API keys; keep them secure and never hard-code in production.

Tips and common issues:

• If you encounter ModuleNotFoundError, run commands from the project root or export PYTHONPATH=.
• When running the MCP server locally, ensure the host/port in the WAP extension settings matches where wap_service.py is listening (default http://localhost:4934/action-data for data collection).
• If the extension reports no task-start file, re-record a complete session; the MCP generation requires exactly one task-start and one task-finish record.
• For Windows users, pay attention to path separators in scripts like generate_mcp_server.py (use the provided backslash notation in commands when shown).
• The MCP workflow integrates with the WAP Replay tool and desktop app for convenience; consider using those GUI options for easier operation once the CLI path is stable.