uce-engine 0.2.1

Unified Context Engine

Unified Context Engine (UCE)

UCE builds a deterministic knowledge graph over code, schema, requirements, policies, and RBAC authority rules in Neo4j, then exposes reasoning and mutation tools through an MCP server.

What You Get

• uce CLI for ingestion + watcher + MCP server
• neo4j-mcp CLI for Neo4j MCP bridge (used by LLM ingestion)
• Graph reasoning tools (impact_analysis, explain_change, risk_assessment)
• RBAC-gated mutation tools (authorize_change, write_file, delete_file)

Architecture (Important)

• Goose connects to UCE MCP only: http://127.0.0.1:9001/mcp/
• Neo4j-MCP is backend-only: http://127.0.0.1:8000/mcp/
• UCE uses Neo4j-MCP internally for LLM ingestion operations.

If Goose is connected directly to Neo4j-MCP, RBAC can be bypassed.

Quickstart (Recommended: Reproducible Docker)

1) Prepare environment file

copy .env.docker.example .env.docker
# Linux/macOS: cp .env.docker.example .env.docker

Edit .env.docker if you need different ports, credentials, target repo path, or LLM provider settings.

2) Start full stack

docker compose --env-file .env.docker up -d --build

This starts:

• Neo4j (7687, 7474)
• Keycloak (8080)
• Neo4j-MCP (8000)
• UCE MCP (9001)

3) Bootstrap Keycloak realm clients, role mappers, and fresh secrets

python scripts/bootstrap_keycloak.py \
  --base-url http://localhost:8080 \
  --public-base-url http://localhost:8080 \
  --realm uce-realm \
  --audience uce-mcp \
  --output-env-file .keycloak-secrets.env

This script ensures:

• realm roles: viewer, editor, admin
• clients: uce-viewer, uce-editor, uce-admin
• mappers:
  • hardcoded role claim
  • custom audience claim (aud=uce-mcp)
• regenerated client secrets (no hardcoded demo secrets)

4) Mint role tokens

Use values from .keycloak-secrets.env.

Example (PowerShell):

$realm = "uce-realm"
$base = "http://localhost:8080"

function Get-ClientToken($clientId, $clientSecret) {
  (Invoke-RestMethod -Method Post `
    -Uri "$base/realms/$realm/protocol/openid-connect/token" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body "grant_type=client_credentials&client_id=$clientId&client_secret=$clientSecret").access_token
}

$viewerToken = Get-ClientToken "uce-viewer" "<VIEWER_SECRET>"
$editorToken = Get-ClientToken "uce-editor" "<EDITOR_SECRET>"
$adminToken  = Get-ClientToken "uce-admin" "<ADMIN_SECRET>"

5) Configure Goose extensions

Create three Goose extensions (or profiles/sessions):

• UCE Viewer
• UCE Editor
• UCE Admin

All three use the same URL:

• http://127.0.0.1:9001/mcp/

Each uses a different auth header:

• Authorization: Bearer <viewer_token>
• Authorization: Bearer <editor_token>
• Authorization: Bearer <admin_token>

RBAC Demo Walkthrough

1. Viewer tries write_file -> denied.
2. Editor writes to allowed app path -> allowed.
3. Editor tries writing RBAC policy path -> denied.
4. Admin writes/deletes in admin-approved scope -> allowed.

Escalation prevention settings

Use these for hard enforcement:

RBAC_ENABLED=true
RBAC_ENFORCE_MODE=enforced
RBAC_DENY_DEFAULT=true

Protect policy sources so non-admin users cannot self-promote by editing governance files.

Manual Setup (Without Docker)

Prerequisites

• Python >=3.10,<3.13
• Neo4j running and reachable
• Keycloak running (if RBAC enabled)

Install

pip install uce-engine

Create config

Run with:

uce --config path/to/config.yaml

Minimal config.yaml shape:

project_root: .
languages: [python, typescript, javascript, go, java, c, cpp]
paths:
  code: [.] 
  schema: [db, src/db]
  requirements: [requirements, src/requirements, artifacts/requirements]
  policies: [policies, src/policies, artifacts/policies]
  rbac: [rbac, src/rbac, artifacts/rbac]
  backend: [src, server, app]
  identifiers: []
ignore: [.git, node_modules, venv, .venv, dist, build, __pycache__]
aliases: {}
neo4j:
  uri: bolt://localhost:7687
  user: neo4j
  password: testpassword

Required env for RBAC mode

RBAC_ENABLED=true
RBAC_ENFORCE_MODE=enforced
RBAC_DENY_DEFAULT=true
RBAC_JWT_ISSUER=http://localhost:8080/realms/uce-realm
RBAC_JWT_AUDIENCE=uce-mcp
RBAC_JWKS_URI=http://localhost:8080/realms/uce-realm/protocol/openid-connect/certs
RBAC_CLOCK_SKEW_SECONDS=60
UCE_MCP_TRANSPORT=http

MCP Tools

• impact_analysis
• explain_change
• risk_assessment
• count_functions_in_file
• find_identifier_usage
• authorize_change
• write_file
• delete_file

Additional Docs

• Tutorial: TUTORIAL.md
• Demo script: DEMO_SCRIPT.md
• Operator runbook: OPERATOR_RUNBOOK.md
• Release checklist: RELEASE_CHECKLIST.md

Notes on LLM Ingestion

Requirements, policies, and RBAC documents are ingested through the LLM pipeline. Ensure your .env/.env.docker includes either:

• OpenAI credentials (LLM_PROVIDER=openai, OPENAI_API_KEY=...), or
• Local OpenAI-compatible endpoint (LLM_PROVIDER=local, LOCAL_LLM_BASE_URL=..., etc.).

License

MIT