Skip to main content
Glama

JavaBytes

CI

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 npx launcher)

  • 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-mcp

It 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
    }
  }
}
# 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 problems

Quick reference for config locations:

Client

Config command

Where to paste

OpenCode

npx -y javabytes-mcp config --client=opencode

~/.config/opencode/opencode.json

Claude Desktop

npx -y javabytes-mcp config --client=claude

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Cursor

npx -y javabytes-mcp config --client=cursor

~/.cursor/mcp.json

VS Code

npx -y javabytes-mcp config --client=vscode

.vscode/mcp.json in your workspace

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 server

The 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:java

Run the shaded jar:

java -jar target/javabytes.jar

stdout is reserved for JSON-RPC. All logging goes to stderr.

Configuration

Variable

Default

Purpose

JAVABYTES_ALLOWED_DIRS

working dir + JVM temp dir

Fallback filesystem sandbox roots

JAVABYTES_ENABLE

category defaults

Enable/disable tools by group or name

JAVABYTES_DISABLE

category defaults

Disable specific tools

JAVABYTES_LOG_FILE

unset

Optional JSON-RPC trace log

JAVABYTES_DB_URL

jdbc:mysql://localhost:3306/appdb

MySQL JDBC URL

JAVABYTES_DB_USER

app

MySQL user

JAVABYTES_DB_PASSWORD

change-me

MySQL password

Example:

JAVABYTES_ALLOWED_DIRS=/home/me/projects java -jar target/javabytes.jar

Tool groups and feature flags

Tools are grouped, and a group can be toggled without touching code:

Group

Default

Contents

files

on

sandboxed filesystem tools

database

on

read-only MySQL query/list/describe

system

on

system info, time conversion, version, tool list

json

on

JSON path query

javafx

on

off-screen canvas, drawing and PNG export

analysis

on

code/UI/security/TODO analysis and Spring Boot inspection

diagnostics

on

evidence-based project diagnostics

ui, design, codegen, springboot

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.jar

Precedence, 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

query_database

Read-only SQL (SELECT/SHOW/DESCRIBE/EXPLAIN/WITH), max 1000 rows

list_tables

Tables and views

describe_table

Column metadata; identifiers are validated and backtick-quoted

javafx_init_canvas

Create an off-screen canvas

javafx_draw_canvas

Draw rectangle/circle/line/text

javafx_set_color

Set fill/stroke color

javafx_clear_canvas

Clear the canvas

javafx_export_image

Snapshot to a real PNG via SwingFXUtils + ImageIO

project_diagnostic

Evidence-based dependency/configuration check

analyze_springboot_project

Spring Boot layout inspection

extract_data_models

Parse mongoose/prisma/sequelize/SQL/JSON data declarations into tables and columns, with per-field confidence and an honest limitations list

models_to_schema

Convert parsed schema models into normalized schema proposals: proposed DDL, pass-through verdicts, and a verification list of medium/low-confidence fields

generate_database

Execute proposed normalized DDL against a user-supplied JDBC URL to create the schema (creates only; refuses existing-table collision unless confirm=true)

fix_javafx_headless

Adds the Monocle property (dry run by default; apply=true to write)

create_mysql_client

Generates a self-contained JDBC helper that reads credentials from env

get_system_info

JVM/OS/hardware info

environment_variables

Read env vars; secret-like values masked unless reveal=true

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.isPathAllowed rejects 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-evil never matches C:\dev.

  • Read-only SQL. MyDatabaseClient.query validates the statement, refuses multiple statements, sets the connection read-only, caps rows,(sf and applies a query timeout.

  • **Identifier validation.describe_table accepts only plain identifiers or schema.table.

  • **Secret masking.Environment variables whose names look like credentials are masked by default. Generated MySQL clients read DB_URL/DB_USER/DB_PASSWORD`; no password is written into source.

  • **Advisory diagnostics.fix_all and fix_maven_dependencies never rewrite the project. fix_javafx_headless writes only with apply=true.

  • **Client roots.When a client provides roots, they replace the environment sandbox. Roots that are not file://, 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/javabytes

They 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 tools
analyze_codeAnalyze Java CodeB
Read-onlyIdempotent

Analyze Java source for complexity, smells and structural problems.

Inputs: code (required), language.

analyze_javascriptAnalyze JavaScript/TypeScriptA
Read-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 NormalizationA
Read-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 ProjectB
Read-onlyIdempotent

Inspect a Spring Boot project and report missing layers, configuration and dependency issues.

Inputs: projectPath.

analyze_ui_layoutAnalyze UI LayoutB
Read-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 IssuesA
Read-onlyIdempotent

Scan Java source for common security issues such as injection and weak crypto.

Inputs: code (required), language.

compare_filesCompare FilesB
Read-onlyIdempotent

Compare two text files and report whether they differ, with a diff summary.

Inputs: path1 (required), path2 (required).

convert_timeConvert TimeA
Read-onlyIdempotent

Convert a timestamp between time zones or between epoch and ISO-8601 formats.

Inputs: time, timezone.

create_mysql_clientGenerate MySQL ClientB
Read-onlyIdempotent

Generate a MySQL JDBC client helper class with safe connection handling.

Inputs: jdbcUrl, username, packageName, projectPath.

delete_fileDelete FileA
Destructive

Delete a file or an empty directory inside an allowed directory.

Inputs: path (required).

describe_tableDescribe Database TableB
Read-onlyIdempotent

Describe the columns, types, keys and defaults of a database table.

Inputs: table_name (required), jdbc_url.

environment_variablesEnvironment VariablesA
Read-onlyIdempotent

List, read or explain environment variables. Secret-like values are masked.

Inputs: name, value, action, reveal.

explain_queryExplain Query PlanB
Read-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 DDLA
Read-onlyIdempotent

Export SHOW CREATE TABLE DDL for one table or every base table.

Inputs: jdbc_url, table_name.

extract_data_modelsExtract Data ModelsA
Read-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 SystemC
Read-onlyIdempotent

Extract colors, typography and spacing tokens from CSS or HTML into a design system.

Inputs: source (required), appName.

find_todosFind TODO MarkersB
Read-onlyIdempotent

Find TODO, FIXME and HACK markers in a source tree.

Inputs: code (required), filePath.

fix_allRun All DiagnosticsC
Read-onlyIdempotent

Run all diagnostics, apply safe fixes and summarize what changed.

Inputs: autoFix, projectPath.

fix_javafx_headlessConfigure Headless JavaFXB
Idempotent

Detect and explain headless JavaFX problems and generate the required configuration.

Inputs: apply, mainClass, projectPath.

fix_maven_dependenciesCheck Maven DependenciesB
Read-onlyIdempotent

Detect and report incorrect or missing Maven dependencies with suggested fixes.

Inputs: action, projectPath.

generate_databaseGenerate Database from DDLA
Destructive

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 InfoA
Read-onlyIdempotent

Return existence, type, size, timestamps and permissions for a path.

Inputs: path (required).

get_system_infoGet System InfoA
Read-onlyIdempotent

Report JVM, operating-system and hardware information.

Inputs: no named parameters.

get_versionGet Server VersionA
Read-onlyIdempotent

Return the JavaBytes server and Java runtime versions.

Inputs: no named parameters.

html_css_to_javafx_cssConvert HTML/CSS to JavaFX CSSA
Read-onlyIdempotent

Translate HTML/CSS declarations into valid JavaFX CSS and report unsupported properties.

Inputs: css, html.

javafx_clear_canvasClear CanvasB
Idempotent

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 PNGC
DestructiveIdempotent

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 ColorA
Idempotent

Set the current fill or stroke color used by canvas drawing operations.

Inputs: color (required).

json_queryQuery JSONB
Read-onlyIdempotent

Query a JSON document with a dot/bracket path and optionally return pretty output.

Inputs: json (required), query.

list_directoryList DirectoryB
Read-onlyIdempotent

List the entries of a directory with type and size information.

Inputs: path (required).

list_foreign_keysList Foreign KeysA
Read-onlyIdempotent

List foreign keys with referenced tables, columns and delete/update rules.

Inputs: jdbc_url, table_name.

list_indexesList IndexesA
Read-onlyIdempotent

List indexes, uniqueness and column order for a table or the whole schema.

Inputs: jdbc_url, table_name.

list_servicesList Enabled ToolsA
Read-onlyIdempotent

List all tools currently registered by this JavaBytes server.

Inputs: no named parameters.

list_tablesList Database TablesB
Read-onlyIdempotent

List the tables and views in the configured MySQL database.

Inputs: jdbc_url.

make_directoryCreate DirectoryA
Idempotent

Create a directory and any missing parents inside an allowed directory.

Inputs: path (required).

models_to_schemaGenerate Schema from ModelsA
Read-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 ProjectA
Read-onlyIdempotent

Check a project for build, dependency and configuration problems without modifying it.

Inputs: projectPath.

query_databaseQuery DatabaseB
Read-onlyIdempotent

Run a read-only SQL query against the configured MySQL database and return rows.

Inputs: sql (required), jdbc_url.

read_text_fileRead Text FileB
Read-onlyIdempotent

Read a UTF-8 text file inside an allowed directory and return its contents.

Inputs: path (required).

search_filesSearch FilesC
Read-onlyIdempotent

Find files by glob name pattern and, optionally, a regular expression on their contents.

Inputs: content, pattern, directory, recursive.

verify_generatedVerify Generated CodeA
Read-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 FileA
DestructiveIdempotent

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

    B3.1/5.0

    Scored across 45 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      26
      63 npm
      10
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Dynamic MCP server for Node.js enabling runtime tool creation, management, and execution in isolated sandboxes (Docker or Node).
      8
      11 npm
      1
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      A 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.
      44
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Zero-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.
      10
      MIT