# Markdown Utilities Engine MCP

> Markdown Utilities Engine gives your AI client dedicated tools for structuring complex documents. It takes raw JSON data and outputs perfectly formatted Markdown tables, eliminating broken columns and misaligned rows. Need a Table of Contents? Use generate_toc to parse massive text blocks and automatically create nested, GitHub-style anchor links.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** markdown, json-parsing, table-generation, toc-generator, data-formatting, v8-engine

## Description

Listen, when you're dealing with complex documentation—the kind that needs perfect structure like a massive README or a technical spec—you know the drill. Just asking your AI client to spit out nested tables or a proper table of contents is risky business. General-purpose models struggle with maintaining structural integrity over long passages; they often mess up pipes, misalign columns, or generate broken link slugs. This engine fixes that by giving your agent dedicated tools. You don't have to rely on the model just guessing how markdown should look; you use a specialized engine that guarantees clean output every time.

When you need to turn raw data into something readable—like turning an array of structured records into a slick, professional-looking table—you run `generate_table_from_json`. You feed it a standard JSON array containing objects. This tool doesn't just approximate the structure; it converts that entire JSON payload into perfectly formatted Markdown tables. It automatically identifies all the required headers and correctly builds the row separators and column dividers, so you never gotta worry about broken pipes (`|`) or data getting misaligned across multiple rows. Think of it like having a specialized formatter: give it structured input, and it spits out rock-solid markdown that looks good right out of the gate.

If your documentation is huge—the kind where scrolling through 50 pages feels impossible—you need a Table of Contents, and you need it to actually work. That’s where `generate_toc` comes in. You drop in massive blocks of raw Markdown text, and this tool scans every single character. It detects all the header levels, whether they're H1 or H3, and then generates a complete, nested Table of Contents (TOC). Crucially, it doesn't just list titles; it creates mathematically accurate link slugs for *every* detected header. This means when you click an entry in that generated TOC, your agent knows exactly where to jump in the document, giving you proper GitHub-style navigation right out of the box. The tool handles the parsing and linking simultaneously, meaning you get a cohesive index pointing directly to every section.

Using these tools lets you separate data structuring from language processing. Your AI client uses `generate_table_from_json` purely for formatting utility: take JSON, give clean markdown table output. It runs independently of general chat logic, making the result predictable and reliable. Similarly, when you need a navigable index, running `generate_toc` ensures that all those links are correctly slugged and nested, which is something models often botch up in simple conversational outputs. You're not just formatting; you’re enforcing strict structural standards across your entire document set. It gives the agent highly reliable methods for converting structured JSON data into clean Markdown tables, and it also provides a mechanism to scan raw text blocks and generate nested lists of links that point precisely to every header slug detected. This separation means your workflow is faster, cleaner, and much less prone to formatting errors you'd normally spend hours fixing with manual cleanup.

## Tools

### generate_table_from_json
Converts a JSON array of objects into a perfectly formatted Markdown table, automatically extracting headers and rows.

### generate_toc
Parses raw Markdown text and generates a nested Table of Contents (TOC) with linked bullet points pointing to all header slugs.

## Prompt Examples

**Prompt:** 
```
Create a Table of Contents for this massive README text I pasted below.
```

**Response:** 
```
Using the generate_toc tool: 
- [Introduction](#introduction)
  - [Features](#features)
- [Deployment](#deployment)
```

**Prompt:** 
```
Here is the raw database output JSON: `[{"id": 1, "name": "John", "role": "Admin"}, {"id": 2, "name": "Jane", "role": "User"}]`. Convert this into a Markdown table.
```

**Response:** 
```
Using the generate_table_from_json tool:
| id | name | role |
|---|---|---|
| 1 | John | Admin |
| 2 | Jane | User |
```

## Capabilities

### Format JSON to Markdown Tables
Converts an array of structured JSON data into a clean, readable Markdown table.

### Generate Linked Table of Contents (TOC)
Scans raw Markdown text and outputs a nested list of links pointing to every detected header slug.

## Use Cases

### Documenting API Responses
A developer has run a script that returns hundreds of records in JSON format. Instead of pasting this messy dump into the documentation, they ask their agent to use `generate_table_from_json`. The agent immediately converts it into a clean Markdown table ready for publication.

### Updating a Massive README
The content team finished a 50-page technical manual and dumped the raw markdown text. They run `generate_toc` on the document. The agent returns a perfectly nested, linked Table of Contents that guides users through all sections without any broken links.

### Creating Comparison Guides
A product manager needs to compare features across three versions (JSON data). They pass the JSON array and use `generate_table_from_json`. The agent builds a comparison table instantly, saving hours of manual markdown alignment.

### Structuring Meeting Notes
Someone pastes raw meeting notes with lots of headers. They ask the agent to run `generate_toc`. The tool returns an index that lets readers jump straight to 'Action Items' or 'Next Steps,' making the document highly navigable.

## Benefits

- Perfect Tables, Every Time: Stop dealing with broken pipes (`|`) or misaligned data columns. `generate_table_from_json` guarantees a clean Markdown table from any JSON structure.
- Accurate Navigation: Don't waste time manually linking headers. Run your huge documents through `generate_toc`, and it builds a nested, linked Table of Contents that works in GitHub or Readme files.
- Local & Private: Your proprietary internal documentation never leaves your machine. This utility runs 100% locally, keeping all your data secure.
- Zero-Latency Performance: The formatting happens instantly. You get immediate response times for rendering massive blocks of structured content.
- Consistency Check: It removes the guesswork from markdown. Whether it’s a table or an index, the output adheres to strict structural rules you can count on.

## How It Works

The bottom line is: you get reliable, structured output regardless of how complex your source data or document is.

1. First, you pass the tool (e.g., `generate_table_from_json`) and your structured input data (the JSON array) to your AI client.
2. The MCP Server executes the precise JavaScript utility locally, bypassing the LLM's general formatting limitations.
3. Your agent receives a clean, fully formatted Markdown block ready for immediate use in documentation or reports.

## Frequently Asked Questions

**Does generate_table_from_json handle missing keys?**
Yes, it handles schema variance by using all available headers from the input JSON and filling in null or empty cells for records that lack data for specific columns. This keeps your table structure intact even if some rows are incomplete.

**Can generate_toc handle mixed header levels?**
Absolutely. It parses nested headers (H1, H2, H3, etc.) and accurately generates a corresponding nested list in the Table of Contents using indentation, reflecting the true hierarchy of your document.

**Is Markdown Utilities Engine local or cloud-based?**
The utility runs 100% locally on your machine. This means your proprietary source documents and data never leave your infrastructure. It's designed for private enterprise use.

**What kind of JSON can generate_table_from_json accept?**
It accepts a standard JSON array of objects, like `[{col1: 'A', col2: 1}, {col1: 'B', col2: 2}]`. The keys in the first object become your table headers.

**Is my internal documentation secure when using the Markdown Utilities Engine, or does it send data offsite?**
The engine runs 100% locally on your machine. Your proprietary documents never leave your infrastructure, guaranteeing privacy whether you're calling `generate_table_from_json` or `generate_toc`.

**How large of a dataset can I pass to generate_table_from_json without performance issues?**
It handles very large JSON arrays efficiently. The tool is designed for zero-latency execution, delivering perfectly aligned Markdown tables even when processing hundreds of rows.

**What happens if the raw markdown text I feed into generate_toc has formatting errors or incomplete syntax?**
The system doesn't fail on bad input. It scans the provided document and generates nested links based on detected header patterns, making it robust even if surrounding markdown is imperfect.

**Does using either tool require specific libraries or complex setup beyond connecting to Vinkius?**
No, you just connect your AI client via MCP. The utility handles the formatting engine internally; you don't need to worry about dependencies or complicated local setups.

**Why use an MCP for Markdown tables?**
When generating large Markdown tables, AI models commonly drop rows to save tokens or accidentally break the table structure by forgetting column separators. This MCP guarantees an absolutely perfect conversion from JSON.

**How does the TOC generator calculate URL slugs?**
It follows standard GitHub Flavored Markdown rules. It parses every Header (e.g. `### My Title`), strips special characters, replaces spaces with hyphens, and outputs `- [My Title](#my-title)` with accurate indentation.

**Does this tool send my internal documents to the cloud?**
No. The `markdown-utilities` engine executes completely locally using V8. Your proprietary documentation data is processed safely and privately.