Locker-MCP

A minimal Model Context Protocol (MCP) server for file locking and access control in AI code tools.

Overview

Locker-MCP prevents AI coding agents from repeatedly editing the same files by tracking file lock states and providing context-aware access control. When a file is "done," the LLM locks it via MCP, adding a comment header and saving metadata to prevent accidental changes.

Features

• File State Management: Track files as unlocked, locked-context, or locked
• Context Tracking: Store purpose/context descriptions for locked files
• Self-Evaluation: LLMs must assess confidence (0-100%) before editing locked-context files
• Audit Trail: Complete history of state transitions with timestamps
• Security: Path validation and local-only operation

Installation

npm install locker-mcp

Usage

As MCP Server

Start the server for use with MCP clients:

npx locker-mcp

Programmatic Usage

import { Locker } from 'locker-mcp';

const locker = new Locker();

// Lock a file with context
const result = locker.lockFile({
  filePath: 'src/auth.ts',
  context: 'Authentication module implementation'
});

// Check file state
const state = locker.getFileState({ filePath: 'src/auth.ts' });
console.log(state.state); // 'locked-context'

// Update file context
locker.updateFile({
  filePath: 'src/auth.ts',
  context: 'Enhanced authentication with 2FA',
  state: 'locked-context'
});

// Finalize file (no further edits)
locker.finalizeFile('src/auth.ts');

MCP Tools

The server exposes these tools for MCP clients:

• getFileState: Check current lock state of a file
• lockFile: Lock a file with context description
• unlockFile: Remove lock state from a file
• updateFile: Update file context and/or state
• finalizeFile: Mark file as fully locked
• getAllTrackedFiles: List all tracked files

File States

• unlocked: No restrictions, normal editing allowed
• locked-context: Locked with context, editable only if change aligns with context (≥80% confidence)
• locked: Fully locked, no edits allowed

Workflow Example

1. LLM completes work on a file
2. LLM calls lockFile with file path and context description
3. Locker adds // LOCKED: <UUID> STATE=locked-context comment to file
4. Metadata saved to .reporepo/locker/locker.json
5. Future edit attempts require confidence assessment
6. If confidence ≥80%, edit proceeds; otherwise rejected

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint
npm run lint

File Structure

.reporepo/locker/
└── locker.json    # Metadata with file states and history

Each entry contains:

• filePath: File path
• id: Unique identifier (UUID)
• state: Current lock state
• context: Purpose description
• history: Array of state changes with timestamps

Security

• All file operations are validated for path traversal attacks
• Only local project files can be modified
• No external network calls
• User maintains full control over all operations

License

MIT