MCP vs CLI

sitemd has two interfaces that do the same thing: the MCP server for AI agents and the CLI for humans in the terminal. Both wrap the same build engine, share the same validation logic, and produce identical output.

When to use MCP

Use the MCP server when an AI coding agent is driving. The agent calls structured tools with JSON parameters and gets structured JSON back — no terminal parsing, no interactive prompts.

MCP is the default for:

Claude Code, Codex, Cursor, Gemini CLI — these read .mcp.json automatically and call MCP tools as part of their workflow
Autonomous site building — agents can scaffold, create pages, configure settings, and deploy without human intervention
Conversational config setup — instead of a terminal wizard, the agent asks you questions in chat and calls sitemd_config_set with your answers
Content validation — agents call sitemd_build or sitemd_content_validate to catch issues and fix them in the same conversation

When to use CLI

Use the CLI when you want direct control. It's faster for quick checks and lets you use shell features like pipes and scripts.

CLI is the default for:

Quick project status — run sitemd for an interactive overview
Dev server — sitemd launch starts the server with live reload
Manual deploys — sitemd deploy when you want to push on your own schedule
Shell scripting — pipe JSON output from sitemd pages, sitemd settings, sitemd seo, or sitemd validate into jq or other tools
Interactive setup — sitemd config setup walks you through provider selection with a guided wizard
Credential management — sitemd auth login, sitemd config set for one-off operations

Feature parity

Both interfaces cover the same capabilities. The table below maps MCP tools to their CLI equivalents. Operations marked "direct file access" are handled by the agent's native Read/Edit/Glob tools instead of MCP tools — this reduces token overhead.

Capability	MCP Tool	CLI Command
Project status	`sitemd_status`	`sitemd` (interactive menu)
Initialize project	`sitemd_init`	`sitemd init <dir>`
Build	`sitemd_build`	built into `sitemd deploy`
Deploy	`sitemd_deploy`	`sitemd deploy`
Deploy (skip build)	`sitemd_deploy` with `skipBuild: true`	`sitemd deploy --no-build`
Activate site	`sitemd_activate`	`sitemd activate`
Login	`sitemd_auth_login` + `sitemd_auth_poll`	`sitemd auth login`
Auth status	`sitemd_auth_status`	`sitemd auth status`
Logout	`sitemd_auth_logout`	`sitemd auth logout`
API keys	`sitemd_auth_api_key`	`sitemd auth api-key [name]`
Auth setup	`sitemd_auth_setup`	`sitemd config setup auth`
Set config	`sitemd_config_set`	`sitemd config set <key> <value>`
Create page	`sitemd_pages_create`	write a markdown file
Create pages (batch)	`sitemd_pages_create_batch`	write multiple files
Delete page	`sitemd_pages_delete`	delete the file + edit groups.md
Add to group	`sitemd_groups_add_pages`	edit `settings/groups.md`
Site context	`sitemd_site_context`	MCP only
Content validate	`sitemd_content_validate`	`sitemd validate [slug]`
SEO audit	`sitemd_seo_audit`	`sitemd seo [options]`
Clone website	`sitemd_clone`	`sitemd clone <url>`
Check updates	`sitemd_update_check`	`sitemd update`
Apply updates	`sitemd_update_apply`	`sitemd update`
Read/edit pages	direct file access	edit `pages/{slug}.md`
Read/edit settings	direct file access	`sitemd settings` or edit file
Read groups	direct file access	read `settings/groups.md`
Config status	direct file access	`sitemd config`
Git history	`git log` via agent	`git log`
Server status	`curl localhost:4747`	check browser
Browse docs	agent uses web search	`sitemd docs [query]`

Direct file access

Agents read and edit markdown files directly using their native tools (Read, Edit, Glob). This is more token-efficient than routing through MCP tools:

Pages — pages/{slug}.md (e.g. /about → pages/about.md, / → pages/home.md)
Settings — settings/{name}.md (e.g. settings/meta.md, settings/theme.md)
Groups — read settings/groups.md directly; use sitemd_groups_add_pages for writes (indent-sensitive)
Config — read .sitemd/config.json; use sitemd_config_set for writes (routes secrets correctly)

MCP tools are reserved for operations that coordinate multiple files (page creation with nav+group updates), require API calls (auth, deploy, activate), or run complex logic (build, validate, SEO audit).

Same engine, same results

Both interfaces import the same modules:

sitemd/engine/
  build/          ← shared build system
    validate.js     shared validation (CLI validate + MCP content_validate)
    config.js       settings loader
    render.js       page builder
  cli/            ← CLI commands
  mcp/            ← MCP tool handlers (22 tools)
  deploy/         ← deploy targets (shared)

A build through MCP produces the same output as a build through the CLI. Validation through sitemd validate reports the same issues as sitemd_content_validate. Pick whichever interface fits the moment — agent conversation or terminal — and get identical results.