web-algebra 1.1.0

Composable RDF operations in JSON

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: Complete operation definitions and JSON format specification
• Formal Semantics: Complete type system and operation catalog
• Operation Interface: Base class and JSON interpreter
• Operation Implementations: Directory containing all available operations
• JSON Examples: Sample operation compositions

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
• URI & String Operations
  • ResolveURI
  • EncodeForURI
  • Concat
  • Replace
  • Str
  • URI
• Control Flow & Variables
  • Value
  • Variable
  • ForEach
• LinkedDataHub-specific
  • ldh-CreateContainer
  • ldh-CreateItem
  • ldh-List
  • ldh-AddGenericService
  • ldh-AddResultSetChart
  • ldh-AddSelect
  • ldh-AddView
  • ldh-AddObjectBlock
  • ldh-AddXHTMLBlock
  • ldh-RemoveBlock

Usage

Pre-requisites

1. Install uv

2. 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 more examples

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

Execute JSON

uv run python src/web_algebra/main.py --from-json ./examples/united-kingdom-cities.json

See JSON examples.

With LinkedDataHub

1. Run LinkedDataHub v5
2. Execute src/web_algebra/main.py, it expects the path to your LDH's owner certificate and its password as arguments. For example:

uv run python src/web_algebra/main.py --from-json ./examples/united-kingdom-cities.json \
  --cert_pem_path ../LinkedDataHub/ssl/owner/cert.pem \
  --cert_password **********

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

As MCP server

stdio transport

uv run python -m web_algebra

Streamable HTTP transport

uv run uvicorn web_algebra.server:app --reload

or with LinkedDataHub certificate credentials (change the path and password to yours):

CERT_PEM_PATH="/Users/Martynas.Jusevicius/WebRoot/LinkedDataHub/ssl/owner/cert.pem" CERT_PASSWORD="********" uv run uvicorn web_algebra.server:app --reload

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

Add Web Algebra entry (that uses stdio transport) to the mcpServer configuration your claude_desktop_config.json file:

{
    "mcpServers": {
        "Web Algebra": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/Martynas.Jusevicius/WebRoot/Web-Algebra/src",
                "run",
                "--with",
                "mcp[cli]",
                "--with",
                "rdflib",
                "--with",
                "openai",
                "python",
                "-m",
                "web_algebra"
            ],
            "env": {
                "CERT_PEM_PATH": "/Users/Martynas.Jusevicius/WebRoot/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.