SpecViber SaaS Client — Setup guide

How to connect a project on your machine to a hosted SpecViber workspace. The downloaded ZIP is reference code — settings live in .vscode/mcp.json in your own project, not in the unpacked folder.

On this page Prerequisites 1. Download & unpack 2. Create workspace + token 3. Run setup prompt Start using it Architecture Troubleshooting Upgrading

Prerequisites

Requirement	Check	Install
Node.js 18+	`node --version`	nodejs.org
PHP 8.1+ with `pdo_pgsql`	`php --version`	XAMPP, Laravel Herd, or standalone
Web server (serves local PHP)	`http://localhost/`	Included with XAMPP (Apache)
VS Code with GitHub Copilot	—	marketplace

Why a web server? The MCP server calls local PHP endpoints (api/docs/content/) over HTTP to read and write your .md files, checkboxes, and comments on disk. Without a running web server, content operations can't work.

1. Download and unpack

Get the latest specviber-saas-client-<version>.zip from the Downloads page and extract it into a folder your web server can serve — for example C:\xampp\htdocs\specviber_saas_client\ for XAMPP. Remember the path — you'll need it in step 3.

Then install the MCP server's dependencies:

cd specviber_saas_client/mcp-server
npm install
cd ..

2. Create your workspace in the web UI

Open the SpecViber web UI and create a workspace there (if you haven't already). During workspace creation:

Give the workspace a name.
If the workspace will contain multiple repos, decide which one is your main repo / customization host. Put that repo first in the workspace repo list. That repo should carry .vscode/mcp.json, .github/local-instructions.md, deployed skills, the rendered agent shells, and the built AGENTS.md.
Point it at the local path where you unpacked the SaaS client in step 1.
Finish the setup. Copy the API token and write down the numeric workspace ID — both are shown once and you'll need them in step 3.

Multi-repo note: the current deploy flow targets one repo, not all repos in the workspace. Keep repo-specific always-on instructions short, and move shared workflows into skills or shared docs to avoid oversized Copilot instructions when several projects later live in the same VS Code workspace.

3. Copy and run the setup prompt in your project

Open the main repo / customization host in VS Code — not the SaaS client folder. The unpacked client is a background service; you don't open it for daily work.

The setup prompt is generated for you. Open the workspace you created in step 2 in the SpecViber web UI and use the prompt shown there — it already has your workspace ID and API token filled in, so there is less to replace by hand.

Why it is not repeated here: the prompt has one source, and every place that shows it renders that source. A copy on this page would be a second version to keep in step, and the two previous copies had already drifted apart from each other.

The same prompt also ships with the client package, in its README.md, for when you are working offline or want to read it before running it.

Start using it

Once setup is complete:

Copilot Agent: switch to the spevi agent in VS Code Copilot Chat for task-driven work.
Web UI: app.specviber.com/specviber.html — sign in and select your workspace.
Kanban: app.specviber.com/kanban/kanban.html — manage tasks visually.

Architecture

Your project repo          SaaS client folder (background service)
  .md files ◄──────────── PHP API (local) ──────── Cloud DB
                              ▲
  VS Code ──── MCP ───────────┘

Content (.md files, checkboxes, comments) → local disk in your project
Metadata (tasks, status, relations) → managed cloud database
MCP → proxies everything through the local PHP API in the SaaS client folder

What's in the unpacked ZIP:

Directory	Contents
`mcp-server/`	Node.js MCP server
`api/`	PHP content endpoints (local file operations)
`classes/`	PHP application classes
`.github/agents/`	Agent definitions (including the `spevi` agent)
`.github/skills/`	Agent skill definitions

Troubleshooting

Problem	Solution
PHP errors about `pdo_pgsql`	Enable the `pdo_pgsql` extension in your `php.ini`
MCP tools not showing in Copilot	Restart VS Code after saving `.vscode/mcp.json`
`specviber_dashboard` returns auth error	Check that you pasted the API token from step 2 correctly into `.vscode/mcp.json`
Workspace not visible / wrong path	Edit the workspace in the web UI and update the local path; then re-run `specviber_scan`

Upgrading

The unpacked SaaS client is reference code — it doesn't keep state. Your settings live in .vscode/mcp.json in the project you manage with SpecViber, not in the SaaS client folder. To upgrade, just download the new ZIP and unpack it to the same path (overwrite is fine), then re-run npm install in mcp-server/ if package.json changed. No data lives in this folder that needs preserving.