Metadata-Version: 2.4
Name: kl-mcp-client
Version: 2.1.19
Summary: MCP Client for Python
Author-email: Kyle <hngan.it@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.5
Requires-Dist: httpx>=0.28.1

# kl-mcp-client

SDK Python để gọi MCP Browser Server qua JSON-RPC HTTP.

## Cài đặt

```bash
pip install kl-mcp-client
```

## Thành phần

- `kl_mcp_client.client.MCPClient`: sync JSON-RPC client
- `kl_mcp_client.tools.MCPTools`: sync tools wrapper
- `kl_mcp_client.asyncio.client.MCPClient`: async JSON-RPC client
- `kl_mcp_client.asyncio.tools.MCPTools`: async tools wrapper

## Quickstart (sync)

```python
from kl_mcp_client.tools import MCPTools

tools = MCPTools()
tools.connect_mcp("http://localhost:3000/mcp")

sid = tools.create_session("http://localhost:9222")['sessionId']
tools.open_page(sid, "https://example.com")
print(tools.get_html(sid))
```

## Quickstart (async)

```python
import asyncio
from kl_mcp_client.asyncio.tools import MCPTools

async def main():
    tools = MCPTools()
    tools.connect_mcp("http://localhost:3000/mcp")

    sid = (await tools.create_session("http://localhost:9222"))["sessionId"]
    await tools.open_page(sid, "https://example.com")
    print(await tools.get_html(sid))
    await tools.close()

asyncio.run(main())
```

## Danh sách function (sync `kl_mcp_client.tools.MCPTools`)

### Kết nối / core
- `connect_mcp(mcp_url=None, mcpUrl=None, headers=None, timeout=30, retries=2, proxies=None)`
- `close()`

### Session tools
- `create_session(cdpUrl)`
- `close_session(sessionId)`
- `list_sessions()`
- `open_page(sessionId, url)`
- `get_html(sessionId)`
- `click(sessionId, selector)`
- `get_bounding_box(sessionId, selector)`
- `click_to_text(sessionId, text)`
- `click_by_node_id(sessionId, nodeId)`
- `screenshot(sessionId)`
- `import_cookies(sessionId, cookies)`
- `click_bounding_box(sessionId, selector)`
- `upload_file(sessionId, selector, file_path)`
- `perform(sessionId, action, target=None, value=None, x=None, y=None, from_point=None, to_point=None)`
- `wait_for_selector(sessionId, selector, timeout=None, timeoutMs=None)`
- `scroll(sessionId, x=None, y=None, selector=None, position=None)`
- `evaluate(sessionId, expression)`
- `evaluate_stream(sessionId, expression, chunkSize=100)`
- `stream_pull(stream_id, offset=0, limit=100)`
- `get_cookies(sessionId)`
- `parse_html_by_prompt(html, prompt)`
- `viewport(sessionId, viewport=None)`

### Input tools
- `send_keys(sessionId, text, interval=None)`
- `type(sessionId, selector, text)`
- `send_text(sessionId, text, interval=None)`
- `clear_all(sessionId)`
- `send_combo(sessionId, text)`

### Tab tools
- `get_current_url(sessionId)`
- `list_tabs(sessionId)`
- `switch_tab(sessionId, tabId=None, targetId=None)`
- `close_tab(sessionId, tabId)`
- `new_tab(sessionId, url=None)`
- `switch_tab_by_title(sessionId, title)`
- `switch_tab_by_url(sessionId, url)`
- `current_tab(sessionId)`

### DOM tools
- `get_dom_tree(sessionId)`
- `get_clickable(sessionId)`
- `selector_map(sessionId, selector)`
- `get_clean_text(sessionId)`

### Element tools
- `find_all(sessionId, selector)`
- `find_element(sessionId, selector)`
- `find_element_by_xpath(sessionId, xpath)`
- `find_element_xpath(sessionId, xpath)`
- `find_element_by_text(sessionId, text)`
- `find_element_by_prompt(sessionId, prompt)`

### Browser tools
- `create_browser(payload=None)`
- `release_browser(pod_name)`

### Helper / tương thích ngược
- `cookies(sessionId)`
- `current_url(sessionId)`
- `set_viewport(sessionId, width, height, deviceScaleFactor=1.0, mobile=False)`
- `get_viewport(sessionId)`
- `drag_and_drop(sessionId, from_x, from_y, to_x, to_y)`
- `hover(sessionId, x, y)`
- `evaluate_stream_all(sessionId, expression, chunkSize=100, max_items=None)`

## Danh sách function async

`kl_mcp_client.asyncio.tools.MCPTools` hỗ trợ cùng API như bản sync, nhưng gọi bằng `await`.

## Lưu ý

- Cần gọi `connect_mcp(...)` trước khi gọi tools.
- `upload_file(...)` dùng endpoint `/upload` để lấy `uploadId`, sau đó gọi tool `uploadFile`.
- Tool name map theo server tại `mcp-server/internal/interfaces/http/mcp`.
