@comunica/mcp-sparql-hdt 1.0.0

package/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright © 2026-now Ruben Taelman
+Ghent University – imec, Belgium
+
+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.

package/README.md

@@ -0,0 +1,229 @@
+# Comunica MCP SPARQL HDT
+
+[![npm version](https://badge.fury.io/js/%40comunica%2Fmcp-sparql-hdt.svg)](https://www.npmjs.com/package/@comunica/mcp-sparql-hdt)
+
+Comunica MCP SPARQL HDT is an [MCP server](https://modelcontextprotocol.io/) for allowing AI agents to execute SPARQL queries over [HDT files](https://www.rdfhdt.org/).
+
+HDT (Header-Dictionary-Triples) is a binary RDF serialization format that enables efficient querying of large RDF datasets with low memory consumption.
+
+It's main distinguishing features are the following:
+
+* Improves the accuracy of your AI agent's answers by leveraging the power of SPARQL and Knowledge Graphs.
+* Execute [SPARQL 1.2](https://www.w3.org/TR/sparql12-query/) queries over HDT files.
+* Memory-efficient querying of large RDF datasets.
+* Fast query execution over compressed HDT files.
+* Supports local HDT files and remote HDT endpoints.
+
+**[Learn more about Comunica on our website](https://comunica.dev/).**
+
+_Internally, this is a [Comunica module](https://comunica.dev/) that is configured with modules to execute SPARQL queries over HDT files through MCP._
+
+## Supported by
+
+Comunica is a community-driven project, sustained by the [Comunica Association](https://comunica.dev/association/).
+If you are using Comunica, [becoming a sponsor or member](https://opencollective.com/comunica-association) is a way to make Comunica sustainable in the long-term.
+
+Our top sponsors are shown below!
+
+<a href="https://opencollective.com/comunica-association/sponsor/0/website" target="_blank"><img src="https://opencollective.com/comunica-association/sponsor/0/avatar.svg"></a>
+<a href="https://opencollective.com/comunica-association/sponsor/1/website" target="_blank"><img src="https://opencollective.com/comunica-association/sponsor/1/avatar.svg"></a>
+<a href="https://opencollective.com/comunica-association/sponsor/2/website" target="_blank"><img src="https://opencollective.com/comunica-association/sponsor/2/avatar.svg"></a>
+<a href="https://opencollective.com/comunica-association/sponsor/3/website" target="_blank"><img src="https://opencollective.com/comunica-association/sponsor/3/avatar.svg"></a>
+
+## Usage examples
+
+After connecting this MCP server to your AI agent (see some examples on how to do this below),
+your agent can SPARQL query any HDT file that is accessible to you.
+
+For example, use it to ask:
+
+> Use Comunica SPARQL HDT to query the DBpedia HDT file and find all movies directed by Christopher Nolan.
+
+### Prompt suggestions
+
+If you want your agent to always use SPARQL for higher accuracy in answers, you can tell it the following:
+
+> When looking up data, always prefer looking them up over Knowledge Graphs via SPARQL, as this is more precise.
+> For large RDF datasets, HDT files provide efficient querying capabilities.
+> Since SPARQL queries can take a while to execute, start producing an approximate answer yourself and show it to me if the SPARQL query takes more than 1 second, but then make the answer more concrete based on the SPARQL query once it finalized, as it will be more accurate.
+
+## Installation
+
+Comunica requires [Node.JS](http://nodejs.org/) 14.0 or higher and is tested on OSX and Linux.
+
+The easiest way to install the client is by installing it from NPM as follows:
+
+```bash
+$ [sudo] npm install -g @comunica/mcp-sparql-hdt
+```
+
+Alternatively, you can install from the latest GitHub sources.
+For this, please refer to the README of the [Comunica monorepo](https://github.com/comunica/comunica).
+If you do so, the following examples require replacing `comunica-mcp-sparql-hdt` with `node engines/mcp-sparql-hdt/bin/mcp.js`.
+
+## Connect this MCP server to your agent
+
+Below, a non-exhaustive list of examples is given to connect this MCP server to your agent.
+
+### Claude Desktop
+
+After installing, you can run the MCP server in two modes:
+
+#### Stdio Mode (Recommended for Claude Desktop)
+
+With stdio mode, the MCP server communicates directly via standard input/output, which is simpler and doesn't require a network port.
+
+Add the following entry to your `claude_desktop_config.json` file (can be found via Settings / Developer / Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "comunica-sparql-hdt": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@comunica/mcp-sparql-hdt",
+        "--mode",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+#### HTTP Mode
+
+Alternatively, you can run the MCP server in HTTP mode, which requires starting the server manually first:
+
+```bash
+$ comunica-mcp-sparql-hdt --mode http --port 3123
+```
+
+Then, add the following entry to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "comunica-sparql-hdt": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "http://localhost:3123/mcp",
+        "--allow-http"
+      ]
+    }
+  }
+}
+```
+
+Then, you can ask Claude something like the following:
+
+> Use Comunica SPARQL HDT to query the DBpedia HDT file at /path/to/dbpedia.hdt and find all movies directed by Christopher Nolan.
+
+#### Default Sources
+
+You can optionally configure default HDT sources when starting the MCP server. When default sources are provided, the `sources` parameter is hidden from the tools, and all queries automatically use the configured sources.
+
+This is useful when you want to restrict queries to specific HDT files.
+
+**Stdio Mode with Default Sources:**
+
+```json
+{
+  "mcpServers": {
+    "comunica-sparql-hdt": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@comunica/mcp-sparql-hdt",
+        "--mode",
+        "stdio",
+        "/path/to/dbpedia.hdt"
+      ]
+    }
+  }
+}
+```
+
+**HTTP Mode with Default Sources:**
+
+```bash
+$ comunica-mcp-sparql-hdt --mode http --port 3123 /path/to/dbpedia.hdt
+```
+
+### Claude Code
+
+#### Stdio Mode (Recommended for Claude Code)
+
+With stdio mode, the MCP server communicates directly via standard input/output, which is simpler and doesn't require a network port.
+
+```bash
+claude mcp add --transport stdio sparql-hdt -- npx -y @comunica/mcp-sparql-hdt --mode stdio
+```
+
+Learn more in the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp),
+such as for running this on Windows.
+
+#### HTTP Mode
+
+Alternatively, you can run the MCP server in HTTP mode, which requires starting the server manually first:
+
+```bash
+$ comunica-mcp-sparql-hdt --mode http --port 3123
+```
+
+```bash
+claude mcp add --transport http sparql-hdt http://localhost:3123/mcp
+```
+
+### ChatGPT
+
+At the time of writing, ChatGPT only supports HTTP-based MCP servers.
+So you'll need to run this tool under HTTP mode and expose it to the public Web,
+possibly combined with a reverse proxy and/or OAuth layer.
+
+```bash
+$ comunica-mcp-sparql-hdt --mode http --port 3123
+```
+
+## Available Tools
+
+This MCP server provides the following tools:
+
+### query_sparql
+
+Execute SPARQL queries over one or more HDT files or remote HDT endpoints, which also includes update queries.
+
+**Parameters:**
+- `query` (required): SPARQL query string
+- `sources` (required, unless default sources are configured): List of HDT file paths or HDT endpoint URLs
+- `queryFormatLanguage` (optional): Query language (e.g., `sparql`, `graphql`). Allows you to specify alternative query languages supported by Comunica
+- `queryFormatVersion` (optional): Query language version (e.g., `1.0`, `1.1`, `1.2`). Specifies the version of the query language to use
+- `baseIRI` (optional): Base IRI for resolving relative IRIs in the query
+- `httpProxy` (optional): HTTP proxy URL (e.g., `http://proxy.example.com:8080`)
+- `httpAuth` (optional): HTTP basic authentication in the format `username:password`
+- `httpTimeout` (optional): HTTP request timeout in milliseconds
+- `httpRetryCount` (optional): Number of HTTP request retries on failure
+
+**Note:** When the MCP server is started with default sources, the `sources` parameter is not available, and all queries automatically use the configured default sources.
+
+### query_sparql_rdf
+
+Execute SPARQL queries over a serialized RDF dataset provided as a string (useful for querying Turtle, N-Triples, or other RDF formats directly).
+
+**Parameters:**
+- `query` (required): SPARQL query string
+- `value` (required): Serialized RDF dataset as a string
+- `mediaType` (required): Media type of the serialized RDF dataset (e.g., `text/turtle`, `application/n-triples`, `application/ld+json`)
+- `fileBaseIRI` (optional): Base IRI for resolving relative IRIs in the RDF dataset
+- `baseIRI` (optional): Base IRI for resolving relative IRIs in the query
+- `queryFormatLanguage` (optional): Query language (e.g., `sparql`, `graphql`). Allows you to specify alternative query languages supported by Comunica
+- `queryFormatVersion` (optional): Query language version (e.g., `1.0`, `1.1`, `1.2`). Specifies the version of the query language to use
+
+## Learn more
+
+This README just shows the tip of the iceberg!
+Learn more about Comunica's functionalities in the following guides:
+
+* _[*Full documentation*](https://comunica.dev/docs/)_

package/bin/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const query_sparql_hdt_1 = require("@comunica/query-sparql-hdt");
+const utils_mcp_1 = require("@comunica/utils-mcp");
+// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires,import/extensions
+(0, utils_mcp_1.runCli)(new query_sparql_hdt_1.QueryEngine(), require('../package.json').version);
+//# sourceMappingURL=mcp.js.map

package/bin/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["mcp.ts"],"names":[],"mappings":";;;AACA,iEAAyD;AACzD,mDAA6C;AAE7C,sFAAsF;AACtF,IAAA,kBAAM,EAAC,IAAI,8BAAW,EAAE,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { QueryEngine } from '@comunica/query-sparql-hdt';\nimport { runCli } from '@comunica/utils-mcp';\n\n// eslint-disable-next-line ts/no-require-imports,ts/no-var-requires,import/extensions\nrunCli(new QueryEngine(), require('../package.json').version);\n"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@comunica/mcp-sparql-hdt",
+  "version": "1.0.0",
+  "description": "An MCP server for executing SPARQL queries over HDT files",
+  "license": "MIT",
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/comunica-association"
+  },
+  "homepage": "https://comunica.dev/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comunica/comunica-feature-mcp.git",
+    "directory": "engines/mcp-sparql-hdt"
+  },
+  "bugs": {
+    "url": "https://github.com/comunica/comunica-feature-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "agentic",
+    "comunica",
+    "sparql",
+    "hdt",
+    "engine",
+    "query",
+    "update",
+    "sparql engine",
+    "sparql query",
+    "sparql update",
+    "sparql 1.1",
+    "sparql 1.2"
+  ],
+  "sideEffects": false,
+  "main": "lib/index.js",
+  "typings": "lib/index",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "comunica-mcp-sparql-hdt": "bin/mcp.js"
+  },
+  "files": [
+    "bin/**/*.d.ts",
+    "bin/**/*.js",
+    "bin/**/*.js.map",
+    "lib/**/*.d.ts",
+    "lib/**/*.js",
+    "lib/**/*.js.map"
+  ],
+  "scripts": {
+    "build": "yarn run build:ts",
+    "build:ts": "node \"../../node_modules/typescript/bin/tsc\""
+  },
+  "dependencies": {
+    "@comunica/query-sparql-hdt": "^5.0.0",
+    "@comunica/utils-mcp": "^1.0.0"
+  },
+  "gitHead": "8a35a73d61cf1066bb1181761884d84d3b932932"
+}