Add install.sh script for automated setup across package managers

[WolfgangFahl]

Problem

The current AGENTS.md and README.md provide manual setup instructions. Users need to:

1. Install Node.js v22 via their package manager
2. Install Meteor via curl
3. Install MongoDB
4. Run meteor npm ci
5. Install MCP server connectivity (API key generation, opencode config)

This is error-prone, especially since:

• Meteor has no MacPorts port on macOS — users must use the curl installer and manually configure PATH
• Different OS/package manager combinations (Homebrew, MacPorts, apt, dnf, etc.) require different commands
• New contributors shouldn't need to read through docs to get started
• MCP onboarding requires browser console steps (find projectId, call generateApiKey, copy-paste key)

Proposed Solution

• install.sh — automated, idempotent setup script that detects OS and package manager, installs Node.js v22, Meteor, and npm deps
• mcp-install.sh — one-command MCP setup: detects running ViziQuer, auto-generates API key via localhost endpoint, configures opencode (jq merge)
• POST /api/v1/mcp-install endpoint — localhost-only, auto-creates project if needed, generates API key, returns it

Files

File	Purpose
install.sh	Automated prereq install + meteor npm ci
mcp-install.sh	One-command MCP setup (auto key + opencode config)
app/imports/platform/server/api_router.js	Added POST /api/v1/mcp-install (localhost-only, auto project + key)

Acceptance Criteria

• install.sh works on macOS with MacPorts
• install.sh works on macOS with Homebrew
• install.sh works on Debian/Ubuntu (apt)
• mcp-install.sh auto-generates API key with zero manual steps
• mcp-install.sh configures opencode if jq + ~/.config/opencode/opencode.json exist
• POST /api/v1/mcp-install is localhost-only, auto-creates project if needed
• No browser console, no copy-paste, no manual config

Related

• ViziQuer/2026-05-12 — Session log: MacPorts hiccup and import path bug
• Karlis Cerans/2026-05-13 — Meeting agenda: example project discussion

[WolfgangFahl]

The MCP tools list_diagrams and get_diagram require a projectId (MongoDB _id like ddEpGP8uJT5XaYmEc) — not the human-readable project name (e.g. "WikidataSmallSample"). This makes the tools effectively unusable because:

1. Users create projects by name — they never see or interact with the _id
2. The only way to discover the _id is by inspecting the browser URL or dev console
3. Even the browser URL is useless unless you're on that project's page

The fix: accept a projectName parameter and resolve it to the _id internally by querying Projects.findOne({ name }). The projectId parameter can remain as a faster alternative when known.

Relevant code in api_router.js:344-365 — list_diagrams and get_diagram both do { projectId } direct DB lookups with no name-based fallback.

[WolfgangFahl]

The MCP tools list_diagrams and get_diagram require a projectId (MongoDB _id like ddEpGP8uJT5XaYmEc) — not the human-readable project name (e.g. "WikidataSmallSample"). This makes the tools effectively unusable because:

1. Users create projects by name — they never see or interact with the _id
2. The only way to discover the _id is by inspecting the browser URL or dev console
3. Even the browser URL is useless unless you're on that project's page

The fix: accept a projectName parameter and resolve it to the _id internally by querying Projects.findOne({ name }). The projectId parameter can remain as a faster alternative when known.

Relevant code in api_router.js:344-365 — list_diagrams and get_diagram both do { projectId } direct DB lookups with no name-based fallback.

[WolfgangFahl]

A note on the DSS (Data Shape Server) dependency and how install.sh fits with viziquer-tools:

The current install.sh scope covers only the ViziQuer Meteor app and prerequisites (Node.js, Meteor, npm ci). However, for the full ViziQuer experience, the Data Shape Server (DSS) + PostgreSQL are required — without DSS, schema-aware query building and endpoint configuration won't work. The README already documents this:

"For the use with the data shape server (DSS), the DSS server needs to be installed/accessible, as well"

There are two paths here, and I think install.sh should clearly document both:

---

Option A: Use a hybrid local+Docker setup

install.sh sets up ViziQuer in Meteor dev mode. For DSS + PostgreSQL, spin up only those containers from viziquer-tools:

# Comment out 'viziquer' and 'mongodb' services in docker-compose.yml
# (Meteor dev mode provides its own MongoDB), then:
docker compose up -d dss postgres

This gives you local ViziQuer development with hot-reload while DSS runs containerized. Requires adding a .env or commenting out the viziquer/mongodb services.

Con: The docker-compose.yml services are tightly coupled — viziquer depends on dss and mongodb. Running a subset requires manual YAML editing. It might be worth splitting viziquer-tools into a docker-compose.yml (Infra-only: dss + postgres + pgadmin) and a separate docker-compose.full.yml that adds viziquer + mongodb on top.

---

Option B: Recommend viziquer-tools for full-stack usage, install.sh for dev-only

The README could frame two distinct use cases:

Use case	Tool	What you get
Contribute to ViziQuer	install.sh + mcp-install.sh	Local Meteor dev env, MCP for AI-assisted coding
Run ViziQuer with DSS (production/exploration)	viziquer-tools (docker compose up -d)	ViziQuer + DSS + PostgreSQL + pgAdmin in one command

Then install.sh can detect if DSS is reachable (e.g. check SCHEMA_SERVER_URL from .env or http://localhost:9005/api) and print a helpful warning if it's missing, pointing to viziquer-tools.

---

Suggested small addition to install.sh

At the end of the script, add a post-install check:

# Check if DSS is available
if curl -s --max-time 2 http://localhost:9005/api > /dev/null 2>&1; then
  echo "✅ DSS detected at http://localhost:9005/api"
else
  echo "⚠️  DSS not detected. For schema-aware queries, run:"
  echo "    git clone https://github.com/LUMII-Syslab/viziquer-tools"
  echo "    cd viziquer-tools && cp sample.env .env && docker compose up -d"
fi

This makes the DSS requirement visible without adding complexity to the install flow.

[WolfgangFahl]

A note on the DSS (Data Shape Server) dependency and how install.sh fits with viziquer-tools:

The current install.sh scope covers only the ViziQuer Meteor app and prerequisites (Node.js, Meteor, npm ci). However, for the full ViziQuer experience, the Data Shape Server (DSS) + PostgreSQL are required — without DSS, schema-aware query building and endpoint configuration won't work. The README already documents this:

"For the use with the data shape server (DSS), the DSS server needs to be installed/accessible, as well"

There are two paths here, and I think install.sh should clearly document both:

---

Option A: Use a hybrid local+Docker setup

install.sh sets up ViziQuer in Meteor dev mode. For DSS + PostgreSQL, spin up only those containers from viziquer-tools:

# Comment out 'viziquer' and 'mongodb' services in docker-compose.yml
# (Meteor dev mode provides its own MongoDB), then:
docker compose up -d dss postgres

This gives you local ViziQuer development with hot-reload while DSS runs containerized. Requires adding a .env or commenting out the viziquer/mongodb services.

Con: The docker-compose.yml services are tightly coupled — viziquer depends on dss and mongodb. Running a subset requires manual YAML editing. It might be worth splitting viziquer-tools into a docker-compose.yml (Infra-only: dss + postgres + pgadmin) and a separate docker-compose.full.yml that adds viziquer + mongodb on top.

---

Option B: Recommend viziquer-tools for full-stack usage, install.sh for dev-only

The README could frame two distinct use cases:

Use case	Tool	What you get
Contribute to ViziQuer	install.sh + mcp-install.sh	Local Meteor dev env, MCP for AI-assisted coding
Run ViziQuer with DSS (production/exploration)	viziquer-tools (docker compose up -d)	ViziQuer + DSS + PostgreSQL + pgAdmin in one command

Then install.sh can detect if DSS is reachable (e.g. check SCHEMA_SERVER_URL from .env or http://localhost:9005/api) and print a helpful warning if it's missing, pointing to viziquer-tools.

---

Suggested small addition to install.sh

At the end of the script, add a post-install check:

# Check if DSS is available
if curl -s --max-time 2 http://localhost:9005/api > /dev/null 2>&1; then
  echo "✅ DSS detected at http://localhost:9005/api"
else
  echo "⚠️  DSS not detected. For schema-aware queries, run:"
  echo "    git clone https://github.com/LUMII-Syslab/viziquer-tools"
  echo "    cd viziquer-tools && cp sample.env .env && docker compose up -d"
fi

This makes the DSS requirement visible without adding complexity to the install flow.

[WolfgangFahl]

Mikus suggets:

put the line
VQ_SCHEMA_SERVER_URL=https://dss.semtech.lv/api
in the .env file

[WolfgangFahl]

Check with Windows users: Run this script inside WSL2 (Ubuntu/Debian). The script auto-detects apt and works as-is. Ensure Docker Desktop has WSL2 backend enabled if using DSS containers.

[karlisc]

This is expected to work for MacOS and Linux.
Windows support may be limited (this script might be extended for WSL, not for Windows directly).