Visual Spec MCP Server

Connect Cursor (or any MCP client) to your Visual Spec project requirements and kanban tasks.

Published on npm as @geeks.ltd/geeks-visualspec-mcp (same scope as @geeks.ltd/geeks-amp-mcp).

Quick start (npm — recommended for all users)

Add to your application repo's .cursor/mcp.json:

{
  "mcpServers": {
    "visualspec": {
      "command": "npx",
      "args": ["-y", "@geeks.ltd/geeks-visualspec-mcp"],
      "env": {
        "VISUALSPEC_API_URL": "https://your-visualspec-api.example.com",
        "VISUALSPEC_API_KEY": "vs_your_agent_key",
        "VISUALSPEC_PROJECT_ID": "your-project-guid"
      }
    }
  }
}

Restart Cursor MCP after changing config (Settings → MCP → visualspec → Restart).

Generate an agent API key from Designer → Code workspace in Visual Spec, or via:

POST /projects/{projectId}/code/agent-keys
{ "name": "Cursor MCP", "readOnly": false }

Env file instead of inline secrets

Set VISUALSPEC_ENV_FILE to a path (relative to the workspace root) instead of putting the API key in mcp.json:

{
  "mcpServers": {
    "visualspec": {
      "command": "npx",
      "args": ["-y", "@geeks.ltd/geeks-visualspec-mcp"],
      "env": {
        "VISUALSPEC_ENV_FILE": "mcp-server/.env.local"
      }
    }
  }
}

Copy .env.example to .env.local and fill in values. The launcher also checks .env.local and mcp-server/.env.local in the workspace root automatically.

| Variable | Description | |----------|-------------| | VISUALSPEC_API_URL | Visual Spec API base URL (default http://localhost:5000) | | VISUALSPEC_API_KEY | Agent API key (vs_...) | | VISUALSPEC_PROJECT_ID | Project GUID | | VISUALSPEC_ENV_FILE | Optional path to a .env.local file |

Local development (this repo)

Build

cd mcp-server
npm install
npm run build

Cursor (local package path)

Use the local package via npx (no publish required):

{
  "mcpServers": {
    "visualspec": {
      "command": "npx",
      "args": ["./mcp-server"],
      "env": {
        "VISUALSPEC_ENV_FILE": "mcp-server/.env.local"
      }
    }
  }
}

Or use the dev entry point directly:

{
  "mcpServers": {
    "visualspec": {
      "command": "node",
      "args": ["C:/path/to/visualspec.app/mcp-server/run.mjs"]
    }
  }
}

Automated local setup

Creates an agent API key, writes mcp-server/.env.local, and updates .cursor/mcp.json:

.\mcp-server\scripts\setup-cursor-mcp.ps1

Optional flags: -ProjectName "Demo", -ProjectId "{guid}", -ReadOnly (omit for write access to task tools).

Requires local SQL Server + running API database.

Publishing to npm

See How to publish.txt. Quick options:

cd mcp-server
.\publish.ps1

Or manually:

cd mcp-server
npm run build
npm version patch    # or: npm version minor
npm publish --access public

Use npm login first, or a temporary .npmrc with //registry.npmjs.org/:_authToken=... (see How to publish.txt). publishConfig.access is already public in package.json, so --access public is optional but fine.

Write access for task tools

Task create/update/delete tools require an API key that is not read-only:

POST /projects/{projectId}/code/agent-keys
{ "name": "Cursor MCP", "readOnly": false }

Read-only keys can still use list_tasks, get_task, and all implementation brief tools.

Tools

Implementation context (read-only)

• get_project_overview / get_implementation_brief — scoped implementation context
• list_implementation_gaps — drift between mock and code
• get_page_spec — page-level brief

Project tasks (kanban board)

• list_tasks — all tasks with #taskNumber, status, priority, order
• get_task — full task detail (assignees, scope links, AMP ref)
• create_task — create a task (requires write key)
• update_task — partial update by taskId (requires write key)
• reposition_task — move column / reorder within column (requires write key)
• delete_task — delete a task (requires write key)

Status values: notStarted, inProgress, development, reviewPending, testing, block, completed

Priority values: low, medium, high, critical

Resources

• visualspec://project/{id}/brief — implementation brief JSON
• visualspec://project/{id}/tasks — all project tasks JSON

Repo manifest

Add .visualspec.yaml to your application repository:

projectId: "your-project-guid"
apiUrl: "http://localhost:5000"
layer: frontend
pathPrefix: "UI/"