Agent Permission Broker

Least-privilege scope planning for tools, MCP servers, and agent chains.

Version: 1.0.0 | License: MIT | Status: production-oriented v1 foundation

Problem

Agents often receive broad tools, broad tokens, and broad autonomy, turning model mistakes into real-world damage.

What this project solves

A scope planner that compares requested operations with minimal permissions, flags omnibus scopes, and recommends approval gates.

Agent Permission Broker ships as a small, dependency-free CLI and library. It validates a domain-specific JSON packet, emits actionable findings, and gives contributors a concrete surface for adding adapters, richer checks, schemas, and integrations.

Who it is for

Agent platform engineers, MCP server authors, security architects.

Quick start

npm test
npm start -- sample

Analyze your own packet:

agent-permission-broker ./packet.json

Or pipe JSON:

cat packet.json | node src/cli.js

Example packet

{
  "task": "summarize invoices",
  "requestedScopes": [
    "email.read",
    "drive.read",
    "payments.write"
  ],
  "tools": [
    {
      "name": "drive",
      "operation": "read"
    },
    {
      "name": "payments",
      "operation": "none"
    }
  ]
}

Library usage

const { analyze } = require("./src/index.js");

const report = analyze({
  "task": "summarize invoices",
  "requestedScopes": [
    "email.read",
    "drive.read",
    "payments.write"
  ],
  "tools": [
    {
      "name": "drive",
      "operation": "read"
    },
    {
      "name": "payments",
      "operation": "none"
    }
  ]
});
console.log(report.summary);

v1 behavior

• Validates required fields for the domain packet.
• Scores readiness from 0 to 100.
• Reports missing or weak governance evidence.
• Suggests next actions and contributor extension points.
• Runs fully offline with no API keys and no network access.

Contribution map

Good first contributions:

• Add OAuth challenge helpers.
• Add MCP scope catalogs.
• Add policy diffing.
• Add agent-chain delegation maps.

Larger contributions:

• Add a JSON Schema and compatibility tests.
• Build import/export adapters for popular AI frameworks.
• Add real-world fixtures from public, non-sensitive examples.
• Improve scoring with transparent, documented heuristics.

Project principles

• Human agency over blind automation.
• Open standards over vendor lock-in.
• Auditable decisions over hidden magic.
• Privacy and safety as design constraints, not release notes.

GitHub Pages

The marketing site lives in site/index.html. Enable GitHub Pages from the site folder or use the included Pages workflow after publishing.

Security

This project does not process secrets by default. If you build adapters that touch production systems, keep least privilege, explicit consent, and auditable logs in the design.