Repository files navigation

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.

This system implements generic operations for RDF Linked Data and SPARQL management, as well as someLinkedDataHub-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.

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

The system is built around theOperation abstract base class that provides:

• Registry System: Auto-discovery of operations fromsrc/web_algebra/operations/
• JSON DSL: Operations use@op key withargs for parameters, supporting nested operation calls
• RDFLib Type System: UsesURIRef,Literal,Graph, andResult 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 viaValue
• URI Resolution: Proper semantic URI construction withResolveURI operation

• 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

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

1. Install uv

2. uv venvuv sync

uv run python src/web_algebra/main.py

Then enter instruction, for example:

Select random 10 UK cities from DBpedia

Seemore examples

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

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

SeeJSON examples.

1. Run LinkedDataHub v5
2. Executesrc/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.

uv run python -m web_algebra

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

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

TheMCP_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

Add Web Algebra entry (that uses stdio transport) to themcpServer configuration yourclaude_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. Thoseuv run --with arguments are important, otherwise 3rd party packages cannot be found.

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

CERT_PEM_PATH andCERT_PASSWORD env values are optional.