{"id":48433884,"url":"https://github.com/valuearchitectsai/sop-mcp","last_synced_at":"2026-04-13T00:56:01.396Z","repository":{"id":340373639,"uuid":"1156046318","full_name":"ValueArchitectsAI/sop-mcp","owner":"ValueArchitectsAI","description":"An MCP server that guides AI agents through Standard Operating Procedures step by step, enforcing execution at each step instead of letting models skip ahead.","archived":false,"fork":false,"pushed_at":"2026-04-06T10:56:27.000Z","size":877,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T11:29:29.535Z","etag":null,"topics":["ai-agent","fastmcp","llm","mcp","mcp-server","python","sop","tool-use"],"latest_commit_sha":null,"homepage":"https://valuearchitects.ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ValueArchitectsAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T07:39:43.000Z","updated_at":"2026-04-06T10:55:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ValueArchitectsAI/sop-mcp","commit_stats":null,"previous_names":["valuearchitectsai/sop-mcp"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/ValueArchitectsAI/sop-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValueArchitectsAI%2Fsop-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValueArchitectsAI%2Fsop-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValueArchitectsAI%2Fsop-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValueArchitectsAI%2Fsop-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ValueArchitectsAI","download_url":"https://codeload.github.com/ValueArchitectsAI/sop-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ValueArchitectsAI%2Fsop-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31471469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","fastmcp","llm","mcp","mcp-server","python","sop","tool-use"],"created_at":"2026-04-06T12:02:06.149Z","updated_at":"2026-04-06T12:02:06.903Z","avatar_url":"https://github.com/ValueArchitectsAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sop-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/sop-mcp?style=flat-square)](https://pypi.org/project/sop-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/sop-mcp?style=flat-square)](https://pypi.org/project/sop-mcp/)\n[![License](https://img.shields.io/pypi/l/sop-mcp?style=flat-square)](https://github.com/ValueArchitectsAI/sop-mcp/blob/main/LICENSE)\n\nAn MCP server that guides AI agents through Standard Operating Procedures (SOPs) step by step, using RFC 2119 requirement levels. Instead of dumping an entire procedure on the agent (which it will summarize or skip), sop-mcp feeds one step at a time and forces actual execution.\n\n## Quick Install\n\n| Kiro | Cursor | VS Code |\n|:---:|:---:|:---:|\n| [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=sop-mcp\u0026config=%7B%22command%22%3A%20%22uvx%22%2C%20%22args%22%3A%20%5B%22sop-mcp%22%5D%7D) | [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=sop-mcp\u0026config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJzb3AtbWNwIl19) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-007ACC?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://vscode.dev/redirect/mcp/install?name=sop-mcp\u0026config=%7B%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22uvx%22%2C%20%22args%22%3A%20%5B%22sop-mcp%22%5D%7D) |\n\nOr add manually to any MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"sop-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"sop-mcp\"]\n    }\n  }\n}\n```\n\n## Why?\n\nAgents tend to summarize or skip steps when given a full procedure. Feeding steps one at a time forces actual execution. Each SOP becomes a dedicated MCP tool (`run_sop`) that the agent discovers naturally in its tool list.\n\n## How It Works\n\n```\nAgent calls run_sop(sop_name=\"sop_creation_guide\")           → gets step 1 + instruction to execute\nAgent executes step 1 actions\nAgent calls run_sop(sop_name=\"sop_creation_guide\", current_step=1, step_output=\"...\")  → gets step 2\n  ... repeats ...\nAgent calls run_sop(sop_name=\"sop_creation_guide\", current_step=8, step_output=\"...\")  → completion signal\n```\n\nEvery response includes an `instruction` field that tells the agent to *act*, not just read.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `publish_sop` | Publish a new or updated SOP with automatic semver bumping |\n| `submit_sop_feedback` | Submit improvement feedback for a specific SOP |\n| `run_sop` | Step-by-step execution of any SOP, with `sop_name` parameter |\n\n## Skills\n\nThe [`skills/sop-mcp-configuration/`](skills/sop-mcp-configuration/) folder contains a self-contained configuration skill with setup instructions, hook examples, and documentation. Copy the [`SKILL.md`](skills/sop-mcp-configuration/SKILL.md) into your MCP client's skill directory to get guided configuration assistance.\n\n## Hooks\n\nsop-mcp includes an optional hook system that triggers external actions (shell commands, webhooks, LLM suggestions) when tools are called. See the [`SKILL.md`](skills/sop-mcp-configuration/SKILL.md) for setup, events, context variables, and examples.\n\n## Discovering SOPs\n\nSOPs are exposed as MCP resources, so agents can list and read them before starting execution.\n\n| Method | URI | Description |\n|--------|-----|-------------|\n| `list_resources` | — | Returns all available SOPs with name, version, step count, and overview |\n| `read_resource` | `sop://{sop_name}` | Read the full latest SOP markdown |\n| `read_resource` | `sop://{sop_name}?version=1.0` | Read a specific version |\n\nFor clients that don't support the MCP resource protocol, resources are also exposed as tools automatically via `ResourcesAsTools`.\n\nThis lets agents load the full SOP content upfront if needed — for example, to understand scope before committing to a multi-step run.\n\n## Creating SOPs\n\nThe built-in `sop_creation_guide` SOP walks agents through the full authoring process (call `run_sop` with `sop_name=\"sop_creation_guide\"`):\n\n1. **Prepare** — gather process info, identify stakeholders, collect existing docs\n2. **Structure** — define metadata, scope, parameters, and document skeleton\n3. **Document** — write detailed step-by-step instructions with decision points\n4. **Apply RFC 2119** — classify each action as MUST, SHOULD, or MAY\n5. **Enrich** — add troubleshooting, best practices, examples, and references\n6. **Review** — validate with SMEs and end users, run through the checklist\n7. **Finalize** — incorporate feedback, publish via `publish_sop`, notify stakeholders\n8. **Maintain** — schedule reviews, collect feedback, keep the SOP current\n\nAfter publishing, restart the server to register the new SOP.\n\n## The `step_output` Field\n\nThe `run_sop` tool accepts an optional `step_output` string parameter (required when `current_step \u003e= 1`). This is where the LLM submits its concrete work product for the completed step — specific values, names, dates, and details rather than summaries.\n\nThe server accepts `step_output` but does not store or process it. The field exists purely to force the LLM to produce detailed output that lands in the conversation's tool-call history. When all steps are complete, the LLM can reference its own `step_output` submissions to compile a comprehensive final document. State lives entirely in the LLM's conversation context, keeping the server stateless.\n\n### Request/response flow\n\n```\n# Step 1: Initial call — no step_output needed\nAgent calls run_sop(sop_name=\"my_sop\")\n→ Response: Step 1 instruction\n\n# Step 2: Agent submits step 1 output\nAgent calls run_sop(\n    sop_name=\"my_sop\",\n    current_step=1,\n    step_output=\"Registration: VALID, Number: BRN-2024-0738291\"\n)\n→ Response: Step 2 instruction\n\n# Step 3: Agent submits step 2 output\nAgent calls run_sop(\n    sop_name=\"my_sop\",\n    current_step=2,\n    step_output=\"Insurance: Hartford Financial, Policy: HFS-GL-4829173\"\n)\n→ Response: Step 3 instruction\n\n# Completion: Agent submits final step output\nAgent calls run_sop(\n    sop_name=\"my_sop\",\n    current_step=3,\n    step_output=\"Compliance: All checks passed, Certificate: CC-2024-9182\"\n)\n→ Response: Completion signal\n```\n\nAt completion, the LLM uses its conversation history of `step_output` submissions to compile the final document with all concrete values.\n\n## Storage Configuration\n\nsop-mcp uses local filesystem storage for SOP persistence.\n\n### Hook Events\n\nThe hook system uses FastMCP middleware to fire events on every tool call. Event names match tool names directly — no mapping needed.\n\n| Event Name | Triggered When | Description |\n|------------|-----------------|-------------|\n| `run_sop` | Every `run_sop()` call | Fires on every step |\n| `publish_sop` | Every `publish_sop()` call | Fires on publish attempts |\n| `submit_sop_feedback` | Every `submit_sop_feedback()` call | Fires on feedback submissions |\n| `sop_completed` | `run_sop()` final step | Bonus event when `current_step == total_steps` |\n\n### Local Filesystem (default)\n\nBy default, SOPs are stored in the bundled `src/sops/` directory (ephemeral — data may be lost if the package cache refreshes).\n\nTo persist SOPs locally, set `SOP_STORAGE_DIR`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sop-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"sop-mcp\"],\n      \"env\": {\n        \"SOP_STORAGE_DIR\": \"/path/to/my/sops\"\n      }\n    }\n  }\n}\n```\n\nBundled SOPs are automatically seeded into the custom directory on first run.\n\n## Writing an SOP\n\nEvery SOP markdown file must include:\n\n- A level-1 heading (`# Title`)\n- A `**Document ID**:` field (lowercase, underscores, min 3 words)\n- A `**Version:**` field (semver)\n- An `## Overview` section\n- One or more `### Step N:` sections\n\nUse RFC 2119 keywords (MUST, SHOULD, MAY) to define requirement levels.\n\n## Publishing\n\nCall `publish_sop` with the full markdown content and a `change_type`:\n\n| Type | Effect | Example |\n|------|--------|---------|\n| `major` | Breaking change | 1.2.0 → 2.0.0 |\n| `minor` | New feature | 1.2.0 → 1.3.0 |\n| `patch` | Bugfix | 1.2.0 → 1.2.1 |\n\nNew SOPs always start at v1.0.0.\n\n## SOP Naming Convention\n\n| Element | Format | Example |\n|---------|--------|---------|\n| Folder name | lowercase, underscores | `sop_creation_guide` |\n| Document ID | same as folder name | `sop_creation_guide` |\n| Tool name | `run_sop` with `sop_name=` folder name | `run_sop(sop_name=\"sop_creation_guide\")` |\n| Version file | `v` + semver | `v1.0.0.md` |\n\n## Development\n\nRequires Python 3.10+ and [uv](https://docs.astral.sh/uv/).\n\n```bash\nuv sync              # install dependencies\nuv run pytest        # run tests\nuv run sop-mcp       # start server locally\n```\n\n## Architecture\n\n```mermaid\nsequenceDiagram\n    participant Agent as AI Agent\u003cbr/\u003e(Claude/Kiro)\n    participant Server as sop-mcp\u003cbr/\u003eServer\n    participant Storage as Storage Backend\u003cbr/\u003e(configurable)\n\n    Note over Agent,Storage: Initialize\n    Agent-\u003e\u003eServer: run_sop(sop_name=\"sop_creation_guide\")\n    Server-\u003e\u003eStorage: Load latest version\n    Storage--\u003e\u003eServer: SOP content\n    Server--\u003e\u003eAgent: Step 1 + overview + instruction\n\n    Note over Agent,Storage: Execute Steps\n    loop For each step\n        Agent-\u003e\u003eAgent: Execute step actions\n        Agent-\u003e\u003eServer: run_sop(sop_name=\"sop_creation_guide\", current_step=N, step_output=\"...\")\n        Server--\u003e\u003eAgent: Step N+1 + instruction\n    end\n\n    Note over Agent,Storage: Complete\n    Agent-\u003e\u003eServer: run_sop(sop_name=\"sop_creation_guide\", current_step=last, step_output=\"...\")\n    Server--\u003e\u003eAgent: completion signal\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaluearchitectsai%2Fsop-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaluearchitectsai%2Fsop-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaluearchitectsai%2Fsop-mcp/lists"}