{"id":40454608,"url":"https://github.com/rcrsr/mcp-policy-server","last_synced_at":"2026-01-26T08:03:52.798Z","repository":{"id":320644264,"uuid":"1082786510","full_name":"rcrsr/mcp-policy-server","owner":"rcrsr","description":"MCP server for dynamically injecting agents and prompts with policy documentation.","archived":false,"fork":false,"pushed_at":"2026-01-13T22:10:23.000Z","size":542,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-21T00:17:50.700Z","etag":null,"topics":["agentic-ai","claude-code","mcp","model-context-protocol","model-context-protocol-server","policies"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rcrsr.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2025-10-24T19:10:56.000Z","updated_at":"2026-01-12T04:58:11.000Z","dependencies_parsed_at":"2025-10-25T01:29:37.916Z","dependency_job_id":null,"html_url":"https://github.com/rcrsr/mcp-policy-server","commit_stats":null,"previous_names":["andrebremer/mcp-policy-server","rcrsr/mcp-policy-server"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/rcrsr/mcp-policy-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcrsr%2Fmcp-policy-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcrsr%2Fmcp-policy-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcrsr%2Fmcp-policy-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcrsr%2Fmcp-policy-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rcrsr","download_url":"https://codeload.github.com/rcrsr/mcp-policy-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcrsr%2Fmcp-policy-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28770062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T07:45:00.504Z","status":"ssl_error","status_checked_at":"2026-01-26T07:45:00.070Z","response_time":59,"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":["agentic-ai","claude-code","mcp","model-context-protocol","model-context-protocol-server","policies"],"created_at":"2026-01-20T17:30:16.265Z","updated_at":"2026-01-26T08:03:52.792Z","avatar_url":"https://github.com/rcrsr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Policy Server\n\n**Give your Claude Code subagents instant, token-efficient access to your team's standards, guidelines, and best practices.**\n\nStop polluting your context by putting all your agent guidelines into CLAUDE.md or each subagent definition. Reference specific rules with compact § notation and let subagents fetch exactly what they need, when they need it.\n\n## Why Use This?\n\n### The Problem\n\nTeams document standards in markdown files (coding guidelines, architecture principles, deployment procedures). When you want Claude Code subagents to follow these standards, you're stuck with imperfect options:\n\n- **Put everything in memory like CLAUDE.md or rules files**: Signal loss, high token costs due to implicit context that may not be needed for all tasks\n- **Reference entire documents**: Unreliable, wastes tokens, hits context limits\n- **Maintain each subagent separately**: Unnecessary duplication, hard to keep consistent\n\n### The Solution\n\nReference sections with notation like `§PREFIX.1` or `§PREFIX.2.3-5`. Policies are fetched on demand. Your standards stay in markdown files. Subagents always get current content without token waste.\n\n### Key Benefits\n\n- **No wasted context**: Fetch only needed sections, not entire documents\n- **Always current**: Update files, changes appear automatically\n- **Automatic resolution**: Reference one section, get it plus any sections it references\n- **Fast lookups**: O(1) retrieval via section indexing\n- **Per-project policies**: Same installation, different policy sets per project\n\n## Setup Methods\n\n| Method | Best For | How It Works |\n|--------|----------|--------------|\n| **[Plugin](#method-1-claude-code-plugin-recommended)** | Claude Code subagents | One command install, policies injected automatically |\n| **[Hook](#method-2-claude-code-hook)** | Custom hook configuration | Manual hook setup for non-standard policy paths |\n| **[MCP Server](#method-3-mcp-server)** | Other MCP clients, dynamic policy selection | Subagents call `fetch_policies` tool explicitly |\n| **[CLI](#method-4-cli)** | Scripts, CI/CD, non-MCP tools | Command-line policy extraction |\n\nChoose **Plugin** for Claude Code projects (simplest). Choose **Hook** if you need custom policy paths or hook behavior. Choose **MCP Server** when subagents need to dynamically select policies based on prompt criteria, or when using other MCP-compatible clients. Choose **CLI** for automation scripts or non-MCP integrations.\n\n## Quick Start: Create a Policy File\n\nAll methods require policy files with § notation. Create a policies directory and sample file:\n\n**`.claude/policies/policy-example.md`** (for Plugin method) or **`./policies/policy-example.md`** (for other methods):\n```markdown\n## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)\n\nBuild what you need now. Add features when needed, not in anticipation.\n\n**Guidelines:**\n- No speculative generalization\n- No placeholder code for \"future features\"\n- No abstraction without 3+ concrete use cases\n- Delete unused code immediately\n\n## {§DESIGN.2} Keep It Simple\n\nSee also §DESIGN.1 for related principles.\n```\n\n---\n\n## Method 1: Claude Code Plugin (Recommended)\n\nInstall the policies plugin and create policy files. The plugin configures hooks automatically.\n\n### Step 1: Install the Plugin\n\nInside Claude Code, run this once:\n\n```\n/plugin marketplace add rcrsr/claude-plugins\n```\n\nThen install the policies plugin:\n\n```\n/plugin install policies@rcrsr\n```\n\nThe policies files should be placed in `.claude/policies/` within your project directory.\n\n### Step 2: Create Policy Files\n\nAdd policy files to `.claude/policies/`:\n\n**`.claude/policies/design.md`:**\n```markdown\n## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)\n\nBuild what you need now. Add features when needed, not in anticipation.\n\n**Guidelines:**\n- No speculative generalization\n- No placeholder code for \"future features\"\n- No abstraction without 3+ concrete use cases\n- Delete unused code immediately\n\n## {§DESIGN.2} Keep It Simple\n\nSee also §DESIGN.1 for related principles.\n```\n\n### Step 3: Reference Policies in Subagents\n\n**`.claude/agents/code-reviewer.md`:**\n```markdown\n---\nname: code-reviewer\ndescription: Reviews code for compliance with standards\n---\n\nRequired policies: §DESIGN.1, §DESIGN.2\n\nYou are a code reviewer following our team standards.\nApply the policies above when reviewing code.\n```\n\n### Step 4: Run the Subagent\n\n```\n\u003e @agent-code-reviewer review this PR\n```\n\nThe plugin intercepts Task tool calls, extracts § references from the agent file, and injects matching policies automatically.\n\n**Note:** References inside code fences are ignored, allowing you to document examples without triggering extraction.\n\n---\n\n## Method 2: Claude Code Hook\n\nManual hook configuration for custom policy paths or behavior. Use this when the Plugin method's default `.claude/policies/*.md` path doesn't fit your project structure.\n\n### Step 1: Configure the Hook\n\nAdd to your project's `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"Task\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"npx -p @rcrsr/mcp-policy-server policy-hook --config \\\"./policies/*.md\\\"\"\n      }]\n    }]\n  }\n}\n```\n\nMake sure to restart Claude Code after updating settings.\n\n### Step 2: Create a Subagent with Policy References\n\nThe actual format does not matter as long as the policy references are not code-fenced. For example:\n\n**`.claude/agents/code-reviewer.md`:**\n```markdown\n---\nname: code-reviewer\ndescription: Reviews code for compliance with standards\n---\n\nRequired policies: §DESIGN.1, §DESIGN.2\n\nYou are a code reviewer following our team standards.\nApply the policies above when reviewing code.\n```\n\n### Step 3: Run the Subagent\n\n```\n\u003e @agent-code-reviewer review this PR\n```\n\n**What happens:**\n1. Hook detects Task tool call with agent file\n2. `policy-hook` extracts all § references from agent file (§DESIGN.1, §DESIGN.2)\n3. Policies are injected into the agent prompt wrapped in `\u003cpolicies\u003e` tags\n4. Subagent receives policies automatically—no explicit tool call needed\n\n**Note:** References inside code fences are ignored, allowing you to document examples without triggering extraction.\n\n### Prefix-Only References\n\nUse prefix-only notation to fetch all sections with a given prefix:\n\n```markdown\nRequired: §DESIGN, §API\n```\n\nThis expands `§DESIGN` to all `§DESIGN.*` sections and `§API` to all `§API.*` sections.\n\n---\n\n## Method 3: MCP Server\n\nSubagents call `fetch_policies` tool explicitly. Use this when:\n- Subagents need to dynamically select policies based on prompt content\n- You're using MCP-compatible clients other than Claude Code\n- You need validation tools (`validate_references`, `extract_references`)\n\n### Step 1: Install the MCP Server\n\n**Linux/macOS:**\n```bash\nclaude mcp add-json policy-server '{\n  \"type\": \"stdio\",\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@rcrsr/mcp-policy-server\"],\n  \"env\": {\"MCP_POLICY_CONFIG\": \"./policies/*.md\"}}' \\\n  --scope project\n```\n\n**Windows:**\n```powershell\nclaude mcp add-json policy-server ('{' `\n  '\"type\": \"stdio\", \"command\": \"cmd\",' + `\n  '\"args\": [\"/c\", \"npx\", \"-y\", \"@rcrsr/mcp-policy-server\"], ' + `\n  '\"env\": {\"MCP_POLICY_CONFIG\": \"./policies/*.md\"}}') `\n  --scope project\n```\n\n### Step 2: Create a Subagent with Explicit Tool Call\n\n**`.claude/agents/code-reviewer.md`:**\n```markdown\n---\nname: code-reviewer\ndescription: Reviews code for compliance with standards\ntools: mcp__policy-server__fetch_policies, Read, Glob\n---\n\nYou are a code reviewer following our team standards.\n\n**Before reviewing code:** call `mcp__policy-server__fetch_policies` with `{\"sections\": [\"§DESIGN.1\", \"§DESIGN.2\"]}`\n```\n\n### Step 3: Test and Run\n\n1. Restart Claude Code\n2. Accept prompts to enable the MCP server\n3. Run `/mcp` to verify \"policy-server\" shows \"connected\"\n4. Run `@agent-code-reviewer review this file`\n\nSee [Installation Guide](docs/INSTALLATION.md) for detailed setup.\n\n---\n\n## Method 4: CLI\n\nUse `policy-cli` for scripts, CI/CD, or non-MCP integrations.\n\n### Available Subcommands\n\n```bash\npolicy-cli fetch-policies \u003cfile\u003e        # Fetch policies for § refs in a file\npolicy-cli validate-references \u003cref\u003e... # Validate § refs exist\npolicy-cli extract-references \u003cfile\u003e    # Extract § refs from a file\npolicy-cli list-sources                 # List available policy files\npolicy-cli resolve-references \u003cref\u003e...  # Map § refs to source files\n```\n\n### Extract Policies from a File\n\n```bash\nnpx -p @rcrsr/mcp-policy-server policy-cli fetch-policies document.md --config \"./policies/*.md\"\n```\n\nExtracts § references from `document.md`, fetches matching policies, outputs to stdout.\n\n### Use in Scripts\n\n```bash\n# Inject policies into a prompt template\nPOLICIES=$(npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies agent.md --config \"./policies/*.md\")\necho \"Follow these policies: $POLICIES\" | your-llm-tool\n\n# Validate references before use\nnpx -p @rcrsr/mcp-policy-server policy-cli validate-references §DOC.1 §DOC.2 --config \"./policies/*.md\"\n```\n\n---\n\n## MCP Server Tools\n\nThese tools are available when using [Method 3: MCP Server](#method-3-mcp-server).\n\n| Tool | Purpose |\n|------|---------|\n| `fetch_policies` | Retrieve sections with automatic reference resolution |\n| `validate_references` | Check that § references exist before using them |\n| `extract_references` | Scan a file for § references |\n| `list_sources` | List configured policy files and available prefixes |\n| `resolve_references` | Map sections to source files |\n\n**Example usage:**\n```json\n{\"sections\": [\"§PREFIX.1\", \"§PREFIX.2\"]}\n```\n\n## Use Cases\n\n- **Code Review**: Reference coding standards, style guides, architecture principles\n- **Deployment**: Reference procedures, security checklists, rollback protocols\n- **Documentation**: Reference standards, templates, review processes\n- **Testing**: Reference coverage requirements, mocking patterns, integration setup\n\n## Documentation\n\n- [Getting Started](docs/GETTING_STARTED.md) - Step-by-step setup for all four methods\n- [Installation Guide](docs/INSTALLATION.md) - Detailed installation options\n- [Configuration Reference](docs/CONFIGURATION_REFERENCE.md) - Config options for hooks, MCP, and CLI\n- [Policy Reference](docs/POLICY_REFERENCE.md) - § notation syntax\n- [Best Practices](docs/BEST_PRACTICES.md) - Patterns and strategies\n\n## License\n\n[GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.en.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcrsr%2Fmcp-policy-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frcrsr%2Fmcp-policy-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcrsr%2Fmcp-policy-server/lists"}