@toolshed/policy

The policy package provides the authorization layer for Toolshed — filtering tools by role and resolving whether tools require approval.

filterToolsByRole(tools, role)

Returns only the tools whose paths match at least one pattern in the role:

import { filterToolsByRole } from "@toolshed/policy";

const visibleTools = filterToolsByRole(allTools, {
  id: "developer",
  name: "Developer",
  patterns: ["github.**", "slack.channels.list"],
});

matchPattern(toolPath, pattern)

Tests whether a tool path matches a glob pattern:

import { matchPattern } from "@toolshed/policy";

matchPattern("github.issues.create", "github.issues.*");  // true
matchPattern("github.issues.create", "github.**");         // true
matchPattern("github.issues.create", "linear.**");         // false
matchPattern("github.issues.create", "*");                 // true

Algorithm: recursive segment-by-segment matching.

* matches exactly one segment
** matches zero or more segments

resolveAnnotations(tool)

Derives whether a tool requires user approval based on its metadata:

import { resolveAnnotations } from "@toolshed/policy";

const annotations = resolveAnnotations(tool);
// { requiresApproval: true, reason: "HTTP method POST is not safe" }

Resolution priority (first match wins):

Source	Logic
OpenAPI	`metadata.httpMethod` — GET, HEAD, OPTIONS are safe
GraphQL	`metadata.operationType` — `query` is safe, `mutation` requires approval
MCP	`metadata.mcpAnnotations.destructiveHint`
Plugin	Falls back to `tool.destructive` field

Return type

interface ToolAnnotations {
  requiresApproval: boolean;
  reason?: string;
}

Package Reference

Reference

filterToolsByRole(tools, role)

matchPattern(toolPath, pattern)

resolveAnnotations(tool)

Return type

​filterToolsByRole(tools, role)

​matchPattern(toolPath, pattern)

​resolveAnnotations(tool)

​Return type

filterToolsByRole(tools, role)

matchPattern(toolPath, pattern)

resolveAnnotations(tool)

Return type