Web-Algebra

Conjunto de ferramentas MCP genéricas para Linked Data/SPARQL e específicas do LinkedDataHub

GitHub
46

Documentação

Web-Algebra

Um sistema componível de operações RDF que traduz instruções em linguagem natural para operações JSON em uma linguagem de domínio específica para carregar, consultar e escrever dados vinculados RDF.

Visão Geral

Este sistema implementa operações genéricas para dados vinculados RDF e gerenciamento de SPARQL, além de algumas operações específicas do LinkedDataHub. As operações podem ser consumidas de duas maneiras:

  1. Formato JSON executável: As operações são compostas em estruturas JSON e executadas pelo mecanismo de execução fornecido
  2. Protocolo de Contexto de Modelo (MCP): As operações são expostas como ferramentas para agentes de IA usarem interativamente

Em vez de agentes executarem fluxos de trabalho semânticos passo a passo por meio de chamadas individuais de ferramentas MCP, o Web-Algebra permite que agentes compilem fluxos de trabalho inteiros em "bytecode" JSON otimizado que executa atomicamente - permitindo composições complexas de múltiplas operações.

Demonstração

Agentic Content Management with Web-Algebra MCP

Veja o WebAlgebra em ação - traduzindo linguagem natural em operações RDF.

Arquitetura

O sistema é construído em torno da classe base abstrata Operation que fornece:

  • Sistema de Registro: Descoberta automática de operações a partir de src/web_algebra/operations/
  • DSL JSON: As operações usam a chave @op com args para parâmetros, suportando chamadas de operações aninhadas
  • Sistema de Tipos RDFLib: Usa os tipos URIRef, Literal, Graph e Result internamente para o tratamento adequado de RDF
  • Mecanismo de Execução: Tanto execução autônoma quanto integração com servidor MCP
  • Sistema de Contexto: Operações ForEach definem contexto de linha para operações internas acessarem via Value
  • Resolução de URI: Construção semântica adequada de URI com a operação ResolveURI

Componentes Principais

Operações

As operações cobrem dados vinculados de leitura-escrita, consultas SPARQL, manipulação de URI e criação de recursos específicos do LinkedDataHub. Lista não exaustiva:

  • Dados Vinculados
    • GET
    • PATCH
    • POST
    • PUT
  • SPARQL
    • CONSTRUCT
    • DESCRIBE
    • SELECT
    • Substitute
    • Values
    • SPARQLString
  • Esquema
    • ExtractClasses
    • ExtractDatatypeProperties
    • ExtractObjectProperties
    • ExtractOntology
  • Operações de URI e String
    • ResolveURI
    • EncodeForURI
    • Concat
    • Replace
    • Str
    • STRUUID
    • URI
  • Fluxo de Controle e Variáveis
    • Value
    • Variable
    • ForEach
    • Iterate
    • Filter
    • Bindings
    • Current
    • Position
    • Last
    • Merge
  • Específicas do 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

Pré-requisitos

  1. Instalar uv
  2. uv venv
uv sync

Standalone

Natural language instruction

uv run python src/web_algebra/main.py

Em seguida, insira a instrução, por exemplo:

Selecionar 10 cidades aleatórias do Reino Unido do DBpedia

Veja mais exemplos

Atualmente requer acesso à API OpenAI. O valor da variável de ambiente OPENAI_API_KEY deve ser definido.

Executar JSON

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

Veja exemplos JSON.

Com LinkedDataHub

  1. Execute o LinkedDataHub v5
  2. Execute src/web_algebra/main.py, que espera o caminho para o certificado do proprietário do seu LDH e sua senha como argumentos. Por exemplo:
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 **********

Aqui e ao longo deste guia, os argumentos de certificado/senha do cliente são necessários apenas para autenticação com o LinkedDataHub. Você não precisa deles se não estiver usando o LinkedDataHub com o Web Algebra.

Como servidor MCP

Transporte stdio

uv run python -m web_algebra

Transporte HTTP transmissível

uv run uvicorn web_algebra.server:app --reload

ou com credenciais de certificado do LinkedDataHub (altere o caminho e a senha para os seus):

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

Configuração do MCP Inspector

Você pode usar o inspector assim:

npx @modelcontextprotocol/inspector

e depois abrir na URL impressa em sua saída de console, por exemplo:

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

O MCP_PROXY_AUTH_TOKEN é obrigatório. Se o link não aparecer, você precisa copiar o token de sessão do console e colá-lo na configuração de Token de Sessão de Proxy do inspector.

Configurações do Web Algebra:

Tipo de Transporte
HTTP Transmissível
URL
http://127.0.0.1:8000/mcp

Configuração de ferramenta do Claude Desktop

Adicione a entrada do Web Algebra (que usa transporte stdio) à configuração mcpServer do seu arquivo 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": "********"
            }
        }
    }
}

Deixe o comando como está. Esses argumentos uv run --with são importantes, caso contrário, pacotes de terceiros não podem ser encontrados.

No meu Mac, o caminho para uv precisa ser absoluto, caso contrário não funciona no Claude Desktop 🤷‍♂️.

Os valores de ambiente CERT_PEM_PATH e CERT_PASSWORD são opcionais.