uce-engine 0.1.4

Unified Context Engine

Unified Context Engine (UCE)

UCE builds a deterministic knowledge graph of a codebase in Neo4j and exposes reasoning tools over that graph. It works across repositories, supports multiple languages, and continuously updates when files change.

This package is pip-installable and CLI-friendly.

What UCE Does

• Ingests source code, schema, requirements, and policies into a Neo4j graph.
• Tracks files, functions, classes, methods, tables, columns, requirements, and policies.
• Provides deterministic impact analysis and risk assessment.
• Keeps the graph up-to-date via a file watcher.
• Exposes reasoning tools through an MCP server.

Supported Languages

UCE uses Tree-sitter and supports:

• Python
• TypeScript
• JavaScript
• Go
• Java
• C
• C++

Prerequisites

• Python 3.10+ (recommended: 3.10 on Windows due to Tree-sitter wheels)
• Neo4j running locally or remotely

Neo4j Setup (Local)

1. Install Neo4j Desktop or Neo4j Server.
2. Start a database and note the Bolt URI (default: bolt://localhost:7687).
3. Set a username and password.

Neo4j Setup (Docker)

docker run --name neo4j-uce -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  neo4j:5

Install

pip install uce-engine

Configure

Create a config.yaml file in any folder (recommended in the repo you want to analyze).

Example:

project_root: .

languages:
  - python
  - typescript
  - javascript
  - go
  - java
  - c
  - cpp

paths:
  code:
    - core
    - ingestion
    - runtime
    - server
    - reasoning
  schema: []
  requirements:
    - artifacts/requirements
  policies:
    - artifacts/policies
  identifiers: # optional: limit identifier usage indexing to these paths
    - server

ignore:
  - .git
  - .next
  - __pycache__
  - node_modules
  - venv
  - dist
  - build
  - coverage
  - .idea
  - .vscode
  - ui
  - views
  - public
  - assets
  - styles
  - css
  - scss
  - ".log"

aliases:
  "@/": src/

neo4j:
  uri: bolt://localhost:7687
  user: neo4j
  password: testpassword

Optional .env (recommended for local development)

UCE can load environment variables from a .env file.

Defaults:

• UCE looks for .env at the repo root (next to config.yaml).
• You can override the location with UCE_DOTENV_PATH.

We include a template at .env.example. Copy it to .env and fill in your values. Do not commit .env (it contains secrets).

Common variables:

• NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
• LLM_PROVIDER, OPENAI_API_KEY
• NEO4J_TRANSPORT_MODE, NEO4J_MCP_HTTP_URL

How ignore Works

ignore entries are substring path filters applied to relative file paths. If a file path contains /ui/ or starts with ui/, it will be skipped.

Globs like "*.log" are treated as literal substrings unless you customize the matcher.

Run (CLI)

From anywhere:

uce --config path/to/config.yaml

This will:

1. Load configuration
2. Connect to Neo4j
3. Build or update the graph
4. Start the file watcher
5. Launch the MCP server

Run End-to-End (LLM Ingestion)

If you want LLM-based requirements/policies ingestion, you also need the Neo4j MCP server running.

1. Start Neo4j and ensure credentials are correct.
2. Create .env from .env.example and set:
   • LLM_PROVIDER, OPENAI_API_KEY (or Anthropic equivalents)
   • NEO4J_TRANSPORT_MODE=http
   • NEO4J_MCP_HTTP_URL=http://127.0.0.1:8000/mcp/
3. In a separate terminal, start the Neo4j MCP server:

python neo4j-mcp/server.py --transport http --server-host 127.0.0.1 --server-port 8000 --server-path /mcp/

4. Run UCE:

uce --config path/to/config.yaml

Stdio MCP (optional)

If you prefer stdio, set:

NEO4J_TRANSPORT_MODE=stdio
NEO4J_MCP_COMMAND=.../python -u neo4j-mcp/server.py --transport stdio

Then run uce --config ... without starting the MCP server separately.

Run (Library)

from run import run_uce

run_uce("path/to/config.yaml")

MCP Tools

UCE exposes reasoning tools via MCP:

• impact_analysis
• explain_change
• risk_assessment
• count_functions_in_file (AST-lite helper)
• find_identifier_usage (AST-lite helper)

These tools query the graph (no ingestion logic).

What Nodes Are In The Graph

• File
• Function
• Class
• Method
• Table
• Column
• Requirement
• Policy
• Identifier (optional, AST-lite usage index)

If you want additional node types (e.g., Dependencies, Endpoints, Services), add them in ingestion and reasoning layers.

Typical Workflow

1. Install Neo4j and start it.
2. Create config.yaml pointing to your repo.
3. Run uce --config config.yaml.
4. Query the MCP server or Neo4j to explore the graph.

Troubleshooting

Neo4j auth error

• Verify neo4j.uri, neo4j.user, neo4j.password in config.yaml.
• Make sure the database is running.

APOC missing (schema ingestion error)

• If you see There is no procedure with the name apoc.meta.schema, install the APOC plugin.
• Neo4j Desktop: open your DB → Plugins → install APOC → restart the DB.
• Docker: set NEO4J_PLUGINS='["apoc"]' and restart the container.

Tree-sitter parser error on Windows

• Use Python 3.10 in a clean venv.

No schema/requirements/policies detected

• Check paths.schema, paths.requirements, paths.policies in config.yaml.

License

MIT