jena-mcp 0.3.0__tar.gz

jena_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knuckles-Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jena_mcp-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include requirements.txt
+recursive-include jena_mcp *.py
+recursive-include jena_mcp *.json
+recursive-include jena_mcp/agent_data *

jena_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: jena-mcp
+Version: 0.3.0
+Summary: Apache Jena (Fuseki) API + MCP Server + A2A Server for Agentic AI!
+Author-email: Audel Rouhi <knucklessg1@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-utilities>=0.41.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: mcp
+Requires-Dist: agent-utilities[mcp]>=0.41.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: agent-utilities[agent,logfire]>=0.41.0; extra == "agent"
+Provides-Extra: all
+Requires-Dist: agent-utilities[agent,logfire,mcp]>=0.41.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# jena-mcp
+
+A Model Context Protocol (MCP) server for Jena integration.
+
+## Table of Contents
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Architecture](#architecture)
+- [Deployment](#deployment)
+- [Environment Variables](#environment-variables)
+- [MCP Tools](#mcp-tools)
+
+## Overview
+jena-mcp exposes a standardized interface to interact with Jena using the Model Context Protocol.
+
+## Installation
+```bash
+pip install -e .
+```
+
+## Usage
+Run the MCP server directly:
+```bash
+python -m jena_mcp
+```
+
+## Architecture
+See `/docs` for architectural diagrams and further documentation.
+
+## Deployment
+### Bare-metal
+```bash
+python -m jena_mcp.agent_server
+```
+
+### Docker
+```bash
+docker compose -f docker/agent.compose.yml up -d
+```
+
+## Environment Variables
+| Variable | Description |
+|----------|-------------|
+| `JENA_FUSEKI_URL` | Fuseki server URL |
+| `JENA_USER` | Admin user |
+| `JENA_PASSWORD` | Admin password |
+
+## MCP Tools
+| Tool | Description |
+|------|-------------|
+| `get_jena_info` | Retrieve basic information from Jena |
+| `query_jena` | Run a query against the Jena instance |

jena_mcp-0.3.0/README.md

@@ -0,0 +1,53 @@
+# jena-mcp
+
+A Model Context Protocol (MCP) server for Jena integration.
+
+## Table of Contents
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Architecture](#architecture)
+- [Deployment](#deployment)
+- [Environment Variables](#environment-variables)
+- [MCP Tools](#mcp-tools)
+
+## Overview
+jena-mcp exposes a standardized interface to interact with Jena using the Model Context Protocol.
+
+## Installation
+```bash
+pip install -e .
+```
+
+## Usage
+Run the MCP server directly:
+```bash
+python -m jena_mcp
+```
+
+## Architecture
+See `/docs` for architectural diagrams and further documentation.
+
+## Deployment
+### Bare-metal
+```bash
+python -m jena_mcp.agent_server
+```
+
+### Docker
+```bash
+docker compose -f docker/agent.compose.yml up -d
+```
+
+## Environment Variables
+| Variable | Description |
+|----------|-------------|
+| `JENA_FUSEKI_URL` | Fuseki server URL |
+| `JENA_USER` | Admin user |
+| `JENA_PASSWORD` | Admin password |
+
+## MCP Tools
+| Tool | Description |
+|------|-------------|
+| `get_jena_info` | Retrieve basic information from Jena |
+| `query_jena` | Run a query against the Jena instance |

jena_mcp-0.3.0/jena_mcp/__init__.py

@@ -0,0 +1,64 @@
+"""jena-mcp: Apache Jena (Fuseki) API + MCP Server + A2A Server."""
+
+import importlib
+import inspect
+from typing import Any
+
+__version__ = "0.2.0"
+__all__: list[str] = []
+
+CORE_MODULES = ["jena_mcp.api_client"]
+OPTIONAL_MODULES = {
+    "jena_mcp.agent_server": "agent",
+    "jena_mcp.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+_loaded_optional_modules = {}
+
+
+def _import_module_safely(module_name: str):
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        return _import_module_safely(mcp_key) is not None if mcp_key else False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        return _import_module_safely(agent_key) is not None if agent_key else False
+
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

jena_mcp-0.3.0/jena_mcp/__main__.py

@@ -0,0 +1,4 @@
+from jena_mcp.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

jena_mcp-0.3.0/jena_mcp/agent_server.py

@@ -0,0 +1,73 @@
+"""Graph-based Pydantic AI agent server entry point for jena-mcp."""
+
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.2.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    """Start the graph-based Pydantic AI agent server for Apache Jena."""
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Apache Jena Agent")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get("description", "AI agent for Apache Jena (Fuseki) operations."),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )

jena_mcp-0.3.0/jena_mcp/api/api_client_base.py

@@ -0,0 +1,93 @@
+"""Shared HTTP base client for the Apache Jena (Fuseki) API wrapper."""
+
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+import urllib3
+
+
+class ApiClientBase:
+    """Thin requests.Session wrapper with token / basic-auth support.
+
+    Apache Jena Fuseki speaks several content types (SPARQL query/update,
+    SPARQL results JSON/XML, RDF serializations). Callers pass an explicit
+    ``content_type``/``accept`` so this base never forces JSON on a SPARQL
+    payload.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        verify: bool = True,
+    ):
+        self.base_url = base_url.rstrip("/") + "/"
+        self.token = token
+        self.username = username
+        self.password = password
+        self.last_etag: str | None = None
+        self._session = requests.Session()
+        self._session.verify = verify
+
+        if not verify:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+        if token:
+            self._session.headers.update({"Authorization": f"Bearer {token}"})
+        elif username and password:
+            self._session.auth = (username, password)
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        data: Any | None = None,
+        content_type: str | None = None,
+        accept: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Perform an HTTP request and return parsed JSON, or raw text.
+
+        Returns a dict when the response is JSON, otherwise
+        ``{"status": "success", "text": <body>}``. Raises on HTTP >= 400.
+        """
+        if endpoint.startswith("http"):
+            url = endpoint
+        else:
+            url = urljoin(self.base_url, endpoint.lstrip("/"))
+
+        req_headers: dict[str, str] = {}
+        if content_type:
+            req_headers["Content-Type"] = content_type
+        if accept:
+            req_headers["Accept"] = accept
+        if headers:
+            req_headers.update(headers)
+
+        response = self._session.request(
+            method=method,
+            url=url,
+            headers=req_headers or None,
+            params=params,
+            data=data,
+        )
+
+        self.last_etag = response.headers.get("ETag")
+
+        if response.status_code >= 400:
+            raise Exception(f"API error: {response.status_code} - {response.text}")
+
+        if response.status_code == 204 or not response.text.strip():
+            return {"status": "success"}
+
+        ctype = response.headers.get("Content-Type", "")
+        if "json" in ctype:
+            try:
+                return response.json()
+            except Exception:
+                pass
+        return {"status": "success", "text": response.text}

jena_mcp-0.3.0/jena_mcp/api/api_client_jena.py

@@ -0,0 +1,171 @@
+"""Apache Jena Fuseki API wrapper.
+
+Covers the three HTTP surfaces Fuseki exposes:
+
+* **SPARQL Protocol** — query (SELECT/ASK/CONSTRUCT/DESCRIBE) and update
+  (INSERT/DELETE) per dataset.
+* **Graph Store Protocol (GSP)** — read/replace/merge/drop RDF graphs.
+* **Admin API** (``/$/``) — ping, server info, statistics, dataset
+  lifecycle (create/list/delete/state), async tasks, backup, compact, metrics.
+"""
+
+from typing import Any
+
+from jena_mcp.api.api_client_base import ApiClientBase
+
+
+class JenaApi(ApiClientBase):
+    """Full client for an Apache Jena Fuseki server."""
+
+    # ------------------------------------------------------------------ #
+    # SPARQL Protocol
+    # ------------------------------------------------------------------ #
+    def query(
+        self,
+        dataset: str,
+        sparql: str,
+        accept: str = "application/sparql-results+json",
+    ) -> Any:
+        """Run a SPARQL read query (SELECT/ASK/CONSTRUCT/DESCRIBE)."""
+        return self.request(
+            "POST",
+            f"{dataset.strip('/')}/sparql",
+            data=sparql,
+            content_type="application/sparql-query",
+            accept=accept,
+        )
+
+    def update(self, dataset: str, sparql: str) -> Any:
+        """Run a SPARQL update (INSERT/DELETE/LOAD/CLEAR)."""
+        return self.request(
+            "POST",
+            f"{dataset.strip('/')}/update",
+            data=sparql,
+            content_type="application/sparql-update",
+        )
+
+    # ------------------------------------------------------------------ #
+    # Graph Store Protocol (GSP)
+    # ------------------------------------------------------------------ #
+    def _gsp_params(self, graph: str | None) -> dict[str, str]:
+        return {"graph": graph} if graph and graph != "default" else {"default": ""}
+
+    def get_graph(
+        self, dataset: str, graph: str | None = None, accept: str = "text/turtle"
+    ) -> Any:
+        """Fetch an RDF graph (named or default) as text."""
+        return self.request(
+            "GET",
+            f"{dataset.strip('/')}/data",
+            params=self._gsp_params(graph),
+            accept=accept,
+        )
+
+    def put_graph(
+        self,
+        dataset: str,
+        rdf_data: str,
+        graph: str | None = None,
+        content_type: str = "text/turtle",
+    ) -> Any:
+        """Replace a graph with the supplied RDF."""
+        return self.request(
+            "PUT",
+            f"{dataset.strip('/')}/data",
+            params=self._gsp_params(graph),
+            data=rdf_data,
+            content_type=content_type,
+        )
+
+    def post_graph(
+        self,
+        dataset: str,
+        rdf_data: str,
+        graph: str | None = None,
+        content_type: str = "text/turtle",
+    ) -> Any:
+        """Merge the supplied RDF into a graph."""
+        return self.request(
+            "POST",
+            f"{dataset.strip('/')}/data",
+            params=self._gsp_params(graph),
+            data=rdf_data,
+            content_type=content_type,
+        )
+
+    def delete_graph(self, dataset: str, graph: str | None = None) -> Any:
+        """Drop a graph (named or default)."""
+        return self.request(
+            "DELETE",
+            f"{dataset.strip('/')}/data",
+            params=self._gsp_params(graph),
+        )
+
+    # ------------------------------------------------------------------ #
+    # Admin API (/$/)
+    # ------------------------------------------------------------------ #
+    def ping(self) -> Any:
+        """Server liveness check."""
+        return self.request("GET", "$/ping", accept="text/plain")
+
+    def server_info(self) -> Any:
+        """Server build info and the list of mounted datasets/services."""
+        return self.request("GET", "$/server", accept="application/json")
+
+    def stats(self, dataset: str | None = None) -> Any:
+        """Server-wide or per-dataset request statistics."""
+        endpoint = "$/stats" + (f"/{dataset.strip('/')}" if dataset else "")
+        return self.request("GET", endpoint, accept="application/json")
+
+    def metrics(self) -> Any:
+        """Prometheus metrics exposition."""
+        return self.request("GET", "$/metrics", accept="text/plain")
+
+    def list_datasets(self) -> Any:
+        """List datasets and their state."""
+        return self.request("GET", "$/datasets", accept="application/json")
+
+    def dataset_info(self, name: str) -> Any:
+        """Detail for a single dataset."""
+        return self.request(
+            "GET", f"$/datasets/{name.strip('/')}", accept="application/json"
+        )
+
+    def create_dataset(self, name: str, db_type: str = "tdb2") -> Any:
+        """Create a dataset. ``db_type`` is one of ``tdb2``, ``tdb``, ``mem``."""
+        return self.request(
+            "POST",
+            "$/datasets",
+            params={"dbName": name, "dbType": db_type},
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def delete_dataset(self, name: str) -> Any:
+        """Remove a dataset (and its configuration)."""
+        return self.request("DELETE", f"$/datasets/{name.strip('/')}")
+
+    def set_dataset_state(self, name: str, state: str) -> Any:
+        """Set a dataset ``active`` (online) or ``offline``."""
+        return self.request(
+            "POST",
+            f"$/datasets/{name.strip('/')}",
+            params={"state": state},
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def list_tasks(self) -> Any:
+        """List async admin tasks (backup/compact)."""
+        return self.request("GET", "$/tasks", accept="application/json")
+
+    def task_info(self, task_id: str) -> Any:
+        """Detail for a single async task."""
+        return self.request("GET", f"$/tasks/{task_id}", accept="application/json")
+
+    def backup(self, dataset: str) -> Any:
+        """Trigger an async backup of a dataset; returns a task handle."""
+        return self.request("POST", f"$/backup/{dataset.strip('/')}")
+
+    def compact(self, dataset: str, delete_old: bool = False) -> Any:
+        """Trigger an async TDB2 compaction; returns a task handle."""
+        params = {"deleteOld": "true"} if delete_old else None
+        return self.request("POST", f"$/compact/{dataset.strip('/')}", params=params)

jena_mcp-0.3.0/jena_mcp/api_client.py

@@ -0,0 +1,11 @@
+"""Public client facade for jena_mcp."""
+
+from jena_mcp.api.api_client_jena import JenaApi
+
+__version__ = "0.2.0"
+
+
+class Api(JenaApi):
+    """Authenticated Apache Jena Fuseki client."""
+
+    pass

jena_mcp-0.3.0/jena_mcp/auth.py

@@ -0,0 +1,35 @@
+"""Identity credentials loader for the Apache Jena Fuseki client."""
+
+import os
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+
+from jena_mcp.api_client import Api
+
+logger = get_logger(__name__)
+
+
+def get_client() -> Api:
+    """Build an authenticated Apache Jena Fuseki client from the environment.
+
+    Honors ``JENA_FUSEKI_URL`` (preferred) or ``JENA_URL``; bearer token via
+    ``JENA_TOKEN``; optional basic auth via ``JENA_USERNAME``/``JENA_PASSWORD``;
+    TLS verification via ``JENA_SSL_VERIFY``.
+    """
+    base_url = (
+        os.getenv("JENA_FUSEKI_URL")
+        or os.getenv("JENA_URL")
+        or "http://localhost:3030"
+    )
+    token = os.getenv("JENA_TOKEN", "")
+    username = os.getenv("JENA_USERNAME", "")
+    password = os.getenv("JENA_PASSWORD", "")
+    verify = to_boolean(os.getenv("JENA_SSL_VERIFY", "True"))
+
+    return Api(
+        base_url=base_url,
+        token=token or None,
+        username=username or None,
+        password=password or None,
+        verify=verify,
+    )