Web Algebra

Web-Algebra

A composable RDF operations system that translates natural language instructions into JSON-formatted domain-specific language operations for loading, querying, and writing RDF Linked Data.

Overview

This system implements generic operations for RDF Linked Data and SPARQL management, as well as some LinkedDataHub-specific operations. Operations can be consumed in two ways:

1. Executable JSON format: Operations are composed into JSON structures and executed by the provided execution engine
2. Model Context Protocol (MCP): Operations are exposed as tools for AI agents to use interactively

Instead of agents executing semantic workflows step-by-step through individual MCP tool calls, Web-Algebra enables agents to compile entire workflows into optimized JSON "bytecode" that executes atomically - enabling complex multi-operation compositions.

Demo

*See WebAlgebra in action - translating natural language into RDF operations.*

Architecture

The system is built around the Operation abstract base class that provides:

• Registry System: Auto-discovery of operations from src/web_algebra/operations/
• JSON DSL: Operations use @op key with args for parameters, supporting nested operation calls
• RDFLib Type System: Uses URIRef, Literal, Graph, and Result types internally for proper RDF handling
• Execution Engine: Both standalone execution and MCP server integration
• Context System: ForEach operations set row context for inner operations to access via Value
• URI Resolution: Proper semantic URI construction with ResolveURI operation

Key Components

• [System Prompt](src/web_algebra/prompts/system.md): Complete operation definitions and JSON format specification
• [Formal Semantics](formal-semantics.md): Complete type system and operation catalog
• [Operation Interface](src/web_algebra/operation.py): Base class and JSON interpreter
• [Operation Implementations](src/web_algebra/operations/): Directory containing all available operations
• [Examples](examples/): Real-world plans over live Linked Data, each with its result and checks

Operations

The operations cover read-write Linked Data, SPARQL queries, URI manipulation, and LinkedDataHub-specific resource creation. Non-exhaustive list:

• Linked Data
• GET
• PATCH
• POST
• PUT
• SPARQL
• CONSTRUCT
• DESCRIBE
• SELECT
• Substitute
• Values
• SPARQLString
• Schema
• ExtractClasses
• ExtractDatatypeProperties
• ExtractObjectProperties
• ExtractOntology
• Reconciliation
• Reconcile
• URI & String Operations
• ResolveURI
• EncodeForURI
• Concat
• Replace
• Str
• StrUUID
• URI
• Date/Time
• Now
• Control Flow & Variables
• Value
• Variable
• ForEach
• Iterate
• Filter
• Bindings
• Current
• Position
• Last
• Merge
• LinkedDataHub-specific
• ldh-CreateContainer
• ldh-CreateItem
• ldh-List
• ldh-AddFile
• ldh-AddGenericService
• ldh-AddResultSetChart
• ldh-AddSelect
• ldh-AddConstruct
• ldh-AddView
• ldh-AddObjectBlock
• ldh-AddXHTMLBlock
• ldh-RemoveBlock
• ldh-GeneratePortal
• ldh-GenerateClassContainers
• ldh-GenerateOntologyViews

Usage

Pre-requisites

1. Install uv
2. `bash uv venv uv sync

Standalone

Natural language instruction

uv run python src/web_algebra/main.py

Then enter instruction, for example:

Select random 10 UK cities from DBpedia

See the instructions of the examples.

_Currently requires OpenAI API access. OPENAI_API_KEY env value has to be set._

Execute JSON

uv run web-algebra --from-json ./examples/city-profiles/plan.json

See the examples: each has the instruction it answers, its plan, the result of a run, and checks.

With LinkedDataHub

1. Run LinkedDataHub v6
2. Give web-algebra your LDH's owner certificate and its password in the CERT_PEM_PATH and CERT_PASSWORD environment variables (or the --cert_pem_path and --cert_password options, which override them). For example:

export CERT_PEM_PATH=../LinkedDataHub/ssl/owner/cert.pem

export CERT_PASSWORD="$(cat ../LinkedDataHub/secrets/owner_cert_password.txt)" uv run web-algebra --from-json ./examples/northwind-category-catalogue/plan.json

_Here and throughout this guide, the client certificate and its password are only required for authentication with LinkedDataHub. You don't need them if you're not using LinkedDataHub with Web Algebra._

As MCP server

Install

Requires uv. Add this to your MCP client configuration (e.g. claude_desktop_config.json):

{

"mcpServers": { "web-algebra": { "command": "uvx", "args": ["--from", "web-algebra", "web-algebra-mcp"], "env": { "CERT_PEM_PATH": "/path/to/LinkedDataHub/ssl/owner/cert.pem", "CERT_PASSWORD": "********" } } } }

or with Claude Code:

claude mcp add web-algebra -e CERT_PEM_PATH=/path/to/LinkedDataHub/ssl/owner/cert.pem -e CERT_PASSWORD=******** -- uvx --from web-algebra web-algebra-mcp

uvx web-algebra mcp runs the same server.

Environment variables:

stdio transport

uv run web-algebra-mcp

Streamable HTTP transport

uv run uvicorn web_algebra.server:app --reload

with CERT_PEM_PATH and CERT_PASSWORD set, as above, for LinkedDataHub.

MCP Inspector config

You can the inspector like this:

npx @modelcontextprotocol/inspector

and then open on the URL printed in its console output, for example:

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b31e4b3d852b5a2445f45032c484e54e319bf16359585858cf88fe9a90816744

The MCP_PROXY_AUTH_TOKEN is required. If the link does not appear, you need to copy the session token from the console and paste it into inspector's Proxy Session Token config.

Web Algebra's settings:

Transport Type Streamable HTTP URL http://127.0.0.1:8000/mcp

Claude Desktop tool config from a local checkout

To run the MCP server from a local checkout instead of the published package, add a Web Algebra entry (that uses stdio transport) to the mcpServer configuration your claude_desktop_config.json file:

{

"mcpServers": { "Web Algebra": { "command": "uv", "args": [ "--directory", "/path/to/Web-Algebra", "run", "web-algebra-mcp" ], "env": { "CERT_PEM_PATH": "/path/to/LinkedDataHub/ssl/owner/cert.pem", "CERT_PASSWORD": "********" } } } }

_Leave the command as it is. Those `uv run --with` arguments are important, otherwise 3rd party packages cannot be found._

On my Mac, the path to uv has to be absolute, otherwise it doesn't work in Claude Desktop 🤷♂️.

CERT_PEM_PATH and CERT_PASSWORD env values are optional.