agentleFS
Sign inStart free
0disoft0disoft/mcp-security-proxy/AGENTS.md

mcp-security-proxy

AGENTS.md2 starsChanged 4 months agoApache-2.0View on GitHub

Scope: general This repository owns the MCP Security Proxy project: a local proxy that sits in front of MCP servers and applies policy to tool discovery and tool calls before an AI agent can use them. It owns product requirements, architecture decisions, CLI contracts, library API contracts, policy and audit-log semantics, compatibility notes, and future implementation source for this tool when implementation work is explicitly requested. It does not own a general OS sandbox, malware scanner, enterprise SIEM, secret manager,…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository8 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

11 rules. About 3 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈3

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not claim this proxy is a complete OS sandbox.

    line 38
  2. Distinctive:

    Do not claim that tool schemas prove safety.

    line 39
  3. Common:

    Do not store raw secrets, environment values, prompt contents, or tool arguments in audit logs.

    line 41
  4. Common:

    Default examples must be deny-by-default and must require explicit allow rules for file, shell, network, and secret-sensitive capabilities.

    line 42
  5. Distinctive:

    Do not invent technology choices.

    line 44
  6. Common:

    Do not create fake credentials, tokens, secrets, or private values.

    line 45
  7. Distinctive:

    Do not rely on generated, cache, or build output as source truth.

    line 46
  8. Distinctive:

    Do not create large diffs that only change line endings.

    line 54
  9. Very specific:

    Read this file, VALIDATION.md, CHECKLIST.md, and .agents/context-map.md.

    line 58
  10. Distinctive:

    Read the skill and checklist named by the context map.

    line 59
  11. Distinctive:

    Call out API, DB, repository hygiene, and runner changes explicitly.

    line 75

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Repository Scope

Scope: general

This repository owns the MCP Security Proxy project: a local proxy that sits in front of MCP servers and applies policy to tool discovery and tool calls before an AI agent can use them.

It owns product requirements, architecture decisions, CLI contracts, library API contracts, policy and audit-log semantics, compatibility notes, and future implementation source for this tool when implementation work is explicitly requested.

It does not own a general OS sandbox, malware scanner, enterprise SIEM, secret manager, MCP server marketplace, or full agent runtime.

Repository Shape

Primary repository type: cli-tool Addons: library

  • cli-tool: owns proxy commands, policy dry-run commands, config loading, exit codes, terminal output, JSON output, and runtime compatibility.
  • library: owns the reusable policy engine, MCP message inspection contracts, audit event types, package compatibility, semantic versioning, migration guidance, and public API surface.

Source of Truth

  • Product scope: docs/product/02-spec.md
  • Architecture decisions: docs/adr/*.md
  • Validation: VALIDATION.md
  • Agent routing: .agents/context-map.md
  • Repository hygiene: .editorconfig, .gitattributes, .gitignore

Hard Rules

  • Do not claim this proxy is a complete OS sandbox. It controls the MCP protocol boundary only.
  • Do not claim that tool schemas prove safety. Tool classification must be treated as a heuristic unless backed by explicit policy.
  • Do not store raw secrets, environment values, prompt contents, or tool arguments in audit logs.
  • Default examples must be deny-by-default and must require explicit allow rules for file, shell, network, and secret-sensitive capabilities.
  • Do not invent technology choices. Use UNDECIDED when a decision is not known.
  • Do not create fake credentials, tokens, secrets, or private values.
  • Do not rely on generated, cache, or build output as source truth.

Repository Hygiene

  • .editorconfig sets line ending, encoding, and final newline policy.
  • .gitattributes sets Git text normalization and binary diff policy.
  • .gitignore excludes local, secret, build, and cache artifacts.
  • Generated, cache, and build output must not be used as design-document evidence.
  • Do not create large diffs that only change line endings.

Before Editing

  • Read this file, VALIDATION.md, CHECKLIST.md, and .agents/context-map.md.
  • Read the skill and checklist named by the context map.
  • Confirm source-of-truth documents before changing contracts.

Out of Scope

  • Full OS sandboxing, container isolation, kernel enforcement, or process-level containment.
  • Malware scanning and package reputation scoring.
  • Secret storage, rotation, or key-management backends.
  • MCP server marketplace, discovery catalog, or hosted control plane.
  • Enterprise SIEM integrations beyond exportable JSON audit events.
  • Project-specific credentials or deployment secrets.

Final Response Requirements

  • List executed validations, passed validations, skipped validations, skip reasons, and remaining risk.
  • Name any source-of-truth documents changed.
  • Call out API, DB, repository hygiene, and runner changes explicitly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free