Web-Algebra

Conjunto de herramientas MCP genéricas para Linked Data/SPARQL y específicas de LinkedDataHub

GitHub
46

Documentación

Web-Algebra

Un sistema componible de operaciones RDF que traduce instrucciones en lenguaje natural a operaciones JSON en un lenguaje específico de dominio para cargar, consultar y escribir datos enlazados RDF.

Descripción general

Este sistema implementa operaciones genéricas para datos enlazados RDF y gestión de SPARQL, así como algunas operaciones específicas de LinkedDataHub. Las operaciones se pueden consumir de dos maneras:

  1. Formato JSON ejecutable: Las operaciones se componen en estructuras JSON y se ejecutan mediante el motor de ejecución proporcionado
  2. Protocolo de Contexto de Modelo (MCP): Las operaciones se exponen como herramientas para que los agentes de IA las utilicen de forma interactiva

En lugar de que los agentes ejecuten flujos de trabajo semánticos paso a paso mediante llamadas individuales a herramientas MCP, Web-Algebra permite a los agentes compilar flujos de trabajo completos en "código de bytes" JSON optimizado que se ejecuta de forma atómica, lo que permite composiciones complejas de múltiples operaciones.

Demostración

Agentic Content Management with Web-Algebra MCP

Vea WebAlgebra en acción: traduciendo lenguaje natural a operaciones RDF.

Arquitectura

El sistema se construye alrededor de la clase base abstracta Operation que proporciona:

  • Sistema de registro: Descubrimiento automático de operaciones desde src/web_algebra/operations/
  • DSL JSON: Las operaciones utilizan la clave @op con args para parámetros, admitiendo llamadas anidadas a operaciones
  • Sistema de tipos RDFLib: Utiliza los tipos URIRef, Literal, Graph y Result internamente para un manejo adecuado de RDF
  • Motor de ejecución: Tanto ejecución independiente como integración con servidor MCP
  • Sistema de contexto: Las operaciones ForEach establecen el contexto de fila para que las operaciones internas accedan a él mediante Value
  • Resolución de URI: Construcción semántica adecuada de URI con la operación ResolveURI

Componentes clave

Operaciones

Las operaciones cubren datos enlazados de lectura-escritura, consultas SPARQL, manipulación de URI y creación de recursos específicos de LinkedDataHub. Lista no exhaustiva:

  • Datos enlazados
    • GET
    • PATCH
    • POST
    • PUT
  • SPARQL
    • CONSTRUCT
    • DESCRIBE
    • SELECT
    • Substitute
    • Values
    • SPARQLString
  • Esquema
    • ExtractClasses
    • ExtractDatatypeProperties
    • ExtractObjectProperties
    • ExtractOntology
  • Operaciones de URI y cadenas
    • ResolveURI
    • EncodeForURI
    • Concat
    • Replace
    • Str
    • STRUUID
    • URI
  • Flujo de control y variables
    • Value
    • Variable
    • ForEach
    • Iterate
    • Filter
    • Bindings
    • Current
    • Position
    • Last
    • Merge
  • Específicas de LinkedDataHub
    • 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

Uso

Requisitos previos

  1. Instalar uv
  2. uv venv
uv sync

Standalone

Natural language instruction

uv run python src/web_algebra/main.py

Luego ingrese una instrucción, por ejemplo:

Seleccionar 10 ciudades del Reino Unido al azar de DBpedia

Consulte más ejemplos

Actualmente requiere acceso a la API de OpenAI. El valor de entorno OPENAI_API_KEY debe estar configurado.

Ejecutar JSON

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

Consulte ejemplos JSON.

Con LinkedDataHub

  1. Ejecute LinkedDataHub v5
  2. Ejecute src/web_algebra/main.py, que espera la ruta al certificado de propietario de su LDH y su contraseña como argumentos. Por ejemplo:
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 **********

Aquí y en toda esta guía, los argumentos de certificado/contraseña del cliente solo son necesarios para la autenticación con LinkedDataHub. No los necesita si no está usando LinkedDataHub con Web Algebra.

Como servidor MCP

Transporte stdio

uv run python -m web_algebra

Transporte HTTP transmisible

uv run uvicorn web_algebra.server:app --reload

o con credenciales de certificado de LinkedDataHub (cambie la ruta y la contraseña por las suyas):

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

Configuración de MCP Inspector

Puede usar el inspector de esta manera:

npx @modelcontextprotocol/inspector

y luego abrir la URL impresa en su salida de consola, por ejemplo:

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

El MCP_PROXY_AUTH_TOKEN es obligatorio. Si el enlace no aparece, debe copiar el token de sesión de la consola y pegarlo en la configuración de Token de sesión de proxy del inspector.

Configuración de Web Algebra:

Tipo de transporte
HTTP transmisible
URL
http://127.0.0.1:8000/mcp

Configuración de herramienta de Claude Desktop

Agregue la entrada de Web Algebra (que usa transporte stdio) a la configuración mcpServer de su archivo claude_desktop_config.json:

{
    "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": "********"
            }
        }
    }
}

Deje el comando tal como está. Esos argumentos uv run --with son importantes; de lo contrario, los paquetes de terceros no se pueden encontrar.

En mi Mac, la ruta a uv debe ser absoluta; de lo contrario, no funciona en Claude Desktop 🤷‍♂️.

Los valores de entorno CERT_PEM_PATH y CERT_PASSWORD son opcionales.