Skip to main content
Glama
preprint-labs

PolicyPin

by preprint-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

PolicyPin đź“Ś

Stop your AI coding agent from forgetting its rules after context compaction.

Runs as a local, zero-config MCP server. It pulls rules from your repo, isolates them from lossy context summarization, and blocks violating actions in <1ms before they touch your disk.

(Currently in pre-release testing before public npm registry deployment).

The Problem: Governance Decay

In long sessions, tools like Cursor, Claude Code, and Copilot compact (summarize) conversation history to free up context tokens.

When that happens, the summarizer prioritizes recent conversational chatter and quietly drops negative constraints ("never edit package.json", "don't touch .env"). Researchers call this Governance Decay (arXiv:2606.22528), showing that rule violations jump from ~0% to over 40% post-compaction.

PolicyPin fixes this deterministically: it reads your rules, holds them on an immutable plane, and intercepts actions before execution. No API keys, no external calls, zero token drift.

Silent Lock

MCP is just how it boots. Point your editor to the built script and you're done:

  • File Protection (Kernel Level): On boot, PolicyPin flips forbidden paths to OS read-only (attrib +r on Windows, chmod 444 on macOS/Linux). Cursor Composer or native IDE tools can try an internal write and will still get EACCES / EPERM, even if the model forgets to call MCP.

  • Command Protection (Tool Level): Restricted commands (rm -rf, git push --force) are intercepted and blocked at the MCP gatekeeper boundary before execution.

  • Safe Exit: When the editor disconnects or the process exits, file locks come off cleanly so you can edit normally. Silent Lock is a protective read-only flag, not an ACL jail—a human can always attrib -r or chmod manually.

Quick Setup (From Source)

Because PolicyPin is currently in v0.1 pre-release, build it locally in 30 seconds:

git clone https://github.com/preprint-labs/policypin.git
cd policypin
npm install
npm run build

Installation in Editors

Cursor (Option A: GUI - Recommended)

  1. Open Cursor Settings (Ctrl + Shift + J or Cmd + Shift + J).

  2. Go to Features -> MCP Servers -> + Add New MCP Server.

  3. Set:

    • Name: policypin

    • Type: command

    • Command: node <FULL_PATH_TO_POLICYPIN>/dist/index.js (e.g., node "C:\Users\username\Documents\policypin\dist\index.js" or node /Users/username/policypin/dist/index.js)

Cursor (Option B: JSON)

Add to your cursor-settings.json under mcpServers:

{
  "mcpServers": {
    "policypin": {
      "command": "node",
      "args": ["<FULL_PATH_TO_POLICYPIN>/dist/index.js"]
    }
  }
}

Claude Code (Terminal)

claude mcp add policypin -- node <FULL_PATH_TO_POLICYPIN>/dist/index.js

GitHub Copilot (VS Code)

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcpServers": {
    "policypin": {
      "command": "node",
      "args": ["<FULL_PATH_TO_POLICYPIN>/dist/index.js"]
    }
  }
}

(Once v0.1.0 is published to the public registry, installation will be a single npx -y policypin command).

Auto-Detected Rule Files

PolicyPin checks your workspace root for any of the following:

Tool

Rule File

Cursor

.cursorrules or .cursor/rules/*.mdc

Claude Code

CLAUDE.md

GitHub Copilot

.github/copilot-instructions.md

Codex / Generic

AGENTS.md or .rules

(Pass --rules path/to/rules.txt to pin a specific file).

Supported Rule Syntax

PolicyPin parses standard natural language heuristics and globs out of your rule file:

# File and directory locks
Never edit package.json directly; always use npm.
Do not modify any file matching .env*
Forbidden directory: /infra/credentials/**

# Command locks
Forbidden command: rm -rf
Never run git push --force

# Explicit tagging (optional)
<!-- policy:pin -->
Must always preserve MIT license headers in /src
<!-- policy:unpin -->

30-Second Verification

  1. Add this line to your project's rule file (e.g. .cursorrules or CLAUDE.md):

    Never edit secrets.txt

  2. Ask your AI: "Create a dummy password and save it in secrets.txt."

  3. The write will immediately fail:

    🛑 [PolicyPin Blocked]: Target 'secrets.txt' violates rule: 'Never edit secrets.txt'.

Empirical Validation

We ran a ConstraintRot-style probe suite against the Silent Lock matcher/guard plus an OS write verification after attrib +r. That is the direct measurement from this machine.

The baseline figures below are not ours—they are published measurements from the Governance Decay paper (arXiv:2606.22528) showing baseline model compliance decaying across session turns (Fresh: 98.2% → Deep Context: 68.6% → Post-Compaction: 57.7%).

Metric

PolicyPin (Local Eval)

Paper Baselines (arXiv:2606.22528)

Enforcement

8/8 must-block probes (100%)

98.2% (Turn 1) → 57.7% (Post-compaction)

False Alarms

0

—

Avg Latency

0.561 ms

—

OS Kernel Deny

Verified (EPERM / EACCES)

❌ Failed (native file writes succeed)

  • Scope probes covered: package.json, .env / .env.production / .env.local, and config/credentials/master.key (including Windows backslash paths).

  • Command probes covered: git push --force and rm -rf.

  • Precision probes: Legitimate targets (README.md, src/index.ts, git status, git push without --force) remained fully allowed with zero false alarms.

Re-run the benchmark:

npm test

License

MIT

Available Tools

2 tools
policypin_checkA

Pre-flight PolicyPin check. Call before file edits, commands, or sensitive reads. A blocked result is mandatory.

ParametersJSON Schema
NameRequiredDescriptionDefault
intentNoWhat the agent plans to do
targetYesFile path, URI, or command to evaluate

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of disclosing behavioral traits. It does mention that a 'blocked result is mandatory,' which hints at the tool returning a status or decision. However, it does not explicitly state whether the tool is read-only, what the exact output format is, or how to interpret a non-blocked result. This is a partial disclosure but lacks completeness for a pre-flight check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise and well-structured. It front-loads the purpose ('Pre-flight PolicyPin check'), provides explicit usage timing, and states the key behavioral requirement in three short sentences. There is no redundant or extraneous content, making it easy for an agent to parse and act on quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and no annotations, so the description must convey how the agent should use the result. It mentions 'blocked result' but does not explain the response structure, error handling, or what constitutes a successful (non-blocked) outcome. While the usage context is clear, the lack of return format information leaves a notable gap for an agent that needs to programmatically handle the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers both parameters fully: intent ('What the agent plans to do') and target ('File path, URI, or command to evaluate'). The description adds no additional semantic information about these parameters, so it does not exceed the baseline established by the schema. Since schema coverage is 100%, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a 'Pre-flight PolicyPin check' with a specific purpose: to be called before file edits, commands, or sensitive reads. This distinguishes it from the sibling policypin_list, which presumably lists policies, and provides a specific verb (check) and resource (PolicyPin). The purpose is unambiguous and immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly specifies when to call the tool: before file edits, commands, or sensitive reads. It also adds a crucial behavioral constraint: 'A blocked result is mandatory,' indicating the agent must respect the outcome. This provides clear, actionable usage guidance without ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

policypin_listA

List constraints currently pinned by PolicyPin. Read-only.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states 'Read-only,' which is a behavioral trait, but it does not disclose the return format or any other behavioral details such as pagination or ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence, front-loading the core action ('List constraints') and adding the read-only note. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is fairly complete. It states what it does and that it is read-only. It might have mentioned the absence of return details, but given the simplicity, it's adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parametersholistically, so there is nothing to document. The schema has 100% coverage (empty), and the description adds no extra parameter semantics, which is acceptable given no parameters exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists constraints pinned by PolicyPinheb, specifying the verb 'list' and the resource 'constraints pinned by PolicyPin'. It does not explicitly distinguish from the sibling policypin_check, but the purpose is evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus policypin_check. However, the name and description imply it is for listing, while policypin_check likely checks something, so usage is implied but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedpolicypin_check
    • First observedpolicypin_list
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one performs a pre-flight check, the other lists pinned constraints. There is no overlap or ambiguity between them.

Naming Consistency4/5

Both tool names follow a consistent pattern using 'policypin' as a prefix followed by an action verb ('check', 'list'), which is predictable. Minor deviation from 'verb_noun' but internally consistent.

Tool Count4/5

With only 2 tools, the server feels thin for a policy management system. However, for its narrow scope (pre-flight checks and listing constraints), the count is reasonable, though it might benefit from more tools to cover additional functionality.

Completeness2/5

The tool surface is missing obvious operations for managing constraints, such as adding, removing, or updating pinned rules. Without these, agents cannot modify policy, which is a significant gap for a policy management server.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Waymark by waymarks

    Waymarkofficial

    waymarks
    F
    license
    Not graded
    quality
    A
    maintenance
    MCP server that intercepts and controls AI agent actions in your codebase by enforcing policies on file operations and commands, with logging, approval workflows, and rollback capabilities.
    -

  • gov-mcp

    liuhaotian2024-prog
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enforces runtime governance on AI agent actions — file access, command execution, delegation chains, and permission escalation.
    MIT

  • safe-code-mcp

    marcojourney
    F
    license
    Not graded
    quality
    D
    maintenance
    A local MCP server that provides controlled repository access with policy-based file filtering, secret redaction, and audit logging for AI coding agents.
    -

  • universal-mcp-fs

    Prabhas125
    A
    license
    A
    quality
    C
    maintenance
    A secure local MCP server that provides AI assistants controlled filesystem access and command execution with an interactive approval system for dangerous actions.
    17
    7 npm
    MIT