Valem MCP Server
README.md
# Valem
**A spreadsheet engine for AI agents.** An LLM describes a domain as a JSON spec (fields, formulas,
invariants); Valem compiles it into a live model that recomputes every dependent value on each change,
refuses changes that break a rule, and can explain why any number is what it is.
[](https://valem.run/)
[](https://valem.run/docs/)
[](https://valem.run/docs/getting-started/connect-your-agent.html)
[](https://github.com/vlad-public-code/org.json-kula.valem/releases/latest)
[](LICENSE)
## Why
LLMs are good at *describing* a domain and bad at *keeping state consistent* over it. Ask one to
maintain a quote, an order, or a loan application across twenty turns and the total drifts from its
line items, a limit checked three messages ago is forgotten, and arithmetic is off by a rounding step.
Valem moves the rules out of the conversation and into a deterministic runtime:
- **Derivations** are JSONata formulas over JSON paths, recomputed in dependency order (only what a
change touches).
- **Constraints** are invariants checked before a change commits: roll it back or flag it.
- **Effects** (HTTP calls, LLM calls, timers) are emitted as data and run after the commit, so replay
never re-fires I/O.
- **Explain and audit**: every value has a derivation trace, and the audit trail is hash-chained.
The agent writes the spec; Valem validates it, tests it, and keeps it true.
## Try it in 30 seconds
**In the browser, no install.** Open [valem.run](https://valem.run/), describe a model in plain
words ("a mortgage with overpayments", "an invoice with VAT and discounts"), then type into the live
form and watch every derived value update.
**From your agent (MCP, hosted, nothing to download):**
```bash
# Claude Code
claude mcp add --transport http valem https://valem.run/mcp
```
Claude Desktop: Settings → Connectors → *Add custom connector* → `https://valem.run/mcp`. Then ask
the agent to call `pair_browser` and it will build models you see live in a browser tab. The
authoring tools (`validate_spec`, `eval_expression`, `test_spec`, `dry_run`) work without pairing.
Guide: [Connect your agent](https://valem.run/docs/getting-started/connect-your-agent.html).
**Self-hosted with Docker:**
```bash
docker run --rm -p 8080:8080 ghcr.io/vlad-public-code/valem:latest
# → http://localhost:8080 (management UI, REST + WebSocket API, and /mcp)
```
## What a spec looks like
```json
{
"id": "order",
"version": "1.0.0",
"schema": {},
"derivations": [
{ "path": "$.order.items[*].lineTotal", "expr": "$parent.qty * $parent.price" },
{ "path": "$.order.total", "expr": "$sum(order.items.(qty * price))" }
],
"constraints": [
{ "id": "max-order", "expr": "order.total <= 5000",
"message": "Order exceeds the cap", "policy": "rollback" }
]
}
```
Write `qty` on any line item and `lineTotal` and `total` recompute; a write that pushes the total
over 5,000 is rejected before it commits. Full format:
[ModelSpec reference](https://valem.run/docs/reference/model-spec-format.html).
## Ways to run it
| You want | Use |
|---|---|
| An agent that maintains structured state | The [MCP server](https://valem.run/docs/deployment/mcp-server.html), hosted (`valem.run/mcp`) or self-hosted (stdio jar from [Releases](https://github.com/vlad-public-code/org.json-kula.valem/releases)) |
| A backend shared by many clients | [`valem-web`](https://valem.run/docs/deployment/web-api.html): REST + WebSocket, pluggable storage (filesystem, Postgres, Mongo, Redis, S3) |
| The engine inside your JVM app | [Embed `valem-core`/`valem-service`](https://valem.run/docs/extending/embedding.html) |
| Scripting with no server | The [JSON console](https://valem.run/docs/reference/api-reference.html#3-console-json-protocol) (one JSON command per line on stdin) |
| A live model inside your web page | [Embed a live model](https://valem.run/docs/usage-scenarios/embed-a-live-model.html) |
Clients: [TypeScript and Java SDKs](https://valem.run/docs/extending/client-sdks.html).
## Documentation
Published at **[valem.run/docs](https://valem.run/docs/)** (source in [`docs/`](docs/README.md)),
organised in six chapters: **Getting started**, **Usage scenarios**, **Model guide**, **Reference**,
**Deployment**, **Extending**. Good first reads:
- [What is Valem?](https://valem.run/docs/getting-started/what-is-valem.html): the idea in five minutes
- [Valem vs alternatives](https://valem.run/docs/getting-started/compared.html): how it compares to code interpreters, rules engines, form libraries and spreadsheets
- [FAQ, and when not to use Valem](https://valem.run/docs/getting-started/faq.html)
- [ModelSpec format](docs/reference/model-spec-format.md): the spec format, single source of truth
- [API reference](docs/reference/api-reference.md): REST, WebSocket, and console protocol
- [MCP tools](docs/reference/mcp-tools.md): every tool and resource the MCP server exposes
- [Configuration](docs/deployment/configuration.md): every `valem.*` property
- [Security model](docs/deployment/security-model.md): auth, effect egress/SSRF, limits
- [Architecture](docs/extending/architecture.md): component map, data flow, design decisions
- For agents: [llms.txt](https://valem.run/docs/llms.txt)
## Building from source
### Prerequisites
- Java 21+
- Maven 3.9+
- Node.js 20+ and npm 9+ (UI only)
## Running the console app (no HTTP server required)
The console app is the fastest way to use Valem from a script or an AI agent. It reads one JSON
command per line from `stdin` and writes one JSON response per line to `stdout`. No HTTP, no
browser, no server process. All state is held in memory for the lifetime of the process.
```bash
# Build the fat jar (first time)
mvn install -pl valem-core,valem-service -q
mvn package -pl valem-console -q
# Run interactively
java -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar
# Or pipe commands
echo '{"cmd":"list-models"}' | java -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar
```
Example session:
```jsonc
// stdin
{"cmd":"create-model","spec":{"id":"order","version":"1.0.0","schema":{},"derivations":[{"path":"$.total","expr":"subtotal + tax"}]}}
{"cmd":"mutate","id":"order","mutations":{"$.subtotal":100,"$.tax":8}}
{"cmd":"get-state","id":"order"}
// stdout
{"ok":true,"result":{"id":"order","status":"created"}}
{"ok":true,"result":{"success":true,"mutatedPaths":["$.subtotal","$.tax"],"derivedUpdated":["$.total"],...}}
{"ok":true,"result":{"subtotal":100,"tax":8,"total":108}}
```
Full command list: [console JSON protocol](docs/reference/api-reference.md#3-console-json-protocol).
## Running the backend
```bash
# From the repo root — build and start the Spring Boot server on port 8080.
# valem-web is the runnable deployable; valem-api is the headless library it wraps.
mvn install -pl valem-core,valem-service -q
mvn spring-boot:run -pl valem-web
```
The API is now available at `http://localhost:8080`, with the management UI served at `/`. Storage
is in-memory by default; other backends are à-la-carte adapter jars
(`mvn -Pweb-postgres -pl valem-web package`, then `--valem.storage.type=postgres`) — see
[configuration.md](docs/deployment/configuration.md#persistence-model-spec--state). For durable
setups, persistence layout, and the hardening checklist see
[operations.md](docs/deployment/operations.md).
To enable LLM-powered spec generation, configure a provider before starting (the key is read from
`valem.llm.api-key`, settable as `VALEM_LLM_API_KEY`; there is no provider-specific env fallback):
```bash
# Anthropic (default provider)
export VALEM_LLM_API_KEY=sk-ant-...
mvn spring-boot:run -pl valem-web
# OpenAI
VALEM_LLM_PROVIDER=openai VALEM_LLM_MODEL=gpt-4o \
VALEM_LLM_API_KEY=$OPENAI_API_KEY mvn spring-boot:run -pl valem-web
# Ollama (local, no API key needed; start `ollama serve` first)
VALEM_LLM_PROVIDER=ollama VALEM_LLM_MODEL=llama3 mvn spring-boot:run -pl valem-web
```
Without any provider configured the server starts normally; the `/models/generate*` endpoints
return 503. All LLM knobs (providers, tool budgets, retries, temperatures):
[configuration.md](docs/deployment/configuration.md#llm-integration).
## Running the developer UI
In a separate terminal:
```bash
cd valem-ui
npm install # first time only
npm run dev
```
Open `http://localhost:5173` in your browser.
The UI proxies all `/models` and `/blobs` requests (including WebSocket connections) to the
backend, which must be running.
## Generating a model spec with an LLM
The UI's **✦ Generate** button drives a human-in-the-loop workflow: enter a model ID and a
plain-text domain description → **Preview Prompt** (editable) → send to the LLM → review/edit the
generated spec → **Register Model**. The same workflow is available over REST
(`POST /models/generate/preview` → `/models/generate` → `/models`).
See [generating-specs-with-llm.md](docs/model-guide/generating-specs-with-llm.md) for the workflow and
provider setup, and [llm-prompts.md](docs/reference/llm-prompts.md) for the exact prompts and the
validate-and-repair loop.
## Example: create and mutate a model over REST
```bash
# Create a model
curl -s -X POST http://localhost:8080/models \
-H 'Content-Type: application/json' \
-d '{
"id": "order",
"version": "1.0.0",
"schema": {},
"derivations": [
{ "path": "$.order.total", "expr": "order.subtotal + order.tax" }
],
"constraints": [
{ "id": "max-order", "expr": "order.total <= 5000",
"message": "Order exceeds the cap", "policy": "rollback" }
]
}'
# Mutate base fields — total is derived automatically
curl -s -X POST http://localhost:8080/models/order/mutations \
-H 'Content-Type: application/json' \
-d '{ "$.order.subtotal": 200, "$.order.tax": 20 }'
# Read merged state
curl -s http://localhost:8080/models/order/state | python -m json.tool
```
Every endpoint (audit, snapshots, views, blobs, spec evolution, composition, …):
[api-reference.md](docs/reference/api-reference.md).
## Running tests
```bash
# All modules
mvn test
# Core only (faster — no Spring context)
mvn test -pl valem-core
```
## Running end-to-end tests
The `valem-e2e` module contains Playwright browser tests that drive the full stack (backend + UI).
**Prerequisites:** the backend must be running on port 8080 (see
[Running the backend](#running-the-backend)). The UI dev server is started automatically by
Playwright.
```bash
cd valem-e2e
npm install # first time only
npx playwright install # download browser binaries (first time only)
npm test # headless Chromium
npm run test:headed # watch the browser
npm run test:ui # Playwright interactive UI mode
npm run report # open the last HTML report
```
## License
Apache-2.0 — see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues