Skip to main content
Glama
graph-mcp-java-gen

graph-mcp-java-gen

graph-mcp-java-gen

[![CI](https://github.com/jend... [Python(pyproject.toml) [Evidence(evidence/claims.json) [License(LICENSE) [MCP(src/graph_mcp/server.py) [N eo4j(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"| OK

Related 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

no_graph_v0

21.9%

0%

87.5%

0%

Rechazada — sin anclaje

lenient_repair_v1

72.5%

100%

0%

100%

Rechazada — 8 falsas aceptaciones

strict_graph_v2

100%

100%

100%

100%

Seleccionada

wide_context_v3

96.9%

100%

87.5%

87.5%

Rechazada — contexto irrelevante + 1 aceptación errónea


Herramientas MCP

Herramienta

Tipo

Comportamiento

get_fixture_metadata

Lectura

Develve ident, integridad, proveniencia, licencia, backend y número de símbolos del fixture

search_graph

Lectura

Búsqueda parametrizada de nombres/métodos; máx. 20 resultados

generate_java_test

Generación

Campos tipados → búsqueda en grafo → Java → todas las compuertas de validación

generate_java_test_from_intent

Generación

Gramática acotada de 3 formas → la misma política estricta

validate_java_source

Validación

Comprueba hasta 20 000 caracteres; nunca escribe ni ejecuta el código

generate_java_test_nlp

Multiagente

CLI de intenciones LLM → generador → revisor LLM; requiere OPENAI_API

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

Configuració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 fixture

Reproducció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 off

Ruta 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.json

Compilación de Java

# Requires JDK 21 on PATH
python scripts/compile_generated.py --require-compiler
# Writes evidence/java_compile.json

Diseñ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, o java.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 — defusedxml previene 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 scanner

Lí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 tools
generate_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

    B3/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers