locker-mcp/README.md

MCP server for file locking and access control for AI code tools

# 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

```bash
npm install locker-mcp
```

## Usage

### As MCP Server

Start the server for use with MCP clients:

```bash
npx locker-mcp
```

### Programmatic Usage

```typescript
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

```bash
# 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