# KAGE MCP — Lightweight HTML Parsing for AI Agents

**kage-mcp** is a JSON-RPC MCP server that parses HTML, fetches URLs, renders terminal-style screenshots, and executes JavaScript on static HTML. It is packaged as a single 92MB executable — no Python, no Node.js, no browser required.

## Quick Start

### Install

```bash
pip install kage-mcp
```

Or download `kage-mcp.exe` from [GitHub Releases](https://github.com/lxyct825-ops/kage-mcp/releases).

### Run

```bash
kage-mcp
```

Then configure in your MCP client (Cline, Claude Desktop, etc.):

```json
{
  "mcpServers": {
    "kage": {
      "command": "kage-mcp",
      "args": []
    }
  }
}
```

### Manual Test

```bash
# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | kage-mcp

# Parse HTML
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kage_parse_html","arguments":{"html":"<h1>Hello</h1>","selector":"h1"}}}' | kage-mcp

# Fetch URL
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"kage_fetch_url","arguments":{"url":"https://example.com","selector":"h1"}}}' | kage-mcp
```

## Tools

| Tool | Description |
|---|---|
| `kage_parse_html` | Parse an HTML string and extract structured data |
| `kage_fetch_url` | Fetch a URL and extract structured data from the response |
| `kage_render` | Render HTML to a terminal-style PNG image (green-on-black monospace) |
| `kage_execute_js` | Execute JavaScript code against a DOM context and return the result |

## Limitations

KAGE is an **HTML parsing engine**, not a full browser:

- ❌ Does **not** execute external JavaScript from `<script src="...">` tags
- ❌ Does **not** render SPAs (React, Vue, Angular)
- ❌ Screenshot output is terminal-style (green-on-black monospace), not pixel-perfect
- ❌ No WebSocket / WebGL / Canvas support
- ❌ Fetch is HTTP-only (no HTTPS cert validation bypass)

What it **can** do:

- ✅ Parse any HTML string into structured JSON
- ✅ Fetch URLs and extract content via CSS selectors
- ✅ Execute inline JS on a parsed DOM (no network requests)
- ✅ Works as a drop-in MCP server — no extra dependencies

## Requirements

- Windows 10+ (64-bit)
- No Python, Node.js, or browser needed

## License

MIT