graph-mcp-java-gen
graph-mcp-java-gen
[
[
(evidence/claims.json)
[
(LICENSE)
[
(src/graph_mcp/server.py)
[
(evadence/neo4j_integration.json)
Servidor MCP anclado al grafo que convierte solicitudes en lenguaje natural en métodos de prueba Java validados y compilables: nada de imports alucinados, nada de símbolos sin anclar, nada de fallos silenciosos.
Una solicitud en lenguaje natural o estructurada entra en un servidor stdio oficial del Model Context Protocol (MCP). Un catálogo de grafos versionado (un adaptador de Neo4j o un fixture JSON) suministra los únicos símbolos que el generador puede citar. Un validador multicapa comprueba la sintaxis, el contrato del framework, el anclaje y las reglas de APIs prohibidas antes de devolver cualquier código fuente. Dos agentes LLM opcionales — un normalizador de intenciones y un revisor posterior a la generación — amplían el pipeline a entradas de formato libre sin comprometer el marco de seguridad determinista.
Arquitectura
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e3a5f", "primaryTextColor": "#ffffff", "primaryBorderColor": "#0d2137", "lineColor": "#4a9eca", "secondaryColor": "#2d6a4f", "tertiaryColor": "#7b2d8b"}}}%%
flowchart TD
classDef input fill:#7b2d8b,stroke:#4a1a54,color:#fff,font-size:13px
classDef mcp fill:#e07b00,stroke:#9a5700,color:#fff,font-size:13px
classDef agent fill:#1a6b8a,stroke:#0d3f52,color:#fff,font-size:13px
classDef core fill:#2d6a4f,stroke:#1b4332,color:#fff,font-size:13px
classDef graph fill:#1e3a5f,stroke:#0d1f3c,color:#fff,font-size:13px
classDef validate fill:#4a6741,stroke:#2d4026,color:#fff,font-size:13px
classDef ok fill:#155724,stroke:#0a3015,color:#fff,font-size:13px
classDef reject fill:#721c24,stroke:#3d0a0e,color:#fff,font-size:13px
NL["🌎 Free-form NL\n(generate_java_test_nlp)"]:::input
SF["📄 Structured fields\n(generate_java_test)"]:::input
TX["💬 Intent text\n(generate_java_test_from_intent)"]:::input
MCP["🔌 FastMCP stdio Server\n7 tools · zero raw Cypher"]:::mcp
A1["🤖 LLMIntentParser\nAgent 1 · gpt-4o-mini\nfield extraction"]:::agent
INT["✅ GenerationIntent\nclass · package · module\nconfig · version"]:::core
GDB["📊 Graph Catalog\nNeo4j 5.26 / JSON fixture\n8 symbols · 12 methods"]:::graph
GEN["⚙️ Template Generator\ndeterministic render"]:::core
VAL["🛡️ JavaValidator\nTree-sitter AST\ncontract · grounding\nsource-safety"]:::validate
A2["🤖 ReviewAgent\nAgent 2 · gpt-4o-mini\n6-item checklist"]:::agent
OK["✅ Accepted Java\nsource + citations\n+ review verdict"]:::ok
REJ["❌ Typed Rejection\nerror code + message\nno source returned"]:::reject
NL --> MCP
SF --> MCP
TX --> MCP
MCP -->|"NLP path"| A1
MCP -->|"direct path"| INT
A1 -->|"extracted fields"| INT
INT -->|"invalid"| REJ
INT -->|"valid"| GDB
GDB -->|"cited symbols"| GEN
GEN --> VAL
VAL -->|"any gate fails"| REJ
VAL -->|"all gates pass"| A2
A2 -->|"issues found"| REJ
A2 -->|"approved"| OKRelated MCP server: MCP Universal Test Suite Generator
Pipeline multiagente
%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#1e3a5f", "actorTextColor": "#ffffff", "actorBorderColor": "#4a9eca", "activationBkgColor": "#2d6a4f", "activationBorderColor": "#155724", "noteBkgColor": "#fff8e1", "noteTextColor": "#333", "signalColor": "#4a9eca", "signalTextColor": "#1e3a5f"}}}%%
sequenceDiagram
autonumber
actor User
participant MCP as FastMCP Server
participant A1 as LLMIntentParser<br/>(Agent 1)
participant GDB as Graph Catalog<br/>(Neo4j / Fixture)
participant GEN as Generator +<br/>JavaValidator
participant A2 as ReviewAgent<br/>(Agent 2)
User->>MCP: generate_java_test_nlp(free-form NL)
MCP->>A1: extract intent fields
Note over A1: gpt-4o-mini · temp=0<br/>strict JSON schema
A1-->>MCP: {class, package, module, config, version}
MCP->>GDB: get versioned symbols
GDB-->>MCP: 7 cited GraphSymbol objects
MCP->>GEN: render Java + validate
Note over GEN: Tree-sitter AST<br/>contract · grounding · safety
GEN-->>MCP: validated Java source
MCP->>A2: review(source, class, package)
Note over A2: gpt-4o-mini · temp=0<br/>6-item checklist
A2-->>MCP: {approved, checklist, issues}
MCP-->>User: {status, source, citations, review}Panel de evidencias
Todas las mediciones utilizan fixtures sintéticos generados de forma independiente y licenciados bajo CC0.
Los resultados proceden de la política aceptada strict_graph_v2 sobre el conjunto de confirmación reservado.
| Métrica | Resultado | Artefacto | | -------------------------------------- | :---------- ----------------------------------------------------------------- | ----------------------------------------------------------- | | Escala del benchmark | 96 CC0 intents — 32 dev / 32 val / 32 confirmación | task_evaluation.json | | Tasa de éxito en la confirmación | 32 / 32 tareas acotadas | evaluation_trace.json | | Validación del código fuente generado | 24 / 24 intenciones admitidas — sintaxis + contrato + anclaje + seguridad | task_evaluation.json | | Rechazo adversarial seguro | 8 / 8 — cero aceptaciones erróneas | task_evaluation.json | | Presición de citas | 100 % — solo se importan símbolos citados por el grafo | task_evaluation.json | | Recall de símbolos requeridos | 100 % — todos los símbolos requeridos están presentes | task_evaluation.json | | Integración live con Neo4j | Neo4j 5.26.29 — 8 símbolos, 12 métodos materializados | neo4j_integration.json | | Benchmark MCP oficial | 120 / 120 resultados esperados — cero errores de protocolo | mcp_benchmark.json | | Latencia en caliente de MCP (p50 / p95 / p99) | 29.13 / 48.61 / 54.23 ms en concurrencia 1 | mcp_benchmark.json | | Compilación de Java | 8 / 8 archivos de clase con Eclipse ECJ 3.21 | java_compile.json | | Llamadas a modelos externos (ruta determinista) | 0 llamadas · $0.00 | mcp_benchmark.json |
Las cifras de latencia son mediciones locales mono-proceso en Windows, no SLOs de producción.
Selección de Política
Se evaluaron cuatro políticas de generación. El objetivo de selección se declaró antes de abrir el conjunto de confirmación de: maximizar el éxito de validación de tareas entre los candidatos que pasan todas las puertas de seguridad. La confirmación se abrió exactamente una vez para el candidato seleccionado.
%%{init: {"theme": "base", "themeVariables": {"quadrant1Fill": "#155724", "quadrant2Fill": "#856404", "quadrant3Fill": "#721c24", "quadrant4Fill": "#856404"}}}%%
xychart-beta
title "Validation: task success vs safe-rejection recall (%)"
x-axis ["no_graph_v0", "lenient_repair_v1", "strict_graph_v2 ✓", "wide_context_v3"]
y-axis "Task success (%)" 0 --> 105
bar [21.9, 75.0, 100.0, 96.9]
line [87.5, 0.0, 100.0, 87.5]Candidata | Tareas correctas | Generación válida | Rechazo seguro | Precisión de citas | Decisión |
| 21.9% | 0% | 87.5% | 0% | Rechazada — sin anclaje |
| 72.5% | 100% | 0% | 100% | Rechazada — 8 falsas aceptaciones |
| 100% | 100% | 100% | 100% | Seleccionada |
| 96.9% | 100% | 87.5% | 87.5% | Rechazada — contexto irrelevante + 1 aceptación errónea |
Herramientas MCP
Herramienta | Tipo | Comportamiento |
| Lectura | Develve ident, integridad, proveniencia, licencia, backend y número de símbolos del fixture |
| Lectura | Búsqueda parametrizada de nombres/métodos; máx. 20 resultados |
| Generación | Campos tipados → búsqueda en grafo → Java → todas las compuertas de validación |
| Generación | Gramática acotada de 3 formas → la misma política estricta |
| Validación | Comprueba hasta 20 000 caracteres; nunca escribe ni ejecuta el código |
| Multiagente | CLI de intenciones LLM → generador → revisor LLM; requiere |
El adaptador Neo4j usa Cypher estricto y parametrizado, rechaza credenciales en URIs y rechaza las dish sidentidades de los fixtures.
Inicio Rápido
python -m venv .venv
# Windows
.\.venv\Scripts\Activate.ps1
# Linux / macOS
source .venv/bin/activate
pip install -r requirements-dev.txt
pip install --no-deps -e .
# Run the offline smoke test (no database needed)
python scripts/container_smoke.py python -m graph_mcp.serverConfiguración del cliente MCP (VS Code / Claude Desktop)
{
"mcpServers": {
"graph-java-gen": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "graph_mcp.server"],
"cwd": "/absolute/path/to/repo"
}
}
}Habilitar la herramienta NLP multiagente
# Add to your environment or .env file
OPENAI_API_KEY=sk-...
GRAPH_BACKEND=neo4j # optional; defaults to local JSON fixtureReproducción de Evidencias
# Build the CC0 benchmark fixture
python scripts/build_evaluation_fixture.py
# Run all four candidate policies and select strict_graph_v2
python scripts/evaluate_workflow.py
# Validate the claims ledger and evidence privacy rules
python scripts/validate_evidence.py
# Full test suite
pytest --cov=src --cov-report=term-missing --cov-fail-under=75
# Lint and security
ruff check src tests scripts
bandit -r src scripts -q -ll
pip-audit -r requirements.txt --progress-spinner offRuta live de Neo4j
# Start a local Neo4j Community instance (Docker)
docker compose up -d neo4j
python scripts/wait_for_neo4j.py
# Seed the synthetic graph fixture and verify retrieval
python scripts/seed_graph.py
python scripts/verify_neo4j.py # writes evidence/neo4j_integration.json
# Full MCP benchmark over stdio with live graph
python scripts/benchmark_mcp.py # writes evidence/mcp_benchmark.jsonCompilación de Java
# Requires JDK 21 on PATH
python scripts/compile_generated.py --require-compiler
# Writes evidence/java_compile.jsonDiseño de Seguridad
-coneximientos en MCP No hay Cypher en bruto en la superficie — todas las consultas a grafos están parámetizadas.
Lista blanca estricta de campos — los nombres de clase, nombres de package, nombres de módulo, versiones y rutas de configuración se comprueban contra patrones regex compilados antes de ninguna búsqueda en el grafo.
Scanner de seguridad de código fuente — el Java generado se rechaza si hace referencia a
Runtime.getRuntime,ProcessBuilder,System.exit,java.io,java.nio.file, ojava.net.Prevención de path de recorrido — las rutas absolutas y los segmentos
..se rechazan en los campos de rutas de configuración.Aplicación del anclaje al grafo — cada importación en el código fuente generado debe corresponder a un símbolo recuperado del grafo para esa versión exacta.
Salida del LLM revalidada — los campos extraídos por el analizador de intenciones LLM pasan por la misma validación
GenerationIntent.from_mapping()que las llamadas directas a la API.Credenciales de Neo4j — se cargan solo desde variables de entorno, y nunca se registran ni se devuelven en artefactos de evidencia.
Preflight XML —
defusedxmlpreviene ataques de expansión de entidades en el escaneo de la estructura del proyecto.Contenedor — imagen Linux Chainguard fijada, no root UID/GID 65532; el CI ejecuta una prueba de smoke de MCP por contenedor con stdio.
Vea SECURITY.md para conocer la superficie de amenaza completa.
Mapa del repositorio
src/graph_mcp/
workflow.py intent parsing · graph lookup · Java generation · validation
graph_store.py Neo4j catalog adapter (parameterised Cypher)
llm_intent_parser.py Agent 1 — LLM free-form NL → GenerationIntent
review_agent.py Agent 2 — LLM post-generation checklist reviewer
server.py FastMCP stdio server (7 tools)
evaluation.py candidate scoring and selection harness
fixtures/
synthetic_graph.json CC0 versioned framework symbol catalog (SHA-256 bound)
evaluation_cases.json 96 CC0 natural-language intents (32/32/32 split)
java_framework/ 7 independently generated Java stub classes
evidence/
claims.json machine-readable claims ledger (14 public claims)
evaluation_protocol.json pre-declared selection rules and safety gates
task_evaluation.json per-candidate, per-split, per-case results
evaluation_trace.json confirmation case-level trace
neo4j_integration.json live Neo4j integration result
mcp_benchmark.json MCP protocol benchmark (120 calls)
java_compile.json ECJ compilation result
scripts/
build_evaluation_fixture.py generate benchmark from seed
evaluate_workflow.py run and score all four candidates
validate_evidence.py verify claims ledger and privacy rules
benchmark_mcp.py official MCP stdio latency benchmark
verify_neo4j.py live graph integration check
compile_generated.py ECJ compile gate
seed_graph.py materialise fixture into Neo4j
tests/
test_generation_loop.py generation + validation unit tests
test_graph_store.py Neo4j adapter unit tests
test_mcp_protocol.py official MCP protocol conformance
test_evaluation.py evaluation harness tests
test_evidence.py claims ledger integrity tests
test_neo4j_live.py opt-in live graph tests (NEO4J_* env required)
docs/
ARCHITECTURE.md component design and data flow
POLICY_CARD.md candidate selection details
DATA_CARD.md fixture provenance and license
MCP_INTEGRATION.md client configuration guide
DEPLOYMENT.md Docker and container notes
templates/ MCP prompt templates for VS Code Copilot
examples/ sample project preflight scannerLímites
El siguiente no se reclama en este repositorio:
Calidad del parser de intenciones de formato libre independiente de la versión del modelo — el pipeline LLM es optativo y sus resultados no se registran en los artefactos de evaluación congénereados.
Compatibilidad con cualquier framework de pruebas Java propietario o confidencial.
Latencia SLO de producción — todas las medidas son benchmarks secuenciales locales de un solo proceso.
Operación concurrente, o alta disponibilidad distribuida.
Ejecución automática del Java generado contra hardware o un instrumento de prueba.
Ningún ahorro de productividad, costo, cuota o tiempo de pruebas — este repositorio contiene solo evidencia de generación.
La lista completa y legible por máquina se publica en evidence/claims.json.
Licencia
Código del repositorio: MIT. Fixtures del grafo, asignaciones de entidades y stubs de Java: CC0-1.0 (señalado en los metadatos del fixture).
Available Tools
6 toolsgenerate_java_testD
Generate Java only when graph grounding, syntax, contract, and safety pass.
Inputs: class_name (required), config_path (required), module_name (required), package_name (required), +1 more. Returns: object
generate_java_test_from_intentC
Parse a bounded natural-language request, generate Java, and enforce all gates.
Inputs: request (required). Returns: object
generate_java_test_nlpB
Multi-agent pipeline: LLM parses free-form NL, generates Java, LLM reviews it.
Agent 1 (LLMIntentParser) normalises natural language to a structured intent. The deterministic generator produces graph-cited, validated Java source. Agent 2 (ReviewAgent) audits the result against a six-item checklist. Requires OPENAI_API_KEY in the environment.
Inputs: request (required). Returns: object
get_fixture_metadataA
Return provenance and version information for the active graph fixture.
Inputs: no named parameters. Returns: object
search_graphB
Search the bounded synthetic graph by class, qualified name, or method.
Inputs: query (required), limit, version. Returns: object
validate_java_sourceC
Validate bounded Java source against syntax, graph, contract, and safety gates.
Inputs: source (required), class_name (required), config_path (required), module_name (required), +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools are mostly distinct: metadata retrieval, graph search, three variations of Java test generation, and validation. The three generate_java_test* tools could be confused, but their descriptions clearly differentiate by input type (structured, bounded NL, free-form NL with review). Minor overlap exists but descriptions resolve ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case: get_fixture_metadata, search_graph, generate_java_test, generate_java_test_from_intent, generate_java_test_nlp, validate_java_source. The naming is predictable and uniform throughout the set.
With 6 tools, the server is well-scoped for its purpose of generating and validating Java tests from a synthetic graph. Each tool serves a clear role in the workflow, and the count feels appropriate—not too few to be inadequate, not too many to be unwieldy.
The tool surface covers the full lifecycle: metadata retrieval, graph search for grounding, three generation pathways (including NL-based variants), and validation. There are no obvious missing operations for the stated purpose; the server provides a complete pipeline from context gathering to output validation.
Maintenance
Related MCP Connectors
Ship better Java with your coding agent.
Write, run and check natural-language browser tests of your web app from your AI assistant.
QA platform for agents: coverage signals, in-repo test plans, verified tests and release governance.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables LLM clients to generate standardized test cases, perform quality control with lint scoring, convert to Xray/Jira format, and compose test suites (Smoke/Regression/E2E) with coverage analysis.92MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to analyze Java and Web projects, automatically generate unit tests (JUnit) and end-to-end tests (Selenium), and execute them directly through Maven or NPM commands.-
- AlicenseNot gradedqualityBmaintenanceConverts natural-language requests into validated, compilable Java test methods, grounding all symbols in a graph catalog and enforcing strict correctness via multi-layer validation.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to query a semantic code graph over MCP, retrieving exact function source, definitions, callers/callees, impact analysis, and minimal test selection instead of whole files.14Apache 2.0