devin-resource-guard-mcp

A Model Context Protocol (MCP) server for autonomous coding agents such as Devin, Cursor, and Claude Code. It runs over stdio and targets two common failure modes in long agent sessions: context bloat and out-of-memory (OOM) crashes.

Features

• Resource headroom checks: On each call, it reports memory, CPU, and disk headroom. Inside a container, it reads the cgroup memory limit from /sys/fs/cgroup (v1 and v2), so the numbers reflect the container rather than the host. When effective free memory falls below a threshold (500 MB by default), it returns a structured NEAR_OOM_THRESHOLD warning with recommended actions. The agent can then back off before the OOM killer or a cgroup limit ends its process.

• Workspace context optimization: It scans a workspace for token-heavy, low-value paths such as dependency trees, build output, large logs, binary artifacts, minified bundles, and lockfiles. It ranks them by estimated token cost and returns exclude_globs that keep them out of the agent's context.

Works with any MCP client, including Devin, Claude Desktop, Claude Code, Cursor, and VS Code. This is an independent project, not affiliated with Cognition.

Tools

inspect_resource_limits

It returns memory (total, available, and cgroup-aware effective available), CPU utilisation and load average, and disk usage.

status takes one of three values:

Example of the low-memory warning:

{
  "status": "warning",
  "alert": {
    "code": "NEAR_OOM_THRESHOLD",
    "severity": "critical",
    "message": "Only 412.3 MB of memory is available (threshold 500.0 MB). The process is at risk of being killed by the OOM killer or a cgroup memory limit.",
    "available_bytes": 432324608,
    "threshold_bytes": 524288000,
    "cgroup_limited": true,
    "recommended_actions": [
      "Pause spawning new subprocesses, builds, or test runners.",
      "Run memory-heavy commands serially with reduced parallelism (e.g. -j1, --runInBand, --maxWorkers=1).",
      "..."
    ]
  },
  "memory": { "...": "..." },
  "cpu":    { "...": "..." },
  "disk":   { "...": "..." },
  "alerts": [ "..." ]
}

Inside a container, the server reads /sys/fs/cgroup (v1 and v2), so the warning reflects the container's limit rather than the host's total RAM.

optimize_workspace_context

The scan detects:

The response ranks findings by size and estimated token cost (about 4 bytes per token). It also includes exclude_globs that you can paste into .cursorignore, .aiignore, or an agent's deny list:

{
  "status": "ok",
  "summary": {
    "findings": 7,
    "excludable_size": "1.8 GB",
    "estimated_tokens_saved": 483183820
  },
  "exclude_globs": ["**/node_modules/", "**/dist/", "logs/server.log", "**/*.log"],
  "findings": [
    { "path": "node_modules/", "kind": "bloat_directory", "size": "1.2 GB", "estimated_tokens": 322122547, "already_ignored": false }
  ]
}

The scanner reads .gitignore, .cursorignore, .codeiumignore, .aiignore, and .dockerignore at the root, so by default it reports only paths that are not yet ignored.

Related MCP server: DevTwin MCP

Quick start

Requires Python 3.10+.

git clone https://github.com/crona16/devin-resource-guard-mcp.git
cd devin-resource-guard-mcp
python -m venv .venv

Activate the virtualenv:

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Install the dependencies:

pip install -r requirements.txt

Confirm that the server starts. It will wait silently on stdin, and you can stop it with Ctrl+C:

python server.py

To exercise the tools interactively, use the official MCP Inspector. It needs Node.js:

npx @modelcontextprotocol/inspector .venv/bin/python server.py

Connecting to an agent

Every client below takes the same two things:

1. command: the absolute path to the virtualenv's Python interpreter.

   • macOS / Linux: /abs/path/devin-resource-guard-mcp/.venv/bin/python

   • Windows: C:\\abs\\path\\devin-resource-guard-mcp\\.venv\\Scripts\\python.exe

2. args: the absolute path to server.py.

Use absolute paths. GUI apps don't inherit your shell's PATH or working directory, so a bare python often resolves to the wrong interpreter, one without mcp installed.

Cursor

Edit ~/.cursor/mcp.json to make the server available globally, or .cursor/mcp.json in a project to scope it to that project:

{
  "mcpServers": {
    "context-guard": {
      "command": "/abs/path/devin-resource-guard-mcp/.venv/bin/python",
      "args": ["/abs/path/devin-resource-guard-mcp/server.py"],
      "env": {
        "CONTEXT_GUARD_LOW_MEMORY_MB": "500"
      }
    }
  }
}

Then open Settings → MCP and confirm that context-guard shows a green dot with 2 tools.

Devin (Desktop / local MCP)

Add the server through Devin's MCP settings (Settings → MCP servers → Add custom server) as a stdio server:

If your Devin build accepts a JSON config instead, use the same mcpServers block as in the Cursor example. The exact menu path varies between Devin releases, so check Devin's MCP documentation if the menu items above don't match.

Claude Desktop

Edit the config file for your platform:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the same mcpServers block as in the Cursor example, then restart the app.

Claude Code

claude mcp add context-guard -- /abs/path/devin-resource-guard-mcp/.venv/bin/python /abs/path/devin-resource-guard-mcp/server.py

VS Code (Copilot agent mode)

Create .vscode/mcp.json:

{
  "servers": {
    "context-guard": {
      "type": "stdio",
      "command": "${workspaceFolder}/../devin-resource-guard-mcp/.venv/bin/python",
      "args": ["${workspaceFolder}/../devin-resource-guard-mcp/server.py"]
    }
  }
}

Suggested agent rule

Add a rule like this to your agent's rules or system prompt so it actually uses the tools:

Before starting a build, test suite, or large refactor, call inspect_resource_limits. If status is warning, follow alert.recommended_actions before continuing. When you open a new workspace, call optimize_workspace_context once, and never read paths that match its exclude_globs.

Configuration

All settings are optional environment variables:

Design notes

• stdout is used only for the protocol. All logging goes to stderr, and the code never calls print(). Errors are returned as structured {"status": "error", "error": {...}} payloads instead of being raised, so one bad path doesn't kill the session.

• The event loop stays free. psutil sampling and filesystem walks run in asyncio.to_thread.

• The scanner is safe by default. It never follows symlinks, it never descends into bloat directories (it only measures their size), it is bounded by time and file-count budgets, and it can be confined with CONTEXT_GUARD_ALLOWED_ROOTS.

• The scanner is read-only. It deletes or modifies nothing. It only returns recommendations.

Limitations

• Ignore-file matching is a lightweight fnmatch approximation, not a full gitignore engine. Negation (!pattern) is skipped. The matching only affects the already_ignored flag, never what gets scanned.

• Token estimates use a fixed rate of about 4 bytes per token. Treat them as an order of magnitude.

• Generic directory names such as bin/, out/, env/, and vendor/ are flagged by name alone. Review findings before you exclude them.

License

MIT