codescope-mcp-preflight

architecutre
Overview of our tool
Cli guide
demo results screenshots
using it as MCP plugin screenshot
abstract overview before doing anything in codebase while using this plugin

Inspiration

AI coding agents are strong at generating code, but repository-level changes often fail before implementation begins. An agent must first determine which file or symbol owns a behavior, whether the required functionality already exists, and whether similar-looking code is authoritative, experimental, deprecated, or unsafe.

Developers commonly reconstruct this understanding through repeated file searches, keyword queries, source inspection, and manual comparison. That process can work, but it is often prompt-dependent, difficult to reproduce, and increasingly expensive as repositories grow.

We built CodeScope to introduce a structured repository preflight before code generation.

What it does

CodeScope is a local-first, read-only MCP preflight for Python repositories. It indexes source files and exposes four tools to Codex:

list_indexed_files — confirms repository inventory and index state.
search_code — searches source code using behavioral or business-language queries.
find_symbol — locates exact classes, functions, and methods.
find_similar — surfaces related, competing, duplicated, legacy, or experimental implementations.

Using this evidence, Codex can make an explicit architectural decision before editing:

REUSE an existing implementation.
EXTEND the current authoritative component.
CREATE a new component only when no suitable owner exists.

CodeScope does not modify source files or make the final decision. It gathers repository evidence, while Codex remains responsible for interpretation, implementation, testing, and review.

How we built it

CodeScope is implemented in Python and runs locally as a standard-input/output MCP server.

Its workflow is:

Repository
    ↓
Python source discovery
    ↓
Symbol and code-chunk extraction
    ↓
Local vector embeddings
    ↓
Repository index
    ↓
MCP tools for Codex
    ↓
REUSE, EXTEND, or CREATE decision

The current MVP supports Python .py and .pyi files. It uses sentence-transformers/all-MiniLM-L6-v2 to create local code embeddings and stores the generated repository index inside .codescope.

The tool is read-only during discovery. It does not execute indexed source code, apply edits, or silently modify the repository.

Demonstration and validation

We tested CodeScope using two clean copies of the same incident-routing repository.

The task required regulated priority-one incidents to use an existing Security Review route and ten-minute service-level agreement while preserving duplicate suppression, one queue item, and one audit event.

The repository deliberately contained several plausible paths:

an authoritative production routing policy;
an existing response-time component;
a deprecated broadcaster that created duplicate side effects;
an experimental keyword-based router.

Without CodeScope

Codex solved the task correctly, but it manually enumerated files, searched repository terminology, opened several modules, traced ownership, and compared production, legacy, and experimental implementations.

It correctly chose EXTEND + REUSE, changed one production file, modified no tests, and passed all eight tests.

With CodeScope

Codex first performed a structured MCP preflight. It confirmed the indexed repository, searched using task language rather than guessed filenames, resolved exact production symbols, and investigated similar implementations.

The preflight surfaced both the authoritative routing policy and the unsafe alternatives before editing. Codex classified the deprecated broadcaster and experimental router correctly, chose EXTEND + REUSE, applied the same minimal production-only change, modified no tests, and passed the full test suite.

The value of CodeScope was not forcing a different patch. It made the evidence behind the patch explicit, source-grounded, and repeatable.

How Codex and GPT-5.6 were used

We used GPT-5.6 through Codex throughout the project for:

architecture exploration;
implementation planning;
repository investigation;
test development and execution;
failure diagnosis;
MCP integration;
security and privacy review;
documentation;
release validation;
comparison testing.

Codex accelerated implementation and validation, while we defined the product boundary, local-first architecture, read-only discovery model, and the REUSE, EXTEND, or CREATE decision framework.

Challenges we faced

One major challenge was separating semantic relevance from architectural authority. A deprecated implementation may be highly relevant to a search query while still being unsafe to reuse.

This led to an important design principle:

Similarity is evidence, not proof.

CodeScope therefore does not treat the highest-ranked search result as automatically correct. It combines behavioral search, exact symbols, similar-code investigation, source context, and final Codex validation.

We also had to make the indexing and MCP workflow deterministic, keep generated indexes out of version control, support offline model use after preparation, and ensure that discovery never modified indexed source.

What we learned

We learned that the final code change is often not the hardest part of repository work. The harder problem is establishing confidence about:

ownership;
architectural boundaries;
existing reusable behavior;
legacy implementations;
side effects;
the smallest safe change.

We also learned that a useful developer tool should complement an intelligent coding agent rather than claim to replace it. CodeScope focuses on evidence gathering; Codex still owns reasoning and execution.

Accomplishments

Built a working local MCP server for Python repository preflight.
Implemented repository inventory, behavioral search, exact symbol lookup, and similar-code investigation.
Created an explicit REUSE, EXTEND, or CREATE workflow.
Preserved a read-only boundary during repository discovery.
Validated the tool through a controlled comparison with and without CodeScope.
Added installation, testing, judge-evaluation, architecture, security, and limitation documentation.
Prepared a reproducible judge-testing workflow.

Current limitations

The current MVP:

focuses on Python repositories;
requires Python 3.12;
is fully verified on Linux;
does not claim full Windows or macOS verification;
treats semantic similarity as investigation evidence rather than correctness proof;
does not replace tests, code review, or developer judgment.