tamash-wmcp — MCP Server for AI Web Agents

Connects AI IDEs (VS Code Copilot, Cursor, Claude Desktop) to any live Chrome tab via the Model Context Protocol. No Playwright. No selectors. No test code.

Requires the Tamash Chrome extension — install from the Chrome Web Store.

What it does

Tamash is a Chrome extension + MCP server that bridges any web page to AI tools like VS Code Copilot, Cursor, and Claude Desktop.

It automatically reads the page and creates tools the AI can call:

Open any website in Chrome
        ↓
Tamash scans the page automatically
        ↓
AI IDE discovers tools like:
  [WebMCP] search_products { query }
  [WebMCP] add_item_to_cart { itemName, quantity }
  [WebMCP] place_order
  click_submit_button
        ↓
AI executes them on the live page

No code written. No selectors. No configuration per site.

Features

• Works on any website — tools are generated live from the page, not hardcoded
• WebMCP-first — automatically discovers and uses app-declared tools before falling back to DOM scanning
• Live tool updates — tools refresh automatically as the page changes (SPAs, modals, navigation)
• Smart idle detection — waits for DOM, network, and spinners before returning results
• Works with all AI IDEs — VS Code Copilot, Cursor, Claude Desktop, any MCP-compatible client
• Session memory — every tool call is logged to .tamash/memory/ for debugging and reporting

Tool Priority — WebMCP First, DOM as Fallback

Step 1 — Always start with get_webmcp_tools

WebMCP tools are declared by the web application itself. They are semantic, reliable, and app-aware.

get_webmcp_tools()

Example response:

[
  { "name": "user_register",    "description": "[WebMCP] Register a new user account",    "params": ["username", "password", "email"] },
  { "name": "user_login",       "description": "[WebMCP] Log in with credentials",         "params": ["username", "password"] },
  { "name": "search_products",  "description": "[WebMCP] Search products by name",         "params": ["query"] },
  { "name": "add_item_to_cart", "description": "[WebMCP] Add a product to the cart",       "params": ["itemName", "quantity"] },
  { "name": "get_cart_contents","description": "[WebMCP] Return the current cart contents","params": [] },
  { "name": "place_order",      "description": "[WebMCP] Place the current cart order",    "params": [] }
]

If get_webmcp_tools returns tools → use them. Stop here. Do not call get_dom_tools.

Step 2 — Call WebMCP tools

Use call_webmcp_tool for individual actions, run_scenario for multi-step sequences.

Syntax:

call_webmcp_tool { toolName: "<name>", params: { <key>: <value>, ... } }

Examples:

call_webmcp_tool { toolName: "user_register",    params: { "username": "alice", "password": "secret123", "email": "[email protected]" } }
call_webmcp_tool { toolName: "user_login",       params: { "username": "alice", "password": "secret123" } }
call_webmcp_tool { toolName: "search_products",  params: { "query": "carrot" } }
call_webmcp_tool { toolName: "add_item_to_cart", params: { "itemName": "Broccoli", "quantity": 2 } }
call_webmcp_tool { toolName: "get_cart_contents",params: {} }
call_webmcp_tool { toolName: "place_order",      params: {} }

Rules for params:

• Pass params as a plain JSON object — { "key": "value" }.
• Do not pre-stringify params (e.g. do not pass "{ \"key\": \"value\" }").
• The extension handles serialisation internally.
• Omit params entirely (or pass {}) for tools that take no arguments.

Step 3 — DOM tools only as fallback

Only call get_dom_tools / call_dom_tool if:

1. get_webmcp_tools returned an empty list, and
2. The user explicitly asked to use DOM tools.

Never fall back to DOM tools just because a step is easier to express as a click — if a WebMCP tool covers the action, use it.

How to discover DOM tools:

get_dom_tools()

Example response:

[
  { "name": "fill_username",  "description": "Fill the username input field", "params": ["value"] },
  { "name": "fill_password",  "description": "Fill the password input field", "params": ["value"] },
  { "name": "click_login",    "description": "Click the Login button",        "params": [] },
  { "name": "navigate_home",  "description": "Navigate to the Home page",     "params": [] }
]

Syntax:

call_dom_tool { toolName: "<name>", params: { <key>: <value>, ... } }

Examples:

call_dom_tool { toolName: "fill_username", params: { "value": "admin" } }
call_dom_tool { toolName: "fill_password", params: { "value": "admin123" } }
call_dom_tool { toolName: "click_login",   params: {} }

Standard Workflow

1. get_webmcp_tools()
      ↓ tools found?
   YES → call_webmcp_tool / run_scenario with WebMCP tools
      ↓ tools empty AND user asked for DOM?
   NO  → get_dom_tools() → call_dom_tool / run_scenario with DOM tools

2. After actions: get_page_state() to verify result

3. On navigation: get_webmcp_tools() again on the new page

Multi-step example (run_scenario)

run_scenario {
  steps: [
    { toolName: "user_login",       params: { "username": "admin", "password": "admin123" } },
    { toolName: "search_products",  params: { "query": "broccoli" } },
    { toolName: "add_item_to_cart", params: { "itemName": "Broccoli", "quantity": 1 } },
    { toolName: "place_order",      params: {} }
  ]
}

run_scenario handles page navigation automatically — tools from different pages can be mixed in one call.

Quick start

1. Install the Chrome extension

Install Tamash from the Chrome Web Store.

2. Connect your AI IDE

VS Code Copilot — add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "tamash": {
      "command": "npx",
      "args": ["tamash-wmcp"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "tamash": {
      "command": "npx",
      "args": ["tamash-wmcp"]
    }
  }
}

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "tamash": {
      "command": "npx",
      "args": ["tamash-wmcp"]
    }
  }
}

3. Start testing

Open https://vibetestq.com/testweb/vegcart/ in Chrome, then ask your AI:

What WebMCP tools are available?
Search for carrots using WebMCP
Add Broccoli to cart
Get the full product list
Place the order

Documentation

| Guide | Audience | Description | |---|---|---| | User Guide | QA testers, developers, agents | Practical patterns, real app examples, troubleshooting | | How to Use | All users | Complete tool reference with examples | | Testing Guide | QA testers, developers | Writing and debugging test scenarios | | API Architecture | Developers | System design, communication flow | | API MCP Tools | Developers | Full MCP server tool specifications | | API Extension Tools | Developers | Extension content-script tool specs | | API Internals | Developers | BrowserClient, session memory, push events |

Development

Running from source

git clone https://github.com/tamashwm/tamash-mcp
cd tamash-mcp
npm install
npm run mcp        # start MCP server

Running tests

npm run smoke      # smoke tests (requires Chrome + extension)
npm run e2e        # full end-to-end tests

Custom port

# Start server on port 10000
WMCP_PORT=10000 npm run mcp

Update your IDE config to add "env": { "WMCP_PORT": "10000" }.

Extension source

The Chrome extension source lives in the companion repository tamash-extension. After modifying extension source:

1. Run npm run dev in tamash-extension/
2. Reload the extension at chrome://extensions
3. Reload the active Chrome tab

MCP Tools Reference

| Tool | Purpose | When to Use | |---|---|---| | get_webmcp_tools | List WebMCP tools declared by the page | Always call this first | | get_dom_tools | List auto-generated DOM tools | Only if no WebMCP tools | | call_webmcp_tool | Execute one WebMCP tool | Individual WebMCP actions | | call_dom_tool | Execute one DOM tool | Individual DOM actions (fallback) | | call_page_tool | Execute read-only tools | Data queries: get_cart_contents, getState, getFormData, list_frames | | run_scenario | Execute a multi-step sequence | Any action sequence — handles navigation | | run_page_tools | Execute multiple tools on the same page | Batch actions without navigation | | get_page_state | Get current page URL, auth, errors | After actions to verify outcome | | query_elements | Find elements by ARIA role + label | Fast element discovery and verification | | get_element_state | Get live state of a single element | Cheapest post-action verification | | get_form_data | Read all form field values at once | Verify form state without per-field calls | | set_dialog_answer | Pre-configure confirm()/prompt() answer | Before any action that triggers a JS dialog | | list_frames | List all iframes on the page | Before inspecting iframe content | | get_frame_snapshot | Accessibility tree inside an iframe | Testing embedded iframes | | get_page_tools | List all tools (deprecated) | Legacy — use get_webmcp_tools instead | | get_skill_context | Get workflow guidance | When unsure how to proceed | | analyze_page | Deep accessibility tree | Last resort for unlabelled custom widgets |

WebMCP Support

Tamash detects tools declared by websites using Chrome's official WebMCP API. When a site registers tools via navigator.modelContext.registerTool(), Tamash automatically exposes them to your AI IDE — tagged [WebMCP] so you know they're native.

The webmcp-bridge.js content script provides fallback support for when the Chrome flag is not enabled — tools registered via navigator.modelContext are intercepted and forwarded through the same pipeline.

Chrome flag (optional — improves reliability):

chrome://flags/#webmcp-for-testing → Enabled   (Chrome 146+)

Troubleshooting

| Symptom | Fix | |---|---| | "Not connected to browser extension" | Make sure Chrome is open with the Tamash extension installed and a tab is active | | Tools list is empty | Reload the tab — Tamash may not have scanned the page yet | | WebMCP tools not appearing | Enable chrome://flags/#webmcp-for-testing (Chrome 146+) | | Tool call times out | Page may be slow; try reloading and retrying | | Extension not working | Check chrome://extensions → Errors on the Tamash card | | Tool receiving wrong params | Ensure params are a plain object — do not JSON.stringify before passing | | confirm() dialog not handled | Call set_dialog_answer before the action that triggers the dialog | | pick_* tool not found | The dropdown is not open — call the related fill_* first, then re-fetch get_dom_tools | | Frame content inaccessible | Check list_frames — cross-origin frames cannot be read due to browser security policy | | get_form_data returns "No visible form found" | The form may be hidden or inside an iframe — use get_frame_snapshot first |

Further Reading

• How to Use Guide — step-by-step walkthroughs for every tool
• Testing Guide — how to write and run tests with this MCP

License

Free to use. All rights reserved. Source code is proprietary and may not be copied, modified, or redistributed.