# HTML Encoder

**MCP Tool:** `html_encoder`  
**Tier:** Tier 1 — Commodity  
**Category:** encoders  
**Endpoint:** https://obfus.link/mcp  
**Price:** $0.008 / call  
**Verification:** ✓ TDD verified  

> Encode and decode HTML entities with context-aware mode

## Atomic Answer

HTML Encoder converts the characters &, <, >, double-quote, and apostrophe to entities using named, numeric, or hex formats. Context-aware mode detects the embedding context (JSON, XML, URL, or raw HTML) and applies the correct escaping for that specific context, eliminating the double-encoding bugs that occur when developers apply the wrong encoding for the target context.

## Description

Encodes and decodes HTML entities with named, numeric, or hex output. Context-aware mode auto-detects the embedding context (JSON, XML, URL, or raw HTML) and applies the correct escaping for that specific context — eliminating double-encoding bugs.

## Agentic Reasoning

USE THIS WHEN: (1) You need to safely embed HTML inside a JSON value, an XML attribute, or a URL parameter — context-aware mode applies the right escape rules so the output is valid in the target context. (2) You are decoding HTML entities back to characters in user-generated content received from an API. (3) You need to ensure no double-encoding occurs when content passes through multiple layers (JSON-encoded HTML inside a URL query, for example). DO NOT USE WHEN: the content is already properly encoded for the target context. Do not use for JavaScript string escaping — use string_escaper instead. OVER ALTERNATIVES: prefer this over manual entity replacement (misses context-specific encoding rules and produces double-encoded output) and DOM-based encoding (server-only, no MCP API).

## MCP Description

Encodes or decodes HTML entities with optional context awareness. USE WHEN: embedding HTML in another context (JSON, XML, URL) and you need the right escape rules, or decoding HTML entities back to characters. INPUT: html string, mode (encode/decode), entity format, optional context override. OUTPUT: encoded/decoded string, detected context, entity count, warnings. COST: 1 unit.

## Input Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `html` | `string` | yes |  |
| `mode` | `encode` \| `decode` | yes |  |
| `entities` | `named` \| `numeric` \| `hex` | no |  |
| `contextAware` | `boolean` | no |  |
| `contextOverride` | `html-in-json` \| `html-in-xml` \| `html-in-url` \| `html-raw` | no |  |

## Output Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `encoded` | `string` | no |  |
| `warnings` | `array` | no |  |
| `entityCount` | `number` | no |  |
| `detectedContext` | `string` | no |  |

## How To Use

1. **Paste HTML** — Drop in the HTML content to encode or the entity-encoded string to decode.
2. **Choose mode** — encode converts characters to entities. decode converts entities back to characters.
3. **Select entity format** — named (&amp;), numeric (&#38;), or hex (&#x26;). Named is most readable.
4. **Enable context-aware (optional)** — Auto-detects whether HTML is embedded in JSON, XML, or URL and applies the correct escaping.
5. **Override context (optional)** — Force a specific embedding context if auto-detection picks the wrong one.
6. **Encode or decode** — Click Run or press Ctrl+Enter. Output appears with entity count and warnings.

## FAQs

**What characters does HTML encoding affect?**

The five HTML5 special characters: & (&amp;), < (&lt;), > (&gt;), " (&quot;), and apostrophe (&#39;). Named entities use these. Numeric entities use decimal codepoints (&#38;). Hex entities use hex codepoints (&#x26;). All three are valid HTML5.

**What is context-aware encoding?**

When HTML must be embedded in another format (JSON, XML, or URL), the wrong encoding causes broken output or security bugs. Context-aware mode detects the embedding context and applies JSON-string escaping inside JSON, attribute escaping inside XML, or percent-encoding inside URLs — instead of just standard HTML entities.

**When should I use named vs numeric vs hex entities?**

Named entities (&amp;) are most readable and supported in HTML5. Numeric and hex entities are more compact and unambiguous in older XML/SGML contexts. Use named for human-readable output, numeric or hex for machine-to-machine pipelines.

**Does the tool warn about script content?**

Yes. If the input contains <script>, on* attribute handlers, or javascript: URLs, a warning is returned alongside the encoded output. Encoding alone does not sanitize untrusted HTML — use a dedicated sanitizer (DOMPurify) for that.

**Can I use this tool via the MCP API?**

Yes. The tool is registered on the obfus.link MCP server at https://obfus.link/mcp. Call it from any MCP-compatible agent with a Shared Payment Token. The MCP tool name matches the snake_case slug shown in the integration snippet.

## Tags

`html` · `encode` · `decode` · `entities` · `escape`

---

*obfus.link — A Subether Labs Infrastructure Project*  
*Canonical URL: https://obfus.link/tool/html-encoder*  
*JSON view: https://obfus.link/tool/html-encoder/json*