Agent Bound

代理人绑定

实验性 --MCP服务器的访问控制框架，灵感来自 AgentBound 研究论文。

agent-bound 将Android风格的声明性权限引入 模型上下文协议（MCP） 服务器。每个MCP服务器都会发送一个清单，声明它需要的系统资源。在运行时，策略执行引擎将服务器限制为仅使用这些资源，从而将生态系统从 *默认信任* 朝向 *最低特权*.

状态

这是一个 实验参考实施 用于研究和原型制作。它没有生产硬化。权限词汇表和清单格式可能会更改。

概述

该框架有三个组成部分，反映了论文的架构：

运作原理

┌──────────────────────────────────────────────────────────────┐
│  MCP Server Codebase                                         │
│                                                              │
│  ┌───────────────────┐     ┌──────────────────────────────┐  │
│  │ AgentManifestGen  │────▶│ agent-manifest.json          │  │
│  │ (source analysis) │     │ {                            │  │
│  └───────────────────┘     │   "description": "...",      │  │
│                            │   "permissions": [           │  │
│                            │     "mcp.ac.filesystem.read",│  │
│                            │     "mcp.ac.network.client"  │  │
│                            │   ]                          │  │
│                            │ }                            │  │
│                            └──────────────┬───────────────┘  │
└───────────────────────────────────────────┼──────────────────┘
                                            │
                                            ▼
┌──────────────────────────────────────────────────────────────┐
│  AgentBox (Policy Enforcement Engine)                        │
│                                                              │
│  1. Load manifest                                            │
│  2. Resolve generic → effective permissions (with overrides) │
│  3. Request user consent                                     │
│  4. Launch MCP server in sandboxed environment               │
│  5. Enforce: filtered env, scoped fs, network allow-list     │
│  6. Audit all access attempts                                │
└──────────────────────────────────────────────────────────────┘

安装

npm install agent-bound

或者克隆并从源代码构建：

git clone 
cd agent-bound
npm install
npm run build

许可词汇

权限使用 mcp.ac.. 命名约定：

该词汇表在296台真实世界的MCP服务器上进行了验证（见 纸张评价).

用法

命令行界面

# List all permissions in the vocabulary
agent-bound permissions

# Validate a manifest file
agent-bound validate ./agent-manifest.json

# Inspect a manifest (human-readable output with effective policy)
agent-bound inspect ./agent-manifest.json

# Auto-generate a manifest from source code
agent-bound generate ./my-mcp-server/ -o agent-manifest.json -d "My server description"

# Launch an MCP server with enforcement
agent-bound run ./agent-manifest.json -- node server.js

程序化API

创建和验证清单

import {
  createManifest,
  validateManifest,
  saveManifest,
  loadManifest,
  FILESYSTEM_READ,
  NETWORK_CLIENT,
  SYSTEM_ENV_READ,
} from "agent-bound";

// Create a manifest
const manifest = createManifest(
  "My MCP server that reads config files and calls external APIs",
  [FILESYSTEM_READ, NETWORK_CLIENT, SYSTEM_ENV_READ],
);

// Validate arbitrary JSON
const result = validateManifest(someJsonData);
if (!result.valid) {
  console.error(result.errors);
}

// Persist and load
await saveManifest(manifest, "./agent-manifest.json");
const loaded = await loadManifest("./agent-manifest.json");

政策决议和执行

import {
  loadManifest,
  resolvePolicy,
  PermissionChecker,
  AuditLog,
} from "agent-bound";

const manifest = await loadManifest("./agent-manifest.json");

// Resolve generic permissions into scoped effective permissions
const effective = resolvePolicy(manifest, {
  readPaths: ["/data/project"],
  allowedHosts: ["api.example.com"],
  envVars: ["API_KEY", "NODE_ENV"],
});

// Create a checker for runtime enforcement
const audit = new AuditLog();
const checker = new PermissionChecker(effective, audit);

checker.checkFileRead("/data/project/config.json"); // true
checker.checkFileRead("/etc/passwd");                // false
checker.checkNetworkClient("api.example.com");       // true
checker.checkNetworkClient("evil.com");              // false
checker.checkEnvRead("API_KEY");                     // true
checker.checkEnvRead("DATABASE_URL");                // false

// Review denied attempts
for (const entry of audit.denied()) {
  console.log(`DENIED: ${entry.permission} → ${entry.resource}`);
}

启动沙盒MCP服务器

import { loadManifest, createAgentBox } from "agent-bound";

const manifest = await loadManifest("./agent-manifest.json");

const box = createAgentBox({
  manifest,
  command: ["node", "my-mcp-server.js"],
  overrides: {
    readPaths: ["/data/shared"],
    allowedHosts: ["api.example.com"],
    envVars: ["API_KEY"],
  },
});

// The server process runs with a filtered environment
// Only declared env vars are visible; PATH is restricted

// Dynamic checks during operation
box.checker.checkFileRead("/data/shared/doc.txt"); // true

// Shut down
box.stop();

// Review audit log
console.log(box.audit.toJSON());

从源代码自动生成清单

import { generateManifest } from "agent-bound";

const result = await generateManifest("./path/to/mcp-server", "My MCP server");

console.log(`Scanned ${result.filesScanned} files`);
for (const detection of result.detections) {
  console.log(`${detection.permission} (${detection.matchCount} matches)`);
  console.log(`  Rationale: ${detection.rationale}`);
}

console.log(JSON.stringify(result.manifest, null, 2));

清单格式

一 agent-manifest.json 文件：

{
  "description": "Filesystem MCP server with read-only access to project files.",
  "permissions": [
    "mcp.ac.filesystem.read"
  ]
}

一个更完整的示例（浏览器自动化服务器）：

{
  "description": "Playwright MCP server providing browser automation. Launches browsers, navigates pages, takes screenshots, and writes artifacts to disk.",
  "permissions": [
    "mcp.ac.filesystem.read",
    "mcp.ac.filesystem.write",
    "mcp.ac.system.env.read",
    "mcp.ac.network.client",
    "mcp.ac.system.exec"
  ]
}

看 examples/ 更多明显的例子。

通用权限与有效权限

该框架使用两层权限模型：

1. 通用权限 在舱单上申报(mcp.ac.filesystem.read).他们说 *哪种* 需要访问权限。

1. 有效权限 在启动时由操作员解决。它们将每个通用权限范围限定为具体资源：

// Generic: "this server needs filesystem read access"
// Effective: "it can read /data/project and /tmp, nothing else"

const effective = resolvePolicy(manifest, {
  readPaths: ["/data/project", "/tmp"],
  allowedHosts: ["api.example.com"],
  envVars: ["API_KEY"],
  listenPorts: [3000],
  allowedCommands: ["node", "npx"],
});

这种分离允许清单作者声明意图，而操作员则保持对实际范围的控制。

项目结构

agent-bound/
├── src/
│   ├── permissions.ts          # Permission vocabulary (mcp.ac.* constants)
│   ├── index.ts                # Public API re-exports
│   ├── manifest/
│   │   ├── schema.ts           # AgentManifest types and validation
│   │   └── index.ts            # Manifest I/O (load, save, create)
│   ├── box/
│   │   ├── policy.ts           # Generic → effective permission resolution
│   │   ├── sandbox.ts          # Process sandbox launcher
│   │   ├── checker.ts          # Runtime permission checker
│   │   ├── audit.ts            # Audit logging
│   │   └── index.ts            # AgentBox high-level API
│   ├── gen/
│   │   ├── heuristics.ts       # Source-code pattern detection
│   │   └── index.ts            # Manifest generation pipeline
│   └── cli/
│       └── index.ts            # CLI entry point
├── tests/                      # Vitest test suite
├── examples/                   # Example manifests and usage code
├── package.json
└── tsconfig.json

发展

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run tests
npm run dev          # Watch mode compilation

局限性

• 仅在流程级别执行。 当前的沙盒过滤环境并限制PATH，但不使用操作系统级隔离（命名空间、seccomp、cgroups）。为了获得更强的保证，请在容器运行时内运行。
• 静态启发式分析。 AgentManifestGen 使用模式匹配，而不是完整的程序分析。它可能会产生误报或错过通过动态模式访问的权限。
• 无运行时拦截。 这 PermissionChecker 是咨询性的——它评估一个行动是否 *应该* 允许，但不拦截系统调用。搭配一个真正的沙盒来执行。

封学术推荐信

该项目的灵感来源于：

克里斯托弗·布勒、马泰奥·比亚焦拉、卢卡·迪·格拉齐亚和吉多·萨尔瓦内斯基。 “保护AI代理执行。” arXiv预印本arXiv:2510.212362025。 https://arxiv.org/abs/2510.21236

本文介绍了AgentBund，这是MCP服务器的第一个访问控制框架，它将声明性策略机制（受Android权限模型的启发）与策略执行引擎相结合。他们对296台流行的MCP服务器的评估表明，清单可以自动生成，准确率为80.9%，权限词汇表覆盖了100%的实际需求，执行开销可以忽略不计（平均0.6毫秒）。

许可证

麻省理工学院