Sparnatural services platform / MCP-over-SPARQL

This server contains 2 things :

1. A set of API to be integrated with Sparnatural, in particular for the connection of Sparnatural with AI Agents
2. The "MCP-over-SPARQL" experiment to expose knowledge graphs through the MCP protocol

Both features rely on the same underlying config file, to configure the projects being exposed.

Running locally on dev

1. Create a config file in the config folder : config/config.yaml
2. Open package.json and double-check that the start command has a --config= option that matches the path to this file
3. Run npm run start
4. Go to http://localhost:3000/api/v1/ to test an API

Text2Query Test Runner

The project includes a CLI test runner at src/tests/text2query-test.ts. It executes all query.txt / expected.json test cases, compares API responses, and generates an Excel report.

Show CLI documentation

npm run test:t2q -- --help

This help is auto-generated by commander.

Run tests

1. Start the API first:

npm run start

2. Run the test runner (in another terminal):

npm run test:t2q -- --testsDir ./src/tests/text2query --endpoint http://localhost:3000/api/v1/dbpedia-en/text2query --runs 2 --outputDir ./src/tests/test-report --reportFile test-report.xlsx

CLI options

• --testsDir <path>: Root folder containing tests (recursive scan).
• --endpoint <url>: Full Text2Query API endpoint URL.
• --runs <number>: Number of runs per test case (default: 3).
• --outputDir <path>: Output folder for mirrored test artifacts and report.
• --reportFile <name>: Excel report filename (default: test-report.xlsx).

Output structure

The runner mirrors the test folder structure under outputDir. For each test case folder:

• Copies query.txt
• Copies expected.json
• Creates output/ with execution artifacts:
• runN-response.json on success "OK" or unsuccess "KO"
• runN-error.json on failure