Files · Automated Blog Content Pipeline with SEO Scoring

# Automated Blog Content Pipeline with SEO Scoring
 
> From topic brief to published post with built-in SEO gates — no agency needed.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Problem
 
A 10-person SaaS company manually researches keywords, writes blog posts in Google Docs, pastes them into WordPress, installs a Yoast-like plugin for SEO checks, and runs a separate markdown linter before publishing. This pipeline automates the entire workflow: given a topic brief, it generates a draft via LLM, validates and lints the markdown, scores it against SEO criteria, and returns structured results — all through a single API.
 
## Packages
 
This recipe uses 6 REAA packages:
 
| Package | Role |
|---------|------|
| `@reaatech/agents-markdown` | Core types (`AgentsMdDocument`, `LintResult`, `ValidationResult`, `Finding`) and Zod schemas |
| `@reaatech/agents-markdown-validator` | Schema validation engine — validates markdown frontmatter and structure |
| `@reaatech/agents-markdown-linter` | Style, content, and best-practice linting rules engine |
| `@reaatech/agents-markdown-reporter` | Multi-format output reporters — console, JSON, and Markdown |
| `@reaatech/agents-markdown-mcp-server` | MCP server exposing pipeline tools via Model Context Protocol |
| `@reaatech/agents-markdown-observability` | Structured logging and metrics for the pipeline |
 
Additional key dependencies:
 
| Package | Role |
|---------|------|
| `ai` (Vercel AI SDK) | Provider-agnostic LLM interface |
| `@ai-sdk/openai` | OpenAI provider for the AI SDK |
| `zod` | Schema validation for types and API inputs |
 
## API Endpoints
 
### POST `/api/pipeline`
 
Run the full pipeline: generate, validate, lint, score, and report.
 
```bash
curl -X POST http://localhost:3000/api/pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Next.js 16",
    "keywords": ["Next.js", "React", "web development"],
    "targetAudience": "Developers new to Next.js",
    "tone": "professional"
  }'
```
 
### POST `/api/generate`
 
Generate a blog post draft from a topic brief (standalone, no pipeline overhead).
 
```bash
curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "title": "10 Tips for Better SEO",
    "keywords": ["SEO", "content marketing", "ranking"]
  }'
```
 
### POST `/api/validate`
 
Validate markdown content against AGENTS.md schema.
 
```bash
curl -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "---\ntitle: Test\n---\n\n# Hello World",
    "strict": false
  }'
```
 
### POST `/api/lint`
 
Lint markdown content for style and best-practice issues.
 
```bash
curl -X POST http://localhost:3000/api/lint \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello World\n\nThis is a TODO item."
  }'
```
 
### GET `/api/health`
 
Health check returning status, version, and timestamp.
 
```bash
curl http://localhost:3000/api/health
```
 
## MCP Server
 
The pipeline includes an MCP server that exposes agents-markdown tools via the Model Context Protocol (MCP). It provides five tools:
 
| Tool | Description |
|------|-------------|
| `lint_agents_md` | Lint markdown content or file for style and best-practice issues |
| `validate_agents_md` | Validate markdown content or file against the AGENTS.md Zod schema |
| `validate_skill_md` | Validate markdown content or file against the SKILL.md Zod schema |
| `scaffold_agent` | Generate AGENTS.md and SKILL.md files from templates |
| `get_examples` | List or retrieve example agent files |
 
```typescript
import { startBlogMcpServer } from "./src/mcp/index.js";
 
// Start with stdio transport (for local tool-calling agents)
await startBlogMcpServer("stdio");
 
// Start with StreamableHTTP transport (for remote agents)
await startBlogMcpServer("streamable-http");
```
 
## Architecture
 
The pipeline runs through these stages in order:
 
1. **Planning** — Validate the `TopicBrief` input against the Zod schema
2. **Generation** — Call the LLM via Vercel AI SDK to produce a `ContentDraft`
3. **Validation** — Run the markdown through `@reaatech/agents-markdown-validator`
4. **Linting** — Run the markdown through `@reaatech/agents-markdown-linter`
5. **SEO Scoring** — Calculate keyword density, meta description quality, internal link count, and readability
6. **Reporting** — Collect all results, errors, and warnings into a `PipelineResult`
 
Each stage is wrapped with observability via `@reaatech/agents-markdown-observability`. Partial failures are handled gracefully — if scoring fails, the pipeline still returns generation and validation results.
 
## Environment Variables
 
| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAI_API_KEY` | OpenAI API key (required) | — |
| `LLM_MODEL` | LLM model identifier | `gpt-5.2` |
| `NEXT_PUBLIC_APP_URL` | Public app URL for internal links | `http://localhost:3000` |
 
## Running Locally
 
```bash
pnpm install
pnpm dev            # Start development server
pnpm build          # Production build
pnpm start          # Start production server
pnpm test           # Run tests with coverage
pnpm typecheck      # TypeScript type checking
pnpm lint           # ESLint
```
 
## Testing
 
Tests are written with vitest and MSW for HTTP mocking:
 
```bash
pnpm test
```
 
Coverage thresholds: 90% lines, branches, functions, and statements.
 
Test files mirror the source tree under `tests/`. Key test areas:
- Service unit tests (content-generator, seo-scorer, document-validator, document-linter, reporter, observability, pipeline)
- API route tests (pipeline, generate, validate, lint, health)
- MCP server tests
- Integration tests for end-to-end flows
 
## Project Layout
 
```
app/                  Next.js App Router pages + API routes
src/                  Services, types, and MCP server
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency
DEV_PLAN.md           Build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).