CSV Import & Export

MCP tools for reading CSV files into the generation pipeline and exporting generated articles to CSV, Markdown, JSON, or HTML.

Available Tools

Tool Description
import_csv Read a local CSV file, auto-detect columns, preview data
export_csv Export articles to a CSV file
export_markdown Export articles as individual .md files with YAML frontmatter
export_json Export articles as structured JSON
export_bulk Multi-format export with advanced filtering

import_csv

Read a CSV file from your local machine and prepare rows for content generation. The tool scans headers against a built-in lookup table and matches them to canonical fields automatically.

Parameters

Parameter Type Default Description
file_path string required Absolute path to the CSV file
column_map object auto-detect Manual override mapping { canonical_field: "Your CSV Header" }
delimiter string , Delimiter character (,, ;, or \t)
encoding string utf-8 File encoding
skip_rows number 0 Rows to skip before column headers
max_rows number all Maximum rows to import
preview_only boolean false Preview first 5 rows without importing

Auto-Detected Columns

The tool recognizes many common header names:

Canonical Field Recognized Headers
keyword keyword, target_keyword, focus_keyword, kw, search_term, query, keyphrase
title title, post_title, h1, headline, article_title, page_title
meta_description meta, meta_description, meta_desc, description, seo_description
slug slug, url_slug, permalink, url, path, handle
category category, cat, section, topic, group
tone tone, voice, style, writing_style
word_count word_count, length, target_length, words
instructions instructions, notes, prompt_override, custom_prompt, context, brief
tags tags, keywords, labels, secondary_keywords
content content, body, article_content, body_html, html, markdown
status status, state, publish_status
author author, author_name, writer
date date, publish_date, created_at, published_date

Response Fields

Field Description
status success or error message
rows_found Total rows detected in the file
rows_imported Rows ready for generation (0 in preview mode)
columns_detected Which canonical fields were matched and how (auto vs manual)
unmapped_columns Headers that couldn't be matched to a canonical field
preview First 5 rows of mapped data
ready_for_generation true if a keyword column was found
rows Full row data (only in non-preview mode)

Example

{
  "tool": "import_csv",
  "arguments": {
    "file_path": "/Users/me/keywords.csv",
    "preview_only": true
  }
}

export_csv

Write articles to a CSV file on your local machine. You pass the articles inline as an array.

Parameters

Parameter Type Default Description
output_path string required Absolute file path for the CSV
articles array required Article objects (see Article Schema below)
columns string[] all standard Which columns to include
filter_status string all Filter: draft, published, or all
include_html boolean false Add an HTML content column
include_markdown boolean true Include Markdown content column

Example

{
  "tool": "export_csv",
  "arguments": {
    "output_path": "/Users/me/exports/articles.csv",
    "articles": [
      {
        "title": "Best Running Shoes 2026",
        "keyword": "best running shoes",
        "content": "# Best Running Shoes…",
        "word_count": 2400,
        "status": "draft"
      }
    ]
  }
}

export_markdown

Export each article as a separate .md file with YAML frontmatter containing title, keyword, slug, meta description, and other metadata.

Parameters

Parameter Type Default Description
output_dir string required Directory to write files to
articles array required Article objects
project_name string — Project name for frontmatter and folder structure
structure flat | nested flat flat = all in one folder, nested = project subfolder
filename_from slug | title | keyword slug Which field generates the filename
filter_status string all Filter: draft, published, or all

Output

Creates individual .md files plus a manifest.json listing all exported files.

Markdown File Format

---
title: "Best Running Shoes 2026"
slug: "best-running-shoes-2026"
keyword: "best running shoes"
meta_description: "Find the top running shoes of 2026…"
word_count: 2400
model: "gpt-4o"
status: "draft"
---

# Best Running Shoes 2026

Article content here…

export_json

Export articles as a single structured JSON file with metadata envelope.

Parameters

Parameter Type Default Description
output_path string required File path for JSON output
articles array required Article objects
project_name string — Project name for the metadata envelope
pretty boolean true Pretty-print the output
filter_status string all Filter: draft, published, or all

JSON Output Structure

{
  "exported_at": "2026-02-18T16:00:00.000Z",
  "project": "SEO Blog Posts",
  "total_articles": 10,
  "articles": [
    {
      "id": "art_001",
      "title": "Best Running Shoes 2026",
      "slug": "best-running-shoes-2026",
      "keyword": "best running shoes",
      "meta_description": "…",
      "content_markdown": "# Best Running Shoes…",
      "word_count": 2400,
      "model": "gpt-4o",
      "status": "draft",
      "category": "",
      "tags": [],
      "created_at": "",
      "research_citations": []
    }
  ]
}

export_bulk

A combined multi-format export with advanced filtering. Supports all four output formats (CSV, Markdown, JSON, HTML) and five filter dimensions.

Parameters

Parameter Type Default Description
format csv | markdown | json | html required Output format
output_path string required File path (csv/json/html) or directory (markdown)
articles array required Article objects
project_name string — Project name for metadata
structure flat | nested flat Folder structure (markdown only)
filter_status string all Filter: draft, published, or all
filter_model string any Filter by model name (partial match)
filter_date_from string — Start date YYYY-MM-DD
filter_date_to string — End date YYYY-MM-DD
filter_min_words number — Minimum word count
include_metadata boolean true Include frontmatter/headers
columns string[] all Columns to include (CSV format only)

Example

{
  "tool": "export_bulk",
  "arguments": {
    "format": "json",
    "output_path": "/Users/me/exports/batch.json",
    "project_name": "Q1 Blog Posts",
    "filter_status": "draft",
    "filter_min_words": 1500,
    "articles": []
  }
}

Article Schema

All export tools accept articles as an array of objects with these fields:

Field Type Required Description
title string yes Article title
content string yes Article body (Markdown or HTML)
slug string no URL slug
keyword string no Target keyword
meta_description string no SEO meta description
word_count number no Word count
model string no AI model used for generation
status string no draft or published (defaults to draft)
category string no Category name
tags string no Comma-separated tag list
author string no Author name
created_at string no ISO 8601 date string
research_citations string[] no Source URLs from research
faq_schema string no FAQ structured data

Architecture Notes

  • All operations run locally on the user's machine (filesystem reads/writes only)
  • No database queries or remote API calls during import/export
  • Authentication verified on every tool call via API key
  • CSV parsing handles quoted fields, escaped quotes, and configurable delimiters
  • Markdown export creates a manifest.json alongside the .md files
  • HTML export generates a self-contained single-page document