mcp-text-editor: Instructions file for Codex

AGENTS.md - MCP Text Editor Server

This document provides guidance for AI coding agents working on this codebase.

Project Overview

MCP Text Editor Server is a Python MCP (Model Context Protocol) server providing line-oriented text file editing capabilities. It's optimized for LLM tools with efficient partial file access to minimize token usage.

Build System

Package manager: uv with hatchling as build backend.

Essential Commands

# Install dependencies
make install              # or: uv sync --all-extras

# Run all tests
make test                 # or: uv run pytest

# Run a single test file
uv run pytest tests/test_text_editor.py -v

# Run a single test function
uv run pytest tests/test_text_editor.py::test_calculate_hash -v

# Run tests matching a pattern
uv run pytest -k "test_edit" -v

# Run tests with coverage
make coverage

# Format code
make format

# Lint + typecheck
make check

# Format + typecheck + coverage (default)
make all

Project Structure

src/mcp_text_editor/
├── server.py             # FastMCP server implementation
├── text_editor.py        # Core text editor functionality
├── service.py            # Core service logic
├── models.py             # Pydantic data models
├── utils.py              # Security utilities (path validation, file locking)
└── handlers/             # MCP tool handlers (inherit from base.py)
tests/                    # Test files (pytest)

Code Style Guidelines

Formatting & Linting

• Line length: 88 characters (Black)
• Formatter: Black (Python 3.13 target)
• Import sorting: isort with "black" profile
• Linter: Ruff (pycodestyle, pyflakes, isort, flake8-comprehensions, flake8-bugbear)

Imports

# 1. Standard library
from typing import Any, Dict, List, Optional, Sequence, Tuple

# 2. Third-party
from mcp.types import TextContent
from pydantic import BaseModel, Field, model_validator

# 3. Local (relative imports within package)
from ..text_editor import TextEditor
from .base import BaseHandler