mcp-agent-template

mcp-agent-template — 企业 MCP Agent 防护模板

英文摘要。 这是一个 MCP 服务模板，IT 部门可以让 LLM Agent 使用：每次工具调用都要经过允许列表策略（policy.yaml）、调用者角色（lecteur / operateur / admin，根据 MCP 工具注解决定）、各参数的允许值，以及针对破坏性操作的人工确认（MCP elicitation，支持 2025-11-25 和 2026-07-28 两种协议），并记录 JSONL 审计日志（权限模式为 0600，每次调用都有一个关联 ID）。mcp-agent-template 包附带两个可运行示例：一个企业示例（工单、只读的类 LDAP 目录、只读的 SQL 资产清单，全部使用本地虚构数据），以及一个通用运维示例（systemd 和 docker 状态查询、经确认后重启）。本地优先、可自托管、可在本地部署；无云服务、无遥测。采用双重许可：AGPL-3.0，或适用于任何规模公司的商业许可。

---

在企业中向 AI Agent 提供工具，总会引出相同的问题：谁有权做什么，谁批准了危险操作，以及记录在哪里。本仓库提供一个模板（“使用此模板”按钮），基于官方 MCP SDK，一次性解决这些问题。

防护机制的工作方式

每次工具调用都会依次经过以下检查：

1. 允许列表（policy.yaml）：不在列表中的工具会被拒绝。

2. 调用者角色：最低角色由工具类型决定，策略只能提高要求。

   工具类型	已发布的 MCP 注解	最低角色
   读取	readOnlyHint	只读者
   非破坏性写入	—	操作者
   破坏性操作	destructiveHint	管理员 + 人工确认

3. 允许的值：例如，只能重启特定的 systemd 单元。

4. 破坏性工具的人工确认：客户端向人工用户显示确认问题（MCP elicitation）。检查 1 至 3 会先通过：绝不会要求人工用户批准角色无权执行的操作。任何不是明确“是”的回应都视为拒绝，包括无法提出确认问题的客户端。

5. JSONL 审计日志，文件权限模式为 0600，每次调用都有一个关联 ID，用于关联决策、确认和结果。看起来像密钥的参数（password、token、api_key 等）会被隐藏。

拒绝操作时会向 Agent 返回易读的错误，绝不会伪装成成功。

试用

uvx mcp-agent-template --help
uvx mcp-agent-template serve --example enterprise   # tickets, annuaire, inventaire (donnees fictives)
uvx mcp-agent-template serve --example ops          # systemd et docker
uvx mcp-agent-template check-policy policy.yaml     # valide une politique et resume ses regles

在 MCP 客户端（Claude Code、Claude Desktop 等）中：

{
  "mcpServers": {
    "entreprise": {
      "command": "uvx",
      "args": ["mcp-agent-template", "serve", "--example", "enterprise"],
      "env": { "MCP_AGENT_TEMPLATE_ROLE": "operateur" }
    }
  }
}

变量	角色	默认值
MCP_AGENT_TEMPLATE_ROLE	调用者角色：lecteur、operateur、admin	lecteur
MCP_AGENT_TEMPLATE_CONFIRM	elicit：人工用户通过客户端确认；client：客户端自行确认（读取 destructiveHint）	elicit
MCP_AGENT_TEMPLATE_AUDIT_DIR	审计日志目录	~/.local/state/mcp-agent-template
MCP_AGENT_TEMPLATE_DATA_DIR	示例的 SQLite 数据库	~/.local/state/mcp-agent-template-demo

目前，角色来自客户端配置：每台设备或每个配置文件都有自己的角色。角色来源通过一个小型接口（RoleSource）实现：无需改动工具，即可接入基于令牌的身份验证。

示例

企业（--example enterprise），使用本地创建的虚构公司 “Exemple SA”数据，不连接任何外部服务：

• 支持：list_tickets、get_ticket、create_ticket（根据策略，“严重”优先级仅限人工设置）、close_ticket、delete_ticket （管理员权限 + 确认）；
• 只读目录，类似 LDAP：search_directory、get_user、 group_members；
• 只读 SQL 库存：list_tables、query_inventory。有两道防护：数据库以 mode=ro 模式打开，且 SQLite 授权器会拒绝任何写入、 PRAGMA 或 ATTACH 操作，即使它们隐藏在 WITH 中也不例外。

运维（--example ops）：只读的 service_status 和 list_containers， 以及受策略限制、仅可操作列出的单元并须确认后执行的 restart_service。

编写自己的服务

from mcp.server.mcpserver import MCPServer
from mcp_agent_template import Guard, Policy, ToolKind

server = MCPServer("mon-agent")
guard = Guard(server, Policy.load("policy.yaml"))

@guard.tool(ToolKind.READ, title="Lister les commandes")
def list_orders(status: str = "ouverte") -> list[dict]:
    """Commandes du jour."""
    ...

@guard.tool(ToolKind.DESTRUCTIVE, title="Annuler une commande")
def cancel_order(order_id: int) -> dict:
    """Annule une commande (admin + confirmation humaine)."""
    ...

server.run()

# policy.yaml
version: 1
default: deny
tools:
  list_orders: {}
  cancel_order:
    allowed_values:
      order_id: ["1042", "1043"]

要接入真正的工单工具、真正的 LDAP 目录或真正的数据库，只需替换 src/mcp_agent_template/examples/stores.py 中的类：MCP 工具和 防护机制无需更改。

开发

uv sync
uv run pytest        # garde, politique, audit, exemples, protocoles 2025-11-25 et 2026-07-28, stdio
uv run ruff check src tests

项目提供了 devcontainer（.devcontainer/）。

许可证

双重许可：

• AGPL-3.0（LICENSE）：个人、协会以及教育或研究用途可免费使用；
• 商业许可证，面向各种规模的企业： 参见 COMMERCIAL-LICENSE.md。

贡献须遵循 CLA.md 中的协议。

属于 Lyra 生态系统的一部分

采用与 fedora-agents （带关联 ID 的审计日志、MCP 注释）和 Lyra 相同的理念；后者是一款以法语为先的语音助手， 会在每次敏感操作前要求人工确认。