{"id":30801603,"url":"https://github.com/atomgraph/web-algebra","last_synced_at":"2025-10-16T16:19:02.066Z","repository":{"id":309808533,"uuid":"907989537","full_name":"AtomGraph/Web-Algebra","owner":"AtomGraph","description":"Suite of generic Linked Data/SPARQL as well as LinkedDataHub-specific MCP tools","archived":false,"fork":false,"pushed_at":"2025-08-30T10:22:01.000Z","size":292,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-30T12:18:40.935Z","etag":null,"topics":["agent-based","linked-data","mcp","mcp-server","semantic-web","sparql"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AtomGraph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-24T19:48:18.000Z","updated_at":"2025-08-30T10:22:04.000Z","dependencies_parsed_at":"2025-08-13T23:47:33.245Z","dependency_job_id":"bfa1fcfa-b654-4e83-a83c-8ffc92f4d5d2","html_url":"https://github.com/AtomGraph/Web-Algebra","commit_stats":null,"previous_names":["atomgraph/web-algebra"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AtomGraph/Web-Algebra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtomGraph%2FWeb-Algebra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtomGraph%2FWeb-Algebra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtomGraph%2FWeb-Algebra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtomGraph%2FWeb-Algebra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AtomGraph","download_url":"https://codeload.github.com/AtomGraph/Web-Algebra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtomGraph%2FWeb-Algebra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273820971,"owners_count":25174125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-based","linked-data","mcp","mcp-server","semantic-web","sparql"],"created_at":"2025-09-05T21:08:07.742Z","updated_at":"2025-10-16T16:19:01.968Z","avatar_url":"https://github.com/AtomGraph.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web-Algebra\n\nA composable RDF operations system that translates natural language instructions into JSON-formatted domain-specific language operations for loading, querying, and writing RDF Linked Data.\n\n## Overview\n\nThis system implements generic operations for RDF Linked Data and SPARQL management, as well as some [LinkedDataHub](https://atomgraph.github.io/LinkedDataHub/)-specific operations. Operations can be consumed in two ways:\n\n1. **Executable JSON format**: Operations are composed into JSON structures and executed by the provided execution engine\n2. **Model Context Protocol (MCP)**: Operations are exposed as tools for AI agents to use interactively\n\nInstead 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.\n\n## Demo\n\n[![ Agentic Content Management with Web-Algebra MCP](https://img.youtube.com/vi/eRMrSqKc9_E/0.jpg)](https://www.youtube.com/watch?v=eRMrSqKc9_E)\n\n*See WebAlgebra in action - translating natural language into RDF operations.*\n\n## Architecture\n\nThe system is built around the `Operation` abstract base class that provides:\n- **Registry System**: Auto-discovery of operations from `src/web_algebra/operations/`\n- **JSON DSL**: Operations use `@op` key with `args` for parameters, supporting nested operation calls\n- **RDFLib Type System**: Uses `URIRef`, `Literal`, `Graph`, and `Result` types internally for proper RDF handling\n- **Execution Engine**: Both standalone execution and MCP server integration\n- **Context System**: ForEach operations set row context for inner operations to access via `Value`\n- **URI Resolution**: Proper semantic URI construction with `ResolveURI` operation\n\n### Key Components\n\n- **[System Prompt](prompts/system.md)**: Complete operation definitions and JSON format specification\n- **[Formal Semantics](formal-semantics.md)**: Complete type system and operation catalog\n- **[Operation Interface](src/web_algebra/operation.py)**: Base class and JSON interpreter\n- **[Operation Implementations](src/web_algebra/operations/)**: Directory containing all available operations\n- **[JSON Examples](examples/)**: Sample operation compositions\n\n### Operations\n\nThe operations cover read-write Linked Data, SPARQL queries, URI manipulation, and LinkedDataHub-specific resource creation. Non-exhaustive list:\n\n- Linked Data\n  - `GET`\n  - `PATCH`\n  - `POST`\n  - `PUT`\n- SPARQL\n  - `CONSTRUCT`\n  - `DESCRIBE`\n  - `SELECT`\n  - `Substitute`\n- URI \u0026 String Operations\n  - `ResolveURI`\n  - `EncodeForURI`\n  - `Concat`\n  - `Replace`\n  - `Str`\n  - `URI`\n- Control Flow \u0026 Variables\n  - `Value`\n  - `Variable`\n  - `ForEach`\n- LinkedDataHub-specific\n  - `ldh-CreateContainer`\n  - `ldh-CreateItem`\n  - `ldh-List`\n  - `ldh-AddGenericService`\n  - `ldh-AddResultSetChart`\n  - `ldh-AddSelect`\n  - `ldh-AddView`\n  - `ldh-AddObjectBlock`\n  - `ldh-AddXHTMLBlock`\n  - `ldh-RemoveBlock`\n\n## Usage\n\n### Pre-requisites\n\n1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)\n2. ```bash\n   uv venv\n   uv sync\n   ```\n\n### Standalone\n\n#### Natural language instruction\n\n```bash\nuv run python src/web_algebra/main.py\n```\n\nThen enter instruction, for example:\n\u003e Select random 10 UK cities from DBpedia\n\nSee [more examples](examples.md)\n\n_Currently requires OpenAI API access. `OPENAI_API_KEY` env value has to be set._\n\n#### Execute JSON\n\n```bash\nuv run python src/web_algebra/main.py --from-json ./examples/united-kingdom-cities.json\n```\n\nSee [JSON examples](examples).\n\n#### With [LinkedDataHub](https://atomgraph.github.io/LinkedDataHub/)\n\n1. Run LinkedDataHub v5\n2. Execute `src/web_algebra/main.py`, it expects the path to your LDH's owner certificate and its password as arguments. For example:\n\n```bash\nuv run python src/web_algebra/main.py --from-json ./examples/united-kingdom-cities.json \\\n  --cert_pem_path ../LinkedDataHub/ssl/owner/cert.pem \\\n  --cert_password **********\n```\n\n_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._\n\n### As MCP server\n\n#### stdio transport\n\n```bash\nuv run python -m web_algebra\n```\n\n#### Streamable HTTP transport\n\n```bash\nuv run uvicorn web_algebra.server:app --reload\n```\nor with LinkedDataHub certificate credentials (change the path and password to yours):\n\n```bash\nCERT_PEM_PATH=\"/Users/Martynas.Jusevicius/WebRoot/LinkedDataHub/ssl/owner/cert.pem\" CERT_PASSWORD=\"********\" uv run uvicorn web_algebra.server:app --reload\n```\n\n#### [MCP Inspector](https://github.com/modelcontextprotocol/inspector) config\n\nYou can the inspector like this:\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\nand then open on the URL printed in its console output, for example:\n```\nhttp://localhost:6274/?MCP_PROXY_AUTH_TOKEN=b31e4b3d852b5a2445f45032c484e54e319bf16359585858cf88fe9a90816744\n```\n\nThe `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.\n\nWeb Algebra's settings:\n\n\u003cdl\u003e\n    \u003cdt\u003eTransport Type\u003c/dt\u003e\n    \u003cdd\u003eStreamable HTTP\u003c/dd\u003e\n    \u003cdt\u003eURL\u003c/dt\u003e\n    \u003cdd\u003ehttp://127.0.0.1:8000/mcp\u003c/dd\u003e\n\u003c/dl\u003e\n\n#### [Claude Desktop](https://claude.ai/download) tool config\n\nAdd Web Algebra entry (that uses stdio transport) to the `mcpServer` configuration your `claude_desktop_config.json` file:\n```json\n{\n    \"mcpServers\": {\n        \"Web Algebra\": {\n            \"command\": \"uv\",\n            \"args\": [\n                \"--directory\",\n                \"/Users/Martynas.Jusevicius/WebRoot/Web-Algebra/src\",\n                \"run\",\n                \"--with\",\n                \"mcp[cli]\",\n                \"--with\",\n                \"rdflib\",\n                \"--with\",\n                \"openai\",\n                \"python\",\n                \"-m\",\n                \"web_algebra\"\n            ],\n            \"env\": {\n                \"CERT_PEM_PATH\": \"/Users/Martynas.Jusevicius/WebRoot/LinkedDataHub/ssl/owner/cert.pem\",\n                \"CERT_PASSWORD\": \"********\"\n            }\n        }\n    }\n}\n```\n_Leave the command as it is. Those `uv run --with` arguments are important, otherwise 3rd party packages cannot be found._\n\nOn my Mac, the path to `uv` has to be absolute, otherwise it doesn't work in Claude Desktop 🤷‍♂️.\n\n`CERT_PEM_PATH` and `CERT_PASSWORD` env values are optional.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomgraph%2Fweb-algebra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomgraph%2Fweb-algebra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomgraph%2Fweb-algebra/lists"}