easy-code-reader: Instructions file for GitHub Copilot

Copilot Instructions for Easy Code Reader

Architecture

The stdio MCP server exposes exactly search_group_id and read_jar_source.

• server.py: schemas, MCP responses, guide resource; failures use CallToolResult(isError=True).
• service.py: source-first reading and fallback orchestration.
• repository.py: strict Maven resolution, normalized SNAPSHOT input with timestamp-based cache names, fresh repository searches without an in-memory result cache.
• versions.py: Maven ComparableVersion semantics; see NOTICE for attribution.
• source.py: class checks, strict UTF-8 source extraction, internal-class mapping and inclusive line ranges.
• decompiler.py: asynchronous Java child processes, compatible fallback, timeout and cancellation.
• cache.py: JAR-name disk caches, size/mtime validation, atomic publication and LRU cleanup; no hashes or file locks.
• config.py: immutable per-server settings. io_utils.py waits for cancelled file workers before workspace cleanup.

Behavioral Contracts

• Prefer the ordinary SNAPSHOT JAR as input; use the newest timestamped main JAR name (timestamp plus numeric build number) for its cache. Fall back to that timestamped JAR when the ordinary input is absent; use the ordinary filename when no timestamps exist.
• For ordinary SNAPSHOT inputs, prefer ordinary sources, then matching timestamped sources. Timestamped inputs use matching sources. Source-only repositories are readable when prefer_sources=True.
• Never substitute tests/all classifier JARs or files outside the configured repository.
• Internal names use Outer$Inner; include a short warning when returning an outer file.
• Omitted line limits return the complete original text using only class_name, artifact, source_type and code; line metadata appears only for explicit ranges.
• Never manufacture Java source on failure. Return a stable error code and actionable hint.
• Cache names come from the selected timestamp label for SNAPSHOTs, or the actual input filename otherwise. Validate size and modification time against the actual input JAR; regenerate legacy archives missing that metadata. Cache hits read source directly without starting Java. Decompilers receive the absolute original JAR path; use private workspaces for output only and verify the original file state before publishing.
• Use independent temporary paths and atomic publication. Concurrent misses may decompile more than once; there is no cross-process lock. Construct the cache per request from the actual JAR path; never mutate a shared cache location when reading different versions concurrently. Do not put blocking scans or Java calls in the event loop.