The PromptArch CLI & MCP Server: A Complete Guide

PromptArch isn't just a web app. The same engine that powers the Context Engineering Studio ships as two developer surfaces: a CLI you run in your terminal, and an MCP server your AI agent can call directly. This guide covers both: installation, every command and tool, API keys, and how to wire them into CI.

The 30-second version

npm install -g promptarch

promptarch lint CLAUDE.md        # free, offline, CI-friendly
promptarch login                 # paste a pk_ API key once
promptarch init                  # repo → CLAUDE.md, AGENTS.md, Cursor, Copilot

And for agents, one config block:

{
  "mcpServers": {
    "promptarch": {
      "type": "http",
      "url": "https://mcp.promptarch.ai/mcp",
      "headers": { "Authorization": "Bearer pk_your_key" }
    }
  }
}

Linting is always free: no account, no network call from the CLI, no key for the MCP lint tool. Generation costs credits from your PromptArch account, same as building in the app.

Part 1: The CLI

Installing

npm install -g promptarch

That's it. The package bundles everything it needs (Node 18+).

promptarch lint - free, offline, deterministic

promptarch lint CLAUDE.md
promptarch lint AGENTS.md .cursor/rules/*.mdc
promptarch lint CLAUDE.md --strict

The linter detects the artifact format (CLAUDE.md, AGENTS.md, Cursor .mdc, Copilot instructions, memory files), runs a deterministic engine of ~30 research-backed rule families against it, and prints a grade plus a 0–100 objective score with line-anchored, cited explanations. Beyond the basics (per-tool size budgets, vague language, secrets), it flags what current models' own vendors now say to remove: forcing language like "CRITICAL: You MUST use…" (causes over-triggering on Claude 4.5+/GPT-5), "think step by step" scaffolding (reasoning models do this internally; echo-your-reasoning asks can trigger refusals on Claude Fable 5), sycophancy triggers ("match the user's vibe"), pasted directory trees (agents ignore them but pay ~+20% reasoning tokens for them, per an ETH Zurich benchmark), never/always contradictions, and hidden-Unicode instruction smuggling (the "Rules File Backdoor" attack class) with concealment directives and exfil-sink domains.

Three properties make it CI-friendly:

• Offline. No network call, no account, no key. The rules run locally.
• Deterministic. Same file in, same findings out: no LLM variance.
• Exit codes. Non-zero when any file has errors, so a failing lint fails the build. Add --strict to fail on warnings too.

A minimal GitHub Actions step:

- run: npx promptarch lint CLAUDE.md AGENTS.md --strict

This is the same rule engine behind the free web linter at /lint. The CLI just brings it to your repo.

promptarch login - store your API key

Generation (unlike linting) talks to the PromptArch API, so it needs an API key:

1. Create a key under Profile → API keys in the app. Keys start with pk_ and are shown once at creation.
2. Run promptarch login and paste it. The key is stored in ~/.config/promptarch/config.json with owner-only file permissions.

For CI or scripted use, skip the prompt:

promptarch login --key pk_your_key     # non-interactive
# or just set an env var - it wins over the saved config:
export PROMPTARCH_API_KEY=pk_your_key

promptarch init - from repo to context files

promptarch init
promptarch init --dry-run     # show what would be sent, no API call
promptarch init --out docs/   # write files somewhere else

init scans your repository (stack manifest, build commands, the directory tree, your README, and any existing agent config) and sends that context to the PromptArch generation API. Stack detection spans ecosystems, not just Node: it reads package.json, Package.swift/.xcodeproj (Swift), pyproject.toml/requirements.txt (Python, incl. FastAPI/Django/Flask), go.mod, Cargo.toml, and Gemfile; commands come from npm scripts, Makefile targets, and justfile recipes. The result comes back as one canonical context pack, which the CLI exports deterministically into the files each tool expects:

• CLAUDE.md for Claude Code
• AGENTS.md for AGENTS.md-compatible agents
• .cursor/rules/*.mdc for Cursor
• .github/copilot-instructions.md for GitHub Copilot

Each file is kept within the size budget its tool actually reads well, and you can re-run promptarch lint on the output to verify. Use --dry-run first if you want to see exactly what repo context would be sent before anything leaves your machine.

A real run

On a FastAPI service, from a clean checkout:

$ promptarch lint CLAUDE.md
CLAUDE.md - grade C (72/100, claude_md)
  ⚠ warn  line 3  vague/low-signal: "follow best practices" ...
  ⚠ warn  line 8  antipattern/verbosity-instruction: "be concise" ...

$ promptarch init --dry-run        # free; no key, no network call
# → detects tech_stack: "Python, FastAPI, SQLAlchemy", commands from the Makefile

$ promptarch init                  # confirms overwrites first, then generates
init writes agent config files into /srv/app, overwriting:
  CLAUDE.md
Continue? Generating uses one credit. [y/N] y
wrote AGENTS.md
wrote CLAUDE.md
wrote .cursor/rules/overview.mdc
wrote .cursor/rules/structure.mdc
wrote .cursor/rules/style.mdc
wrote .cursor/rules/boundaries.mdc
wrote .github/copilot-instructions.md
wrote .github/instructions/style.instructions.md

✓ Generated 8 file(s) in /srv/app

$ promptarch lint CLAUDE.md
CLAUDE.md - grade A (100/100, claude_md)
  ✓ no findings

That's the loop: lint to see where you stand, generate a clean baseline, lint again to confirm. init never clobbers a hand-maintained file silently, it asks first (pass --force to skip the prompt, or --out <dir> to write elsewhere). In CI, gate on the lint alone:

- run: npx promptarch lint CLAUDE.md AGENTS.md --strict

Part 2: The MCP server

If you use Claude Code, Cursor, Windsurf, or any other Model Context Protocol client, your agent can lint and generate artifacts itself, no terminal round-trip.

The server lives at https://mcp.promptarch.ai/mcp and speaks Streamable HTTP, so there's nothing to install or run locally.

Connecting a client

Add this to your MCP client's server config. For Claude Code that's .mcp.json at the repo root; for Cursor, .cursor/mcp.json:

{
  "mcpServers": {
    "promptarch": {
      "type": "http",
      "url": "https://mcp.promptarch.ai/mcp",
      "headers": { "Authorization": "Bearer pk_your_key" }
    }
  }
}

Only generation needs the Authorization header. Lint-only users can omit it entirely.

The tools

In practice this means you can tell your agent things like "lint this CLAUDE.md and fix what it flags" or "generate a Cursor rule for our API conventions" and it handles the tool calls itself. Your API key never touches the MCP server's storage. It's forwarded per-request to the PromptArch API.

Example prompts

Once the server is connected you drive it in plain language, and the agent picks the tool:

• "What artifact types can promptarch generate?" → runs promptarch_list_artifact_types and lists Context Pack, CLAUDE.md, AGENTS.md, and Cursor rule.
• "Lint our CLAUDE.md with promptarch and fix what it flags." → runs promptarch_lint_artifact (free), then the agent edits the file to clear the findings, e.g. dropping a "follow best practices" line, removing a "think step by step" instruction, and cutting a "be concise" directive the linter warns about.
• "Generate a CLAUDE.md for this repo with promptarch: Next.js 15, Drizzle on SQLite, pnpm." → runs promptarch_generate_artifact (one credit) and writes a structured file with Commands, Architecture, Code Style, and Troubleshooting sections.
• "Give me a Cursor rule for our API validation conventions." → promptarch_generate_artifact with the cursor_rule artifact, returning an .mdc with proper frontmatter.

The real payoff is chaining: lint → read the grade → regenerate or hand-fix → lint again to confirm an A, all without leaving the agent.

Which surface when?

• Web app (/studio) - exploring artifact types, building with the guided wizard, managing your library.
• CLI - repo-native workflows: bootstrap context files for a project with init, gate PRs with lint in CI.
• MCP - agent-native workflows: the agent lints and regenerates its own context files as part of doing its job.

All three share the same generation engine, the same lint rules, and the same credit balance.

Get started

1. npm install -g promptarch and lint something. It's free.
2. Create an API key under Profile → API keys when you're ready to generate.
3. Point your agent at https://mcp.promptarch.ai/mcp.

New accounts get free credits, enough to try init on a real repo without a card.