sample-sop-mcp

Turn your repeatable processes into Standard Operating Procedures (SOPs) that an AI agent executes one step at a time.

An MCP server that hands a procedure to your AI assistant one step at a time and asks it to produce concrete output before moving on. You talk to your agent in plain language — Kiro, Cursor, Claude Desktop, a Strands agent, or any MCP client — and it calls the SOP tools for you under the hood.

✨ Features

• 🗣️ Plain-language driven — Ask your agent to run or author an SOP; you never call tools by hand
• 👣 Step-at-a-time execution — Each step must be executed and produce output before the agent advances
• ✅ Gated & auditable — RFC 2119 levels (MUST, SHOULD, MAY) delivered one step at a time, each gated behind the previous, with progress kept explicit
• 📦 Batteries included — Four ready-to-run SOPs seeded on first launch
• ✍️ Guided authoring — A built-in guide interviews you, drafts, lints, and publishes new SOPs
• 🔌 Works everywhere — One-click install for Kiro, Cursor, and VS Code; manual config for any MCP client

🤔 What's an SOP?

A Standard Operating Procedure is a markdown document that captures a repeatable, multi-step process — a code review, onboarding a new hire, cutting a release. LLMs are powerful but unpredictable across multi-step work: they skip steps, summarize instead of act, and lose their place. sop-mcp makes that behavior predictable — procedures arrive step by step, execution is gated, and progress is explicit.

🚀 Quick Start

1. Install

Add the server with one click, or paste the config below.

Kiro	Cursor	VS Code

{
  "mcpServers": {
    "sop-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aws-samples/sample-sop-mcp", "sop-mcp"]
    }
  }
}

uvx fetches and runs the server straight from this repo — no clone or build. On first run it seeds four bundled SOPs into your storage directory. SOP_STORAGE_DIR is optional (see Storage).

2. Verify the install

Restart your MCP client, then ask your agent to list the available SOPs:

You: "List available SOPs."

You should see the bundled SOPs — sop_creation_guide, code_review_process and more. If none appear, check your MCP client's server logs for errors.

3. Run an SOP

Just ask your agent. It discovers the available SOPs, starts the one you named, and walks through it step by step — doing the work each step describes before advancing.

You: "Run the code review SOP for my current branch."

You stay in the conversation: review each step's output, answer questions, or course-correct as it goes.

4. Author an SOP

Ask the agent to run the built-in authoring guide. It interviews you, drafts the SOP, validates it against the linter, and publishes it — all through conversation.

You: "Help me write a new SOP for our release process — use the sop_creation_guide."

You: "Looks good — publish it as preprod."

A clean lint means a clean publish, so your SOP is immediately runnable: "Run my_release_process."

🔄 How It Works

sequenceDiagram
    actor User
    participant Agent as AI Agent (MCP client)
    participant SOP as sop-mcp server
    participant Store as SOP storage (~/.sop_mcp)

    User->>Agent: "Run the code review SOP"
    Agent->>SOP: list_resources
    SOP->>Store: scan *.sop.md
    Store-->>SOP: SOP names
    SOP-->>Agent: available SOPs (sop://...)

    Agent->>SOP: run_sop(sop_name, current_step=0)
    SOP->>Store: read SOP markdown
    SOP-->>Agent: Step 1 of N + execution rules
    Agent->>Agent: execute step 1 (do the work)

    Agent->>SOP: run_sop(current_step=1, step_output="...")
    Note over Agent,SOP: required — step_output gates the next step
    opt human in the loop
        Agent-->>User: optionally show progress / ask input
    end
    SOP-->>Agent: Step 2 of N
    Note over Agent,SOP: repeat until the final step
    SOP-->>Agent: "SOP execution complete."
    Agent-->>User: done

Each step tells the agent to execute — not just read. It must produce the step's expected output before advancing, which is what makes the run auditable. As the human in the loop, you see each step's result and can intervene at any point.

⚠️ Treat SOP content as untrusted. sop-mcp serves SOP markdown to your agent verbatim — it can't tell a legitimate instruction from a malicious one. If your SOP_STORAGE_DIR is shared, synced, or holds SOPs you didn't author, review an SOP before running it: a crafted SOP could steer the agent into unintended actions (prompt injection). Keep a human in the loop for steps with real-world side effects.

🧩 Agent SOPs vs. Skills

The SOPs here use the Agent SOP format — portable markdown workflows (parameterized, with RFC 2119 MUST/SHOULD/MAY constraints) that guide an agent through a multi-step process. An Agent Skill is also markdown that guides an agent, so the two look similar — the real difference is how the instructions reach the agent:

• As a skill — the whole playbook loads into context at once and the agent self-directs, so it can read ahead, skip, batch, or summarize. Great for domain knowledge and flexible tasks. (Agent SOPs can even be exported to the Skills format.)
• Via sop-mcp — the same SOP is metered out one step at a time. The agent sees only the current step and must report its output before the next is released. It can't look ahead or skip — which is what makes a multi-step run consistent and auditable.

(Separately, this repo also ships a regular skill — sop-mcp-usage — that teaches an agent how to drive the server.)

📦 Bundled SOPs

Four SOPs ship with the server — ask your agent to run any by name:

🛠️ Tools

The agent calls these on your behalf — you won't invoke them directly.

Full parameter reference: docs/mcp-reference.md

💾 Storage

On first run the server seeds the bundled SOPs into your storage directory — ~/.sop_mcp by default, or set SOP_STORAGE_DIR to point it elsewhere. Bundled SOPs are only copied when the directory has no SOPs yet, so anything you author is never overwritten.

To use a custom location, add a SOP_STORAGE_DIR env var to the server config:

{
  "mcpServers": {
    "sop-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aws-samples/sample-sop-mcp", "sop-mcp"],
      "env": { "SOP_STORAGE_DIR": "/path/to/your/sops" }
    }
  }
}

📚 Documentation

💻 Development

uv sync                                  # install dependencies
uv run pytest                            # run tests
uv run ruff check src/ tests/            # lint
uv run sop-mcp                           # start server locally
uv run python scripts/generate_docs.py   # regenerate docs

🔐 Security

See SECURITY.md for the security policy, vulnerability reporting process, and security model documentation.

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.