REST API / MCP Server

[WolfgangFahl]

it would be greate to have computerized interactions with the tool availabe

• via API/RESTFul
• via MCP for LLMs agentic AI to work with things

[WolfgangFahl]

This could e.g. be analyzed using openrouter / opencode see https://github.com/WolfgangFahl/py-3rdparty-mediawiki/blob/master/AGENTS.md

see WolfgangFahl/py-3rdparty-mediawiki#125 for an example where it already worked

[WolfgangFahl]

Implementation Plan: REST API + MCP Server

After reviewing the codebase, here is a concrete plan. The existing infrastructure (Express 5 mounted at /api via WebApp.connectHandlers) gives us a clean foundation to build on — one REST endpoint already exists (POST /api/public-diagram in server/platform/main.js).

---

Phase 1 — REST API

Authentication

All REST endpoints will authenticate via a X-Auth-Token / X-User-Id header pair, which is the standard Meteor accounts token already issued at login. The server looks up the token in Meteor.users (services.resume.loginTokens), resolves the userId, and gates access using the existing is_project_member / is_public_diagram helpers — no new auth scheme needed.

A helper getUserFromRequest(req) in a new file app/imports/custom/vq/server/api/auth.js will encapsulate this lookup.

Endpoints (new file: app/imports/custom/vq/server/api/routes.js)

Method	Path	Description
GET	/api/projects	List projects the authenticated user is a member of
GET	/api/projects/:projectId/diagrams	List diagrams in a project
GET	/api/diagrams/:diagramId/sparql	Return the stored SPARQL text for a diagram
POST	/api/sparql	Execute a SPARQL query (wraps the executeSparql Meteor method logic directly, bypassing DDP)

The POST /api/sparql body:

{
  "projectId": "...",
  "versionId": "...",
  "diagramId": "...",
  "endpoint": "https://dbpedia.org/sparql",
  "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
  "namedGraph": "",
  "endpointUsername": "",
  "endpointPassword": "",
  "httpRequestProfileName": "P2"
}

All endpoints return application/json. Errors use standard HTTP status codes (401, 403, 404, 500).

Wiring

The routes module exports a function registerApiRoutes(app) that is called from the existing Meteor.startup block in server/platform/main.js, keeping the Express app setup in one place.

---

Phase 2 — MCP Server

An MCP (Model Context Protocol) server exposes ViziQuer's capabilities as tools that LLM agents can discover and call. It will be implemented as a separate Express router mounted at /api/mcp, using the MCP TypeScript SDK (plain JS via @modelcontextprotocol/sdk).

Tools exposed

Tool name	Description
list_projects	Returns the user's projects
list_diagrams	Returns diagrams for a given project
get_diagram_sparql	Returns the SPARQL query stored in a diagram
execute_sparql	Executes a SPARQL query against an endpoint and returns results

The MCP server reuses the same REST auth helper and the same underlying logic as Phase 1 — it is essentially a thin MCP protocol wrapper over the REST layer.

New file: app/imports/custom/vq/server/api/mcp.js

Registers an MCP StreamableHTTPServerTransport at POST /api/mcp. Agents send JSON-RPC requests; the server responds with tool results.

---

File Changes Summary

app/
├── server/platform/main.js              # add: import + call registerApiRoutes(app)
└── imports/custom/vq/server/api/
    ├── auth.js                          # NEW: getUserFromRequest helper
    ├── routes.js                        # NEW: REST route handlers
    └── mcp.js                           # NEW: MCP server setup

No schema migrations needed. No new npm dependencies for Phase 1. Phase 2 adds @modelcontextprotocol/sdk.

---

Out of scope for this issue

• OAuth2 / API key generation UI (Meteor login tokens cover the use case)
• WebSocket / SSE streaming of SPARQL results
• Write operations via REST (diagram creation/editing)

[WolfgangFahl]

MCP Server Demo — Diagram Retrieval

Here's a demonstration of the ViziQuer MCP server retrieving the "A Create a Query" diagram from the test project:

Project: ddEpGP8uJT5XaYmEc

Diagram: fAgTr55o3qGG6wnvE ("A Create a Query")

3 diagrams found in the project. This one has 3 elements (2 boxes, 1 link) and the following compartment values:

Element	Compartment	Value
4kRT68kHifnciasmu (Class, type: query)	Name	[human (Q5)]
	Aggregates	C<-count(.)
	OrderBy	order by C DESC
Kr99DG7w7pC2oCz3X (Class, type: condition)	Name	[medical profession (Q66811410)]
	Attributes	(select this) {+label}
7WfLnhZhwt6qTApnC (Link)	Name	[occupation (P106)]
	NestingType	PLAIN

Query interpretation: Count humans (Q5) by occupation (P106), filtered to medical professions (Q66811410), ordered by count descending.

This was done entirely through the MCP server running against a local ViziQuer instance — no browser or UI needed. 🎉

[WolfgangFahl]

MCP Server Demo — Diagram Retrieval

Here's a demonstration of the ViziQuer MCP server retrieving the "A Create a Query" diagram from the test project:

Project: ddEpGP8uJT5XaYmEc

Diagram: fAgTr55o3qGG6wnvE ("A Create a Query")

3 diagrams found in the project. This one has 3 elements (2 boxes, 1 link) and the following compartment values:

Element	Compartment	Value
4kRT68kHifnciasmu (Class, type: query)	Name	[human (Q5)]
	Aggregates	C<-count(.)
	OrderBy	order by C DESC
Kr99DG7w7pC2oCz3X (Class, type: condition)	Name	[medical profession (Q66811410)]
	Attributes	(select this) {+label}
7WfLnhZhwt6qTApnC (Link)	Name	[occupation (P106)]
	NestingType	PLAIN

Query interpretation: Count humans (Q5) by occupation (P106), filtered to medical professions (Q66811410), ordered by count descending.

This was done entirely through the MCP server running against a local ViziQuer instance — no browser or UI needed. 🎉

[karlisc]

API access - this ticket (list diagrams, get diagram content, run a query from a diagram)
API routes for specific functionality - other tickets

[karlisc]

Need to find a way to refer to a query in a diagram (create another ticket). This is the blocking point for full implementation of the ticket.

[karlisc]

The proposed code has hallucinations. The profiles do not belong to services. There is a need of a project list.