# graph-mcp-java-gen

[![CI](https://github.com/rajendarmuddasani/GraphDB_GenAI_MCP_Test_Program_Development/actions/workflows/ci.yml/badge.svg)](https://github.com/rajendarmuddasani/GraphDB_GenAI_MCP_Test_Program_Development/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.12-4ea5d9)](pyproject.toml)
[![Evidence](https://img.shields.io/badge/evidence-validated-18745a)](evidence/claims.json)
[![License](https://img.shields.io/badge/license-MIT-f3c969)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-stdio-7b4ea0)](src/graph_mcp/server.py)
[![Neo4j](https://img.shields.io/badge/Neo4j-5.26-008CC1)](evidence/neo4j_integration.json)

**Graph-grounded MCP server that converts natural-language requests into validated, compilable Java test methods — no hallucinated imports, no ungrounded symbols, no silent failures.**

A natural-language or structured request enters an official Model Context Protocol (MCP) stdio server. A versioned graph catalog (Neo4j or JSON fixture) supplies the only symbols the generator may cite. A multi-layer validator checks syntax, framework contract, grounding, and forbidden-API rules before any source is returned. Two optional LLM agents — an intent normaliser and a post-generation reviewer — extend the pipeline to free-form input without compromising the deterministic safety envelope.

---

## Architecture

```mermaid
%%{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
```

---

## Multi-Agent Pipeline

```mermaid
%%{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}
```

---

## Evidence Dashboard

All measurements use independently generated CC0-licensed synthetic fixtures.
Results are from the accepted `strict_graph_v2` policy on the held-out confirmation split.

| Surface | Result | Artifact |
|---|:---|---|
| Benchmark scale | 96 CC0 intents — 32 dev / 32 val / **32 confirmation** | [task_evaluation.json](evidence/task_evaluation.json) |
| Confirmation task success | **32 / 32** bounded tasks | [evaluation_trace.json](evidence/evaluation_trace.json) |
| Generated-source validation | **24 / 24** supported intents — syntax + contract + grounding + safety | [task_evaluation.json](evidence/task_evaluation.json) |
| Safe adversarial rejection | **8 / 8** — zero false accepts | [task_evaluation.json](evidence/task_evaluation.json) |
| Citation precision | **100%** — only graph-cited symbols imported | [task_evaluation.json](evidence/task_evaluation.json) |
| Required-symbol recall | **100%** — every required symbol present | [task_evaluation.json](evidence/task_evaluation.json) |
| Live Neo4j integration | **Neo4j 5.26.29** — 8 symbols, 12 methods materialized | [neo4j_integration.json](evidence/neo4j_integration.json) |
| Official MCP benchmark | **120 / 120** expected outcomes — zero protocol errors | [mcp_benchmark.json](evidence/mcp_benchmark.json) |
| MCP warm latency (p50 / p95 / p99) | **29.13 / 48.61 / 54.23 ms** at concurrency 1 | [mcp_benchmark.json](evidence/mcp_benchmark.json) |
| Java compilation | **8 / 8 class files** via Eclipse ECJ 3.21 | [java_compile.json](evidence/java_compile.json) |
| External model calls (deterministic path) | **0 calls · $0.00** | [mcp_benchmark.json](evidence/mcp_benchmark.json) |

> Latency figures are single-process local Windows measurements, not production SLOs.

---

## Policy Selection

Four generation policies were evaluated. The selection objective was declared before opening the confirmation split: maximise validation task success among candidates passing **all** safety gates. Confirmation was opened exactly once for the selected candidate.

```mermaid
%%{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]
```

| Candidate | Task success | Gen valid | Safe reject | Citation prec | Decision |
|---|:---:|:---:|:---:|:---:|---|
| `no_graph_v0` | 21.9% | 0% | 87.5% | 0% | Rejected — no grounding |
| `lenient_repair_v1` | 75.0% | 100% | 0% | 100% | Rejected — 8 false accepts |
| **`strict_graph_v2`** | **100%** | **100%** | **100%** | **100%** | **Selected** |
| `wide_context_v3` | 96.9% | 100% | 87.5% | 87.5% | Rejected — irrelevant context + 1 false accept |

---

## MCP Tools

| Tool | Type | Behaviour |
|---|---|---|
| `get_fixture_metadata` | Read | Returns fixture identity, provenance, license, backend, symbol count |
| `search_graph` | Read | Parameterised name/method search; max 20 results |
| `generate_java_test` | Generate | Typed fields → graph lookup → Java → all validation gates |
| `generate_java_test_from_intent` | Generate | Bounded 3-form grammar → same strict policy |
| `validate_java_source` | Validate | Checks up to 20 000 chars; never writes or executes source |
| `generate_java_test_nlp` | **Multi-agent** | LLM intent parser → generator → LLM reviewer; requires `OPENAI_API_KEY` |

The Neo4j adapter uses fixed parameterised Cypher, rejects credentials in URIs, and refuses fixture identity collisions.

---

## Quick Start

```bash
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
```

### MCP client configuration (VS Code / Claude Desktop)

```json
{
  "mcpServers": {
    "graph-java-gen": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "graph_mcp.server"],
      "cwd": "/absolute/path/to/repo"
    }
  }
}
```

### Enable the multi-agent NLP tool

```bash
# Add to your environment or .env file
OPENAI_API_KEY=sk-...
GRAPH_BACKEND=neo4j   # optional; defaults to local JSON fixture
```

---

## Reproduce Evidence

```bash
# 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
```

### Live Neo4j path

```bash
# 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
```

### Java compilation

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

---

## Security Design

- **No raw Cypher on the MCP surface** — all graph queries are parameterised.
- **Strict field allowlists** — class names, package names, module names, versions, and config paths are checked against compiled regex patterns before any graph lookup.
- **Source safety scanner** — generated Java is rejected if it references `Runtime.getRuntime`, `ProcessBuilder`, `System.exit`, `java.io`, `java.nio.file`, or `java.net`.
- **Path traversal prevention** — absolute paths and `..` segments are rejected in config path fields.
- **Grounding enforcement** — every import in generated source must correspond to a symbol retrieved from the graph for that exact version.
- **LLM output re-validated** — fields extracted by the LLM intent parser pass through the same `GenerationIntent.from_mapping()` validation as direct API calls.
- **Neo4j credentials** — loaded only from environment variables; never logged or returned in evidence artifacts.
- **XML preflight** — `defusedxml` prevents entity-expansion attacks in project-structure scanning.
- **Container** — pinned Chainguard Linux image, non-root UID/GID 65532; CI performs an MCP-over-container stdio smoke test.

See [SECURITY.md](SECURITY.md) for the full threat boundary.

---

## Repository Map

```
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
```

---

## Boundaries

The following are **not** claimed by this repository:

- Free-form intent parsing quality independent of model version — the LLM pipeline is opt-in and its results are not captured in the frozen evaluation artifacts.
- Compatibility with any proprietary or confidential Java test framework.
- Production latency SLO — all measurements are single-process local sequential benchmarks.
- Concurrent, distributed, or high-availability operation.
- Automatic execution of generated Java against hardware or a test instrument.
- Any productivity, cost, yield, or test-time saving — this repository contains only generation and validation evidence.

The full machine-readable boundary is in [evidence/claims.json](evidence/claims.json).

---

## License

Repository code: **MIT**.
Graph fixture, intent cases, and Java stubs: **CC0-1.0** (labelled in fixture metadata).