# MCP vs CLI

sitemd has two interfaces that do the same thing: the [MCP server](/docs/mcp-server) for AI agents and the [CLI](/docs/cli-config) 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:

```text
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.