screenctx

screenctx collects the local files that explain one Spring Boot + MyBatis screen so you can hand a compact, structured context bundle to an AI tool (ChatGPT, Claude, Copilot, …) or read it yourself before making a change.

Given a single entry point — a route, a controller/Action class, a method, or a file — it walks the dependency graph (controller → business logic → DAO/Mapper → MyBatis XML, plus views, static assets, message properties, and config) and produces one Markdown file plus a copyable bundle.

It does static analysis only. No Maven/Gradle build, no Spring startup, no network. It favors recall over perfect precision, so related framework/base files may be included when they clarify the screen flow. References it cannot resolve statically (reflection, string-built bean names, runtime-only SQL ids) are reported under unresolved.

It collects, with reasons, things like:

• Spring Boot controllers or legacy-style Action classes
• JSP / Thymeleaf / template views and static assets
• FormBean, input/output beans, DTOs, constants, validators, helpers
• BLogic / BaseLogic / Service classes
• Mapper/DAO interfaces and MyBatis/iBATIS SQLMap XML
• message/error .properties
• application.yml, application.properties, mybatis-config.xml

---

Requirements

• Python 3.10+
• No runtime dependencies for the CLI (the standard library only)
• Optional mcp package only if you use the MCP server

---

Install

macOS / Linux

git clone https://github.com/<your-account>/screenctx.git
cd screenctx
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e .

Windows

PowerShell:

git clone https://github.com/<your-account>/screenctx.git
cd screenctx
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .

If Activate.ps1 is blocked, run once in the same PowerShell window: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Command Prompt (cmd.exe):

git clone https://github.com/<your-account>/screenctx.git
cd screenctx
py -m venv .venv
.venv\Scripts\activate.bat
py -m pip install -e .

After installing, the screenctx command is on your PATH. You can always run it without installing too:

python3 -m screenctx.cli --help     # macOS/Linux
py -m screenctx.cli --help          # Windows

To also use the MCP server, install the extra:

python3 -m pip install -e ".[mcp]"   # macOS/Linux
py -m pip install -e ".[mcp]"        # Windows

---

Collect one screen

screenctx collect \
  --root /path/to/spring-project \
  --entry /customer/detail \
  --out ./ctx \
  --force

Windows:

screenctx collect --root C:\path\to\spring-project --entry /customer/detail --out .\ctx --force

What --entry accepts

--entry is repeatable and is resolved in this order (the first form that matches wins):

Form	Example	Notes
File path (absolute or relative to --root)	src/main/webapp/WEB-INF/jsp/demo100/list.jsp	Any file: .jsp / .html / .java / .xml / .properties. Use this to target a screen by its template file.
Java class (simple name or fully-qualified)	CustomerAction, example.action.CustomerAction	Any existing class — controller, Action, BLogic, Service, Dao/Mapper, … Use the name without a .java suffix.
Class method	CustomerDao#selectByCustomerId, Demo100_02SearchAction#search	Focuses on that method and its call chain.
Route	/customer/detail, /Demo100_list	Supports {id} path variables and * wildcards.

Notes:

• Traversal is downstream-only. Starting from a controller class or a route gives the fullest screen context (it follows return "view" down to the JSP/Thymeleaf and the full BLogic → DAO → XML chain). Starting from a BLogic/DAO only collects what is downstream of it — it does not find its callers.
• There is no "bare view name" lookup: --entry detail will not resolve to a template. Use the screen's route (/customer/detail) or its file path instead.
• A simple class name matches every class with that name across the project; use the fully-qualified name to disambiguate.

Useful options

screenctx collect --root /path/to/project --entry /Demo100_list --out ./ctx --depth 4
screenctx collect --root /path/to/project --entry Demo100_02SearchAction#search --out ./ctx --no-copy
screenctx collect --root /path/to/project --entry /Demo100_list --out ./ctx --dry-run

Option	Default	Meaning
--depth N	3	Dependency traversal depth.
--max-files N	240	Stop after collecting N files.
--max-file-bytes N	none	Cap bytes included per file in context.md. Off by default.
--no-config	off	Do not auto-include application.* / mybatis-config.xml.
--no-follow-view-routes	off	Do not follow form/action/fetch routes found in views/scripts.
--no-copy	off	Write reports only; do not copy files into bundle/.
--force	off	Overwrite the output directory (only if it is empty or screenctx-managed).
--dry-run	off	Analyze and print the file list without writing anything.

--force will refuse to overwrite a directory that contains files screenctx did not write, and refuses to use the project root itself as --out.

---

Output

ctx/
  context.md          # one Markdown file ready to paste/upload to an AI tool
  tree.txt            # directory tree of collected files
  files.txt           # plain list of collected files
  manifest.json       # machine-readable reasons, routes, unresolved refs
  unresolved.jsonl    # only when unresolved refs exist
  bundle/             # copied original files, preserving relative paths

context.md includes the matched routes, the collected file tree, matched message lines, unresolved references, and each collected file with the reasons it was included and its content.

By default context.md does not truncate text files. For common utilities, DAO interfaces, Mapper/API-Mapper classes, and MyBatis/iBATIS SQLMap XML, it uses focused snippets when it can prove the called method or SQL statement; the full original file is still copied under bundle/.

bundle/ is useful when the AI tool can accept a folder/zip; context.md is useful when it only accepts a single text file.

---

Use from VS Code (MCP server)

screenctx ships an MCP server that exposes a collect_screen_context tool, so editors like VS Code (Copilot Chat / agent mode) can pull screen context on demand.

1. Install the MCP extra: pip install -e ".[mcp]"

2. The repo includes .vscode/mcp.json:

   {
     "servers": {
       "screenctx": {
         "type": "stdio",
         "command": "python",
         "args": ["-m", "screenctx.mcp_server"]
       }
     }
   }
   

   On Windows, use "command": "py" if python is not on your PATH. If you installed into a virtual environment, point command at that interpreter (e.g. .venv/bin/python or .venv\\Scripts\\python.exe) so the mcp package is found.

3. Reload VS Code and start the screenctx server from the MCP view. The tool takes a root and a list of entries (same forms as --entry above) and returns the context.md content directly.

You can also run the server standalone over stdio:

python -m screenctx.mcp_server
# or, after install:
screenctx-mcp

---

Development

python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e ".[dev]"
pytest

Smoke checks against fixtures / a real project:

./scripts/smoke_sqlmap_fixture.sh
./scripts/smoke_work_test.sh /path/to/your-spring-project

---

Current limits

• Conservative static collector, not a full Java compiler.
• Resolves common Spring annotations, Java type references, MyBatis XML namespaces, template includes, form actions, static assets, and message keys.
• Does not execute Maven/Gradle, start Spring, or require network access.
• Favors recall over perfect precision; some related base/framework files may be included.