JavaBytes
JavaBytes is a general-purpose Java MCP server that gives an agent sandboxed file access, live read-only MySQL, off-screen JavaFX rendering, and project/code analysis over JSON-RPC 2.0 stdio.
Sandboxed filesystem — read/write text files, list directories, file info, create directories, delete, glob+regex search, timestamped backups, and file comparison, all confined to allowed roots.
Read-only MySQL — run SELECT/SHOW/DESCRIBE/EXPLAIN queries (row-capped), list tables, describe columns, list foreign keys and indexes, export
SHOW CREATE TABLEDDL, and analyze schema normalization.JavaFX canvas — create an off-screen canvas, draw rectangles/circles/lines/text, set colors, clear, and export real PNGs; plus a headless-JavaFX fixer (dry-run by default).
Project diagnostics — evidence-based project checks, Maven dependency checks, Spring Boot layout inspection, and a deterministic "antislop" gate for generated Java.
Code & data analysis — Java complexity/smell analysis, security scanning, TODO finding, JS/TS project inventory, and data-model extraction (mongoose/prisma/sequelize/SQL/JSON) into schema proposals and DDL.
UI/design helpers — extract design tokens, analyze layout/accessibility, and convert HTML/CSS to JavaFX CSS.
System & utility — JVM/OS info, environment variables (secrets masked), time-zone conversion, JSON path queries, server version, and enabled-tool listing.
Generators — a MySQL JDBC client helper plus ~30 opt-in template generators (UI, design, codegen, Spring Boot) that are disabled by default.
Provides read-only MySQL database access, including executing SELECT/SHOW/DESCRIBE/EXPLAIN queries, listing tables and views, and describing table column metadata via configurable JDBC connection settings.
Provides Spring Boot project inspection and scaffolding tools, including analyzing project layout and generating Spring Boot entities, repositories, services, controllers, DTOs, configuration, security, exception handling, validation, pagination, file upload, scheduled/async/cache features, profiles, Docker templates, and tests.
JavaBytes
A general-purpose Java MCP (Model Context Protocol) server that speaks JSON-RPC 2.0 over stdio.
It exposes Java-oriented tools for file access, MySQL, JavaFX canvas rendering/export, project diagnostics, and code/CSS generation. It has no MCP SDK dependency: the protocol is implemented directly with Jackson.
Scope note: tools that only reword a prompt (most
*_generate_*tools) are conveniences. The tools that add real capability are the ones that touch the world: the file sandbox, live MySQL, JavaFX rendering, and project inspection.
Requirements
Node.js 18+ (only for the
npxlauncher)JDK 21 or newer (built and tested with JDK 25)
Maven 3.9+ (only to build from source)
Related MCP server: dynamic-mcp
Install with npx
The javabytes-mcp package bundles the shaded jar, so a client only needs Node.js and Java:
npx -y javabytes-mcpIt resolves java from JAVABYTES_JAVA, then JAVA_HOME, then PATH, and the jar from
JAVABYTES_JAR or the bundled copy.
Client config — Claude Desktop and most clients:
{
"mcpServers": {
"javabytes": {
"command": "npx",
"args": ["-y", "javabytes-mcp"],
"env": {
"JAVABYTES_DB_URL": "jdbc:mysql://localhost:3306/appdb",
"JAVABYTES_DB_USER": "app",
"JAVABYTES_DB_PASSWORD": "change-me"
}
}
}
}OpenCode (~/.config/opencode/opencode.json) uses a different shape — mcp, a command array,
and environment rather than env:
{
"mcp": {
"javabytes": {
"type": "local",
"command": ["npx", "-y", "javabytes-mcp"],
"environment": {
"JAVABYTES_DB_URL": "jdbc:mysql://localhost:3306/appdb",
"JAVABYTES_DB_USER": "app",
"JAVABYTES_DB_PASSWORD": "change-me"
},
"enabled": true
}
}
}First Run (recommended)
# 1. Check your environment
npx -y javabytes-mcp doctor
# 2. Generate the config for your client (copy-paste into its config file)
npx -y javabytes-mcp config --client=opencode # → ~/.config/opencode/opencode.json
npx -y javabytes-mcp config --client=claude # → claude_desktop_config.json
npx -y javabytes-mcp config --client=cursor # → Cursor MCP settings
npx -y javabytes-mcp config --client=vscode # → .vscode/mcp.json
# 3. Restart your client and verify tools load (should show 45/75)Example doctor output:
PASS java: 21.0.5 via JAVA_HOME (/usr/lib/jvm/java-21-openjdk/bin/java)
PASS jar: present (15.8 MB)
INFO db: JAVABYTES_DB_URL is not set - MySQL tools will be unconfigured
PASS update: up to date (1.2.0)
4 checks, 0 problemsQuick reference for config locations:
Client | Config command | Where to paste |
OpenCode |
|
|
Claude Desktop |
|
|
Cursor |
|
|
VS Code |
|
|
Then set your real DB credentials:
# Optional: configure MySQL for live queries
export JAVABYTES_DB_URL=jdbc:mysql://localhost:3306/yourdb
export JAVABYTES_DB_USER=youruser
export JAVABYTES_DB_PASSWORD=yourpassword
# Restart the client / MCP serverThe doctor command checks Java ≥ 21, the bundled jar, MySQL env, and npm updates.
The config command prints ready-to-paste JSON with placeholders — just update the
password and database URL, then restart your client.
Build from source
mvn clean test # 146 unit tests (6 more run live only when JAVABYTES_RUN_DB_TESTS=1)
mvn package # produces target/javabytes.jar (shaded, runnable)Run from source:
mvn -q exec:javaRun the shaded jar:
java -jar target/javabytes.jarstdout is reserved for JSON-RPC. All logging goes to stderr.
Configuration
Variable | Default | Purpose |
| working dir + JVM temp dir | Fallback filesystem sandbox roots |
| category defaults | Enable/disable tools by group or name |
| category defaults | Disable specific tools |
| unset | Optional JSON-RPC trace log |
|
| MySQL JDBC URL |
|
| MySQL user |
|
| MySQL password |
Example:
JAVABYTES_ALLOWED_DIRS=/home/me/projects java -jar target/javabytes.jarTool groups and feature flags
Tools are grouped, and a group can be toggled without touching code:
Group | Default | Contents |
| on | sandboxed filesystem tools |
| on | read-only MySQL query/list/describe |
| on | system info, time conversion, version, tool list |
| on | JSON path query |
| on | off-screen canvas, drawing and PNG export |
| on | code/UI/security/TODO analysis and Spring Boot inspection |
| on | evidence-based project diagnostics |
| off | template generators |
A fresh server exposes 45 capability tools; the 30 template generators are opt-in
(JAVABYTES_ENABLE=all exposes all 75).
Enable or disable by group or by individual tool name:
# Add every Spring Boot and code generator
JAVABYTES_ENABLE=springboot,codegen java -jar target/javabytes.jar
# Everything, except one destructive tool
JAVABYTES_ENABLE=all JAVABYTES_DISABLE=delete_file java -jar target/javabytes.jarPrecedence, highest first: disabled by tool name → enabled by tool name → disabled group →
enabled group → all in the disable list → all in the enable list → the group default.
tools/list only advertises enabled tools; calling a disabled tool returns JSON-RPC -32602
with the flag needed to enable it.
Every tool descriptor also carries a title and MCP annotations (readOnlyHint,
destructiveHint, idempotentHint, openWorldHint) so clients can ask for confirmation or
auto-approve reads.
MCP roots
If the client advertises capabilities.roots, the server requests roots/list after
initialization and again after notifications/roots/list_changed. Usable file:// roots
replace the environment sandbox for the session, narrowing what file tools may touch. If the
client returns no usable roots, or the request fails, the JAVABYTES_ALLOWED_DIRS fallback
stays in effect. Filesystem roots such as C:\ and / are refused so a misconfiguration
cannot expose the whole disk.
Tool catalog
Capabilities
Tool | What it does |
| Read-only SQL ( |
| Tables and views |
| Column metadata; identifiers are validated and backtick-quoted |
| Create an off-screen canvas |
| Draw rectangle/circle/line/text |
| Set fill/stroke color |
| Clear the canvas |
| Snapshot to a real PNG via |
| Evidence-based dependency/configuration check |
| Spring Boot layout inspection |
| Parse mongoose/prisma/sequelize/SQL/JSON data declarations into tables and columns, with per-field confidence and an honest limitations list |
| Convert parsed schema models into normalized schema proposals: proposed DDL, pass-through verdicts, and a verification list of medium/low-confidence fields |
| Execute proposed normalized DDL against a user-supplied JDBC URL to create the schema (creates only; refuses existing-table collision unless confirm=true) |
| Adds the Monocle property (dry run by default; |
| Generates a self-contained JDBC helper that reads credentials from env |
| JVM/OS/hardware info |
| Read env vars; secret-like values masked unless |
Filesystem (sandboxed)
read_text_file, write_file, list_directory, get_file_info, make_directory,
delete_file, search_files (glob + optional content regex), backup_file (no overwrite),
compare_files.
Convenience generators
generate_code, generate_tests, generate_docs, refactor_code, check_security,
find_todos, analyze_code, generate_css, generate_ui_code, generate_javafx_component,
extract_design_system, analyze_ui_layout, html_css_to_javafx_css, design_tokens,
anti_slop_review, translate_webapp, json_query, convert_time, get_version, list_services, and the
springboot_generate_* family (entity, repository, service, controller, DTO, properties,
security, relationship, actuator, exception handler, validation, pagination, file upload,
scheduled, async, cache, profile, docker, test).
These emit templates. They do not compile or run the result. Prefer prompting for anything
beyond their exact shape. All of them are disabled by default; enable them with
JAVABYTES_ENABLE=ui,design,codegen,springboot (or all).
Security model
Path sandbox.
AppConfig.isPathAllowedrejects empty paths and null bytes, normalizes, resolves the real path of the deepest existing ancestor (so non-existent targets and symlinks are handled), and compares on component boundaries.C:\dev-evilnever matchesC:\dev.Read-only SQL.
MyDatabaseClient.queryvalidates the statement, refuses multiple statements, sets the connection read-only, caps rows,(sf and applies a query timeout.**Identifier validation.
describe_tableaccepts only plain identifiers orschema.table.**Secret masking.
Environment variables whose names look like credentials are masked by default. Generated MySQL clients readDB_URL/DB_USER/DB_PASSWORD`; no password is written into source.**Advisory diagnostics.
fix_allandfix_maven_dependenciesnever rewrite the project.fix_javafx_headlesswrites only withapply=true.**Client roots.
When a client provides roots, they replace the environment sandbox. Roots that are notfile://, are not directories, or are filesystem roots (C:`,/) are ignored.
Tests
mvn test runs 146 tests covering the sandbox (traversal, null bytes, sibling-prefix),
directory creation results, glob and content search, CSS conversion, generated UI code, SQL
rejection, dependency false positives, error shapes, tool metadata completeness and
annotations, feature-flag precedence, client-root narrowing/reset, JS translation,
webapp translation with JavaFX CRUD views, scan-only and report-path modes, and Maven
Wrapper generation.
MySQL and JavaFX integration tests require a real database. Canvas export was verified
end-to-end over stdio (200x100 PNG, correct magic bytes). A 26-check stdio scenario also
covers roots negotiation, sandbox narrowing, roots/list_changed, disabled-tool errors,
launcher resolution, and annotations in tools/list.
Agent skills
skills/ holds three agent skills that make the tool catalog usable without
reading it: javabytes-setup (install, configure, troubleshoot),
javabytes-tool-routing (which tool to call, in what order, and what counts
as done) and javabytes-convert (the JavaScript-to-Java pipeline: clone, scope,
analyze, translate, report — with an honest manual-work inventory). Install
them into an agent with:
npx skills@latest add markymakes-dev/javabytesThey are plain markdown; the server is still required for the tools themselves.
License
MIT — see LICENSE.
You may use, modify, and redistribute JavaBytes commercially. In return, the only obligation is keeping the copyright notice and licence text with copies.
The bundled mysql-connector-j is GPL-2.0 with the Universal FOSS Exception, which
permits redistribution inside an OSI-approved (MIT) program. If this project ever ships a
proprietary build, that dependency must be replaced (for example with
mariadb-java-client, LGPL-2.1) or licensed commercially from Oracle.
Available Tools
45 toolsanalyze_codeAnalyze Java CodeBRead-onlyIdempotent
Analyze Java source for complexity, smells and structural problems.
Inputs: code (required), language.
analyze_javascriptAnalyze JavaScript/TypeScriptARead-onlyIdempotent
Inventory a JS/TS file or project: frameworks, npm dependencies, routes, components, browser APIs and migration risks.
Inputs: code, path, file_name, max_files.
analyze_schema_normalizationAnalyze Schema NormalizationARead-onlyIdempotent
Review keys, foreign keys, indexes and sampled list-like columns for likely normal-form problems.
Inputs: jdbc_url, sample_rows, default_table, include_samples, +1 more.
analyze_springboot_projectAnalyze Spring Boot ProjectBRead-onlyIdempotent
Inspect a Spring Boot project and report missing layers, configuration and dependency issues.
Inputs: projectPath.
analyze_ui_layoutAnalyze UI LayoutBRead-onlyIdempotent
Analyze a UI layout description and report spacing, hierarchy and accessibility concerns.
Inputs: css (required), html.
backup_fileBack Up FileA
Copy a file to a timestamped sibling backup without overwriting existing backups.
Inputs: path (required), suffix.
check_securityCheck Security IssuesARead-onlyIdempotent
Scan Java source for common security issues such as injection and weak crypto.
Inputs: code (required), language.
compare_filesCompare FilesBRead-onlyIdempotent
Compare two text files and report whether they differ, with a diff summary.
Inputs: path1 (required), path2 (required).
convert_timeConvert TimeARead-onlyIdempotent
Convert a timestamp between time zones or between epoch and ISO-8601 formats.
Inputs: time, timezone.
create_mysql_clientGenerate MySQL ClientBRead-onlyIdempotent
Generate a MySQL JDBC client helper class with safe connection handling.
Inputs: jdbcUrl, username, packageName, projectPath.
delete_fileDelete FileADestructive
Delete a file or an empty directory inside an allowed directory.
Inputs: path (required).
describe_tableDescribe Database TableBRead-onlyIdempotent
Describe the columns, types, keys and defaults of a database table.
Inputs: table_name (required), jdbc_url.
environment_variablesEnvironment VariablesARead-onlyIdempotent
List, read or explain environment variables. Secret-like values are masked.
Inputs: name, value, action, reveal.
explain_queryExplain Query PlanBRead-onlyIdempotent
Run MySQL EXPLAIN (or EXPLAIN ANALYZE) on a read-only SELECT and return the plan.
Inputs: sql (required), analyze, jdbc_url.
export_schema_ddlExport Schema DDLARead-onlyIdempotent
Export SHOW CREATE TABLE DDL for one table or every base table.
Inputs: jdbc_url, table_name.
extract_data_modelsExtract Data ModelsARead-onlyIdempotent
Parse mongoose, prisma, sequelize, SQL or JSON data declarations into tables and columns, with per-field confidence and an honest limitations list.
Inputs: code, path, file_name, source_type.
extract_design_systemExtract Design SystemCRead-onlyIdempotent
Extract colors, typography and spacing tokens from CSS or HTML into a design system.
Inputs: source (required), appName.
find_todosFind TODO MarkersBRead-onlyIdempotent
Find TODO, FIXME and HACK markers in a source tree.
Inputs: code (required), filePath.
fix_allRun All DiagnosticsCRead-onlyIdempotent
Run all diagnostics, apply safe fixes and summarize what changed.
Inputs: autoFix, projectPath.
fix_javafx_headlessConfigure Headless JavaFXBIdempotent
Detect and explain headless JavaFX problems and generate the required configuration.
Inputs: apply, mainClass, projectPath.
fix_maven_dependenciesCheck Maven DependenciesBRead-onlyIdempotent
Detect and report incorrect or missing Maven dependencies with suggested fixes.
Inputs: action, projectPath.
generate_databaseGenerate Database from DDLADestructive
Execute proposed normalized DDL against a user-supplied JDBC URL to create the schema (creates only; refuses existing-table collision unless confirm=true).
Inputs: ddl (required), jdbc_url (required), url, path, +1 more.
get_file_infoGet File InfoARead-onlyIdempotent
Return existence, type, size, timestamps and permissions for a path.
Inputs: path (required).
get_system_infoGet System InfoARead-onlyIdempotent
Report JVM, operating-system and hardware information.
Inputs: no named parameters.
get_versionGet Server VersionARead-onlyIdempotent
Return the JavaBytes server and Java runtime versions.
Inputs: no named parameters.
html_css_to_javafx_cssConvert HTML/CSS to JavaFX CSSARead-onlyIdempotent
Translate HTML/CSS declarations into valid JavaFX CSS and report unsupported properties.
Inputs: css, html.
javafx_clear_canvasClear CanvasBIdempotent
Clear the active off-screen canvas.
Inputs: no named parameters.
javafx_draw_canvasDraw on CanvasB
Draw shapes and primitives onto the active off-screen canvas.
Inputs: x (required), y (required), shape (required), x2, +5 more.
javafx_export_imageExport Canvas as PNGCDestructiveIdempotent
Export the active off-screen canvas to a PNG image file.
Inputs: path (required).
javafx_init_canvasCreate CanvasA
Create an off-screen JavaFX canvas with the given width and height.
Inputs: width, height.
javafx_set_colorSet Canvas ColorAIdempotent
Set the current fill or stroke color used by canvas drawing operations.
Inputs: color (required).
json_queryQuery JSONBRead-onlyIdempotent
Query a JSON document with a dot/bracket path and optionally return pretty output.
Inputs: json (required), query.
list_directoryList DirectoryBRead-onlyIdempotent
List the entries of a directory with type and size information.
Inputs: path (required).
list_foreign_keysList Foreign KeysARead-onlyIdempotent
List foreign keys with referenced tables, columns and delete/update rules.
Inputs: jdbc_url, table_name.
list_indexesList IndexesARead-onlyIdempotent
List indexes, uniqueness and column order for a table or the whole schema.
Inputs: jdbc_url, table_name.
list_servicesList Enabled ToolsARead-onlyIdempotent
List all tools currently registered by this JavaBytes server.
Inputs: no named parameters.
list_tablesList Database TablesBRead-onlyIdempotent
List the tables and views in the configured MySQL database.
Inputs: jdbc_url.
make_directoryCreate DirectoryAIdempotent
Create a directory and any missing parents inside an allowed directory.
Inputs: path (required).
models_to_schemaGenerate Schema from ModelsARead-onlyIdempotent
Convert parsed schema models into normalized schema proposals: proposed DDL, pass-through verdicts, and a verification list of medium/low-confidence fields.
Inputs: path, entities, source_type, functional_dependencies.
project_diagnosticDiagnose ProjectARead-onlyIdempotent
Check a project for build, dependency and configuration problems without modifying it.
Inputs: projectPath.
query_databaseQuery DatabaseBRead-onlyIdempotent
Run a read-only SQL query against the configured MySQL database and return rows.
Inputs: sql (required), jdbc_url.
read_text_fileRead Text FileBRead-onlyIdempotent
Read a UTF-8 text file inside an allowed directory and return its contents.
Inputs: path (required).
search_filesSearch FilesCRead-onlyIdempotent
Find files by glob name pattern and, optionally, a regular expression on their contents.
Inputs: content, pattern, directory, recursive.
verify_generatedVerify Generated CodeARead-onlyIdempotent
Deterministic antislop gate: checks generated Java files for TODO comments, raw types, missing nullability annotations, var in fields, missing Javadoc, and Object return types. Runs as a pipeline gate before Prove (compile + start).
Inputs: files (required).
write_fileWrite Text FileADestructiveIdempotent
Create or overwrite a text file inside an allowed directory.
Inputs: path (required), content (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Most tools target distinct resources (file ops, MySQL introspection, JavaFX canvas ops), but the diagnostic/analysis cluster is muddy: analyze_code, check_security, verify_generated, project_diagnostic, fix_all, find_todos, analyze_springboot_project and fix_maven_dependencies all sound like 'scan the project and report problems', so an agent could easily pick the wrong one. The mix of unrelated domains (time conversion, json_query, JS analysis) alongside Java tooling further blurs the set's center of gravity.
The dominant pattern is snake_case verb_noun (list_tables, describe_table, export_schema_ddl, write_file, search_files), applied consistently enough to be predictable. A handful of noun-phrase or X_to_Y names (environment_variables, project_diagnostic, models_to_schema, html_css_to_javafx_css) break the verb-first convention but remain clear.
45 tools is well past the comfortable range and the surface spans at least five unrelated domains (MySQL, file system, Java/JS static analysis, JavaFX canvas rendering, system/utility helpers). It reads as several servers bundled into one rather than a scoped toolset, making discovery and selection costly.
Each individual domain is partly covered — DB introspection is strong (tables, indexes, FKs, DDL, explain, generation) and file ops near-complete — but there are visible gaps: no ALTER/DML path for databases, no compose/run step linking verify_generated to a build, and no canvas dispose/teardown after javafx_init_canvas. Coverage is broad but shallow and uneven across the bundled domains.
Maintenance
Related MCP Connectors
238+ dev tools via MCP: JSON, QR, PDF, DNS, hash, UUID, code review, JWT, SSL, WHOIS, and more
39 MCP tools (7 free, 39 Pro/Team): AI guardrails, PII/secrets, MCP lint, SSRF, JSON & EU checks.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for profiling Java applications via JDK utilities (jcmd, jfr, jps). Enables AI assistants to diagnose performance, analyze threads, and inspect JFR recordings without manual CLI usage.2663 npm10MIT
- AlicenseBqualityDmaintenanceDynamic MCP server for Node.js enabling runtime tool creation, management, and execution in isolated sandboxes (Docker or Node).811 npm1MIT
- AlicenseCqualityDmaintenanceA secure-by-default MCP server and CLI for AI agents to inspect Spring Boot repositories and interact with runtime Actuator endpoints, enabling code review, dependency scanning, and monitoring.44MIT
- AlicenseAqualityBmaintenanceZero-dependency stdio bridge to Moltline Studio's fleet of 14 hosted MCP servers covering code review, time operations, data transforms, business ops, education, research, outreach and more. Free tier requires no registration; premium tools unlock with a license. Independently audited, MCPize Verified A.10MIT