MCP Policy Server

MCP策略服务器

让您的Claude Code子代理即时、令牌高效地访问您团队的标准、指南和最佳实践。

通过将所有代理指南放入CLAUDE.md或每个子代理定义中，停止污染您的上下文。使用紧凑§符号引用特定规则，让子代理在需要时准确获取所需内容。

为什么使用这个？

问题

团队在markdown文件中记录标准（编码指南、架构原则、部署过程）。当你希望Claude Code子代理遵循这些标准时，你会遇到不完美的选择：

• 将所有内容放入内存，如CLAUDE.md或规则文件：信号丢失，由于隐式上下文可能并非所有任务都需要，因此令牌成本很高
• 引用整个文档：不可靠，浪费令牌，达到上下文限制
• 分别维护每个子代理：不必要的重复，难以保持一致

解决方案

使用类似符号的参考部分 §PREFIX.1 或 §PREFIX.2.3-5政策是按需提取的。你的标准保存在降价文件中。子代理总是能获得最新内容，而不会浪费代币。

主要优势

• 没有浪费上下文：只获取所需的部分，而不是整个文档
• 始终为最新：更新文件，更改会自动显示
• 自动分辨率：引用一个部分，获取它以及它引用的任何部分
• 快速查找：O（1）通过节索引检索
• 根据项目政策：相同的安装，每个项目不同的策略集

设置方法

选择 插件 用于Claude Code项目（最简单）。选择 钩子 如果您需要自定义策略路径或挂钩行为。选择 MCP 服务器 当子代理需要根据提示条件动态选择策略时，或者当使用其他兼容MCP的客户端时。选择 命令行界面 用于自动化脚本或非MCP集成。

快速入门：创建策略文件

所有方法都需要带有§符号的策略文件。创建策略目录和示例文件：

.claude/policies/policy-example.md （对于插件方法）或 ./policies/policy-example.md （其他方法）：

## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)

Build what you need now. Add features when needed, not in anticipation.

**Guidelines:**
- No speculative generalization
- No placeholder code for "future features"
- No abstraction without 3+ concrete use cases
- Delete unused code immediately

## {§DESIGN.2} Keep It Simple

See also §DESIGN.1 for related principles.

______________________________________________________________________

方法一：克劳德代码插件（推荐）

安装策略插件并创建策略文件。插件会自动配置钩子。

步骤1：安装插件

在Claude Code内部，运行以下命令一次：

/plugin marketplace add rcrsr/claude-plugins

然后安装策略插件：

/plugin install policies@rcrsr

策略文件应放置在 .claude/policies/ 在您的项目目录中。

步骤2：创建策略文件

将策略文件添加到 .claude/policies/:

.claude/policies/design.md:

## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)

Build what you need now. Add features when needed, not in anticipation.

**Guidelines:**
- No speculative generalization
- No placeholder code for "future features"
- No abstraction without 3+ concrete use cases
- Delete unused code immediately

## {§DESIGN.2} Keep It Simple

See also §DESIGN.1 for related principles.

步骤3：子代理中的参考策略

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
---

Required policies: §DESIGN.1, §DESIGN.2

You are a code reviewer following our team standards.
Apply the policies above when reviewing code.

步骤4：运行子代理

> @agent-code-reviewer review this PR

该插件拦截Task工具调用，从代理文件中提取§引用，并自动注入匹配的策略。

注： 代码围栏内的引用被忽略，允许您在不触发提取的情况下记录示例。

______________________________________________________________________

方法2:Claude代码挂钩

自定义策略路径或行为的手动挂钩配置。当Plugin方法为默认值时使用此选项 .claude/policies/*.md 路径不适合您的项目结构，或者在构建捆绑的插件时 mcp-policy-server 作为一种依赖。

插件作者： 钩子自动发现 $CLAUDE_PROJECT_DIR/.claude/{agents,policies} 和 $CLAUDE_PLUGIN_ROOT/{agents,policies} 当没有提供明确的路径时。您的插件可以调用 policy-hook 没有参数，它会自动找到插件捆绑和项目级代理/策略。

步骤1：配置钩子

添加到您的项目 .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Task",
      "hooks": [{
        "type": "command",
        "command": "npx -p @rcrsr/mcp-policy-server policy-hook --config \"./policies/*.md\""
      }]
    }]
  }
}

请确保在更新设置后重新启动Claude Code。

步骤2：创建具有策略引用的子代理

只要策略引用没有代码保护，实际格式就无关紧要。例如：

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
---

Required policies: §DESIGN.1, §DESIGN.2

You are a code reviewer following our team standards.
Apply the policies above when reviewing code.

步骤3：运行子代理

> @agent-code-reviewer review this PR

发生了什么：

1. Hook检测到带有代理文件的任务工具调用
2. policy-hook 从代理文件中提取所有§引用（§DESIGN.1，§DEDesign.2）
3. 策略被注入到包裹在其中的代理提示符中 `

` 标签

1. 子代理自动接收策略，无需明确的工具调用

注： 代码围栏内的引用被忽略，允许您在不触发提取的情况下记录示例。

仅前缀引用

使用仅前缀表示法获取具有给定前缀的所有部分：

Required: §DESIGN, §API

这扩大了 §DESIGN 致所有人 §DESIGN.* 部分和 §API 致所有人 §API.* 部分。

______________________________________________________________________

方法3:MCP服务器

子代理呼叫 fetch_policies 工具明确。在以下情况下使用此功能：

• 子代理需要根据提示内容动态选择策略
• 您正在使用除Claude Code之外的MCP兼容客户端
• 您需要验证工具(validate_references, extract_references)

步骤1：安装MCP服务器

Linux/macOS：

claude mcp add-json policy-server '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@rcrsr/mcp-policy-server"],
  "env": {"MCP_POLICY_CONFIG": "./policies/*.md"}}' \
  --scope project

窗户：

claude mcp add-json policy-server ('{' `
  '"type": "stdio", "command": "cmd",' + `
  '"args": ["/c", "npx", "-y", "@rcrsr/mcp-policy-server"], ' + `
  '"env": {"MCP_POLICY_CONFIG": "./policies/*.md"}}') `
  --scope project

步骤2：使用显式工具调用创建子代理

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
tools: mcp__policy-server__fetch_policies, Read, Glob
---

You are a code reviewer following our team standards.

**Before reviewing code:** call `mcp__policy-server__fetch_policies` with `{"sections": ["§DESIGN.1", "§DESIGN.2"]}`

步骤3：测试和运行

1. 重新启动Claude代码
2. 接受提示以启用MCP服务器
3. 跑 /mcp 验证“策略服务器”是否显示“已连接”
4. 跑 @agent-code-reviewer review this file

看 安装指南 详细设置。

______________________________________________________________________

方法4:CLI

使用 policy-cli 用于脚本、CI/CD或非MCP集成。

可用子命令

policy-cli fetch-policies         # Fetch policies for § refs in a file
policy-cli validate-references ... # Validate § refs exist
policy-cli extract-references     # Extract § refs from a file
policy-cli list-sources                 # List available policy files
policy-cli resolve-references ...  # Map § refs to source files

从文件中提取策略

npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies document.md --config "./policies/*.md"

摘录§参考文献 document.md，获取匹配的策略，输出到stdout。

在脚本中使用

# Inject policies into a prompt template
POLICIES=$(npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies agent.md --config "./policies/*.md")
echo "Follow these policies: $POLICIES" | your-llm-tool

# Validate references before use
npx -p @rcrsr/mcp-policy-server policy-cli validate-references §DOC.1 §DOC.2 --config "./policies/*.md"

______________________________________________________________________

MCP服务器工具

这些工具在使用时可用 方法3:MCP服务器.

示例用法：

{"sections": ["§PREFIX.1", "§PREFIX.2"]}

用例

• 代码审查：参考编码标准、风格指南、架构原则
• 部署：参考程序、安全检查表、回滚协议
• 文档：参考标准、模板、审查流程
• 测试：参考覆盖率要求、模拟模式、集成设置

文档

• 入门指南 -逐步设置所有四种方法
• 安装指南 -详细的安装选项
• 配置参考 -钩子、MCP和CLI的配置选项
• 政策参考 -§符号语法
• 最佳实践 -模式和策略

许可证

GPL-3.0或更高版本