@konductro/cursor-plugin 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# @konductro/cursor-plugin
+
+Cursor IDE plugin for the Konductro delivery platform. Enables technical analysis, story decomposition, ticket management, prototype delivery, and ticket-to-PR workflows directly from Cursor.
+
+## Prerequisites
+
+- **Node.js** 18+
+- **Cursor IDE** (any plan — MCP works on free tier)
+- **Konductro CLI token** (generated in Konductro → Settings → CLI Access)
+
+## Install
+
+```bash
+npm install -g @konductro/cursor-plugin
+```
+
+## Setup
+
+```bash
+konductro-cursor-setup --url https://platform.konductro.com --token YOUR_CLI_TOKEN
+```
+
+This will:
+1. Configure the Konductro MCP server in `~/.cursor/mcp.json`
+2. Install Cursor Rules to `~/.cursor/rules/`
+
+After setup, reload Cursor (Cmd+Shift+P → "Developer: Reload Window").
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--url` | Konductro platform URL | Required |
+| `--token` | Your personal CLI token | Required |
+| `--project` | Install to `.cursor/` in current directory instead of global | `false` |
+| `--env-refs` | Use `${env:...}` references instead of inline values (for git-committed configs) | `false` |
+
+## Rules (Workflows)
+
+Rules are guided workflows that Cursor invokes based on context:
+
+| Rule | Description |
+|------|-------------|
+| `start-ticket` | Pick up a Konductro ticket, create branch, and start work |
+| `decompose` | Decompose a story into technical implementation tasks |
+| `technical-analysis` | Perform a technical analysis for a project phase |
+| `profile-repository` | Scan repository and submit its tech profile |
+| `prototype` | Build a UX prototype and publish to S3 |
+| `find-prototype` | Find and download approved prototypes |
+| `bug-enrich` | Enrich a bug report with codebase context |
+
+## MCP Tools
+
+Tools are called automatically by Cursor's agent based on your requests:
+
+| Tool | What it does |
+|------|-------------|
+| `list_my_tickets` | List all tickets assigned to you |
+| `get_ticket_context` | Load full context for a ticket |
+| `start_work` | Create branch and start a ticket |
+| `create_pr` | Create a pull request for a ticket |
+| `list_tech_analysis_tasks` | List tech analysis assignments |
+| `get_task_context` | Load tech analysis context |
+| `submit_tech_analysis` | Submit analysis document |
+| `list_decomposition_tasks` | List story decomposition assignments |
+| `get_decomposition_context` | Load story context |
+| `submit_decomposition_task` | Submit a decomposed task |
+| `complete_decomposition` | Mark decomposition complete |
+| `list_prototype_tasks` | List prototype assignments |
+| `get_prototype_context` | Load prototype context |
+| `start_prototype_work` | Mark prototype in progress |
+| `request_upload_credentials` | Get S3 upload credentials |
+| `submit_prototype` | Submit completed prototype |
+| `profile_repository` | Submit repository profile |
+| `find_project_prototypes` | Find UX prototypes for a project |
+
+## Updating Your Token
+
+Run the setup command again with the new token:
+
+```bash
+konductro-cursor-setup --url https://platform.konductro.com --token NEW_TOKEN
+```
+
+## Troubleshooting
+
+- **MCP server not connecting:** Reload Cursor after config changes (Cmd+Shift+P → "Developer: Reload Window")
+- **Tools not showing:** Check Cursor Settings → MCP tab for connection status and errors
+- **Rules not activating:** Ensure rules are in `~/.cursor/rules/` or `.cursor/rules/` and mention Konductro in your prompt

package/bin/postinstall.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+console.log('');
+console.log('╔═══════════════════════════════════════════════════════╗');
+console.log('║  Konductro Cursor Plugin installed                    ║');
+console.log('║                                                       ║');
+console.log('║  Run setup to configure:                              ║');
+console.log('║  konductro-cursor-setup --url <URL> --token <TOKEN>   ║');
+console.log('║                                                       ║');
+console.log('║  Get your CLI token from:                             ║');
+console.log('║  Konductro → Settings → CLI Access                    ║');
+console.log('╚═══════════════════════════════════════════════════════╝');
+console.log('');

package/bin/setup.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function parseArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--url' && args[i + 1]) {
+      parsed.url = args[++i].replace(/\/$/, '');
+    } else if (arg === '--token' && args[i + 1]) {
+      parsed.token = args[++i];
+    } else if (arg === '--project') {
+      parsed.project = true;
+    } else if (arg === '--env-refs') {
+      parsed.envRefs = true;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    }
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`
+Konductro Cursor Plugin Setup
+
+Usage:
+  konductro-cursor-setup --url <konductro-url> --token <cli-token>
+
+Options:
+  --url        Konductro platform URL
+  --token      Personal CLI token from Konductro Settings -> CLI Access
+  --project    Install to .cursor/ in current directory instead of global ~/.cursor/
+  --env-refs   Use \${env:...} references instead of inline values (for git-committed configs)
+  --help       Show this help message
+
+Example:
+  konductro-cursor-setup --url https://platform.konductro.com --token <your-cli-token>
+`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!args.url || !args.token) {
+    console.error('Error: Both --url and --token are required.\n');
+    printHelp();
+    process.exit(1);
+  }
+
+  // Find the MCP server path (absolute, so Cursor can resolve it from any cwd)
+  const serverPath = resolve(join(__dirname, '..', 'servers', 'konductro-api.js'));
+  if (!existsSync(serverPath)) {
+    console.error('Error: MCP server not found at', serverPath);
+    process.exit(1);
+  }
+
+  // Determine config base directory
+  const baseDir = args.project ? join(process.cwd(), '.cursor') : join(homedir(), '.cursor');
+
+  // --- MCP config ---
+  const mcpConfigPath = join(baseDir, 'mcp.json');
+  mkdirSync(baseDir, { recursive: true });
+
+  let config = {};
+  if (existsSync(mcpConfigPath)) {
+    try {
+      config = JSON.parse(readFileSync(mcpConfigPath, 'utf8'));
+    } catch {
+      console.warn('Warning: Could not parse existing mcp.json, will add Konductro config.');
+      config = {};
+    }
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+
+  // Add/update Konductro server
+  const pluginDir = resolve(join(__dirname, '..'));
+  config.mcpServers.konductro = {
+    command: 'node',
+    args: [serverPath],
+    cwd: pluginDir,
+    env: args.envRefs
+      ? { KONDUCTRO_URL: '${env:KONDUCTRO_URL}', KONDUCTRO_CLI_TOKEN: '${env:KONDUCTRO_CLI_TOKEN}' }
+      : { KONDUCTRO_URL: args.url, KONDUCTRO_CLI_TOKEN: args.token },
+  };
+
+  writeFileSync(mcpConfigPath, JSON.stringify(config, null, 2) + '\n');
+
+  // --- Rules ---
+  const rulesDir = join(baseDir, 'rules');
+  mkdirSync(rulesDir, { recursive: true });
+
+  const sourceRulesDir = join(__dirname, '..', 'skills');
+  if (existsSync(sourceRulesDir)) {
+    const ruleFiles = readdirSync(sourceRulesDir).filter((f) => f.endsWith('.mdc'));
+    for (const file of ruleFiles) {
+      const srcPath = join(sourceRulesDir, file);
+      const destPath = join(rulesDir, file);
+      copyFileSync(srcPath, destPath);
+    }
+  }
+
+  // --- Output ---
+  console.log('');
+  console.log('✓ Konductro plugin configured for Cursor');
+  console.log('');
+  console.log('  MCP server: ' + serverPath);
+  console.log('  MCP config: ' + mcpConfigPath);
+  console.log('  Rules:      ' + rulesDir);
+  console.log('  Konductro:  ' + args.url);
+  console.log('');
+  if (args.envRefs) {
+    console.log('  ⚠ Using env var references. Set these in your shell profile:');
+    console.log('    export KONDUCTRO_URL=' + args.url);
+    console.log('    export KONDUCTRO_CLI_TOKEN=<your-token>');
+    console.log('');
+  }
+  console.log('Rules (workflows):');
+  console.log('  start-ticket         — pick up a ticket and start work');
+  console.log('  decompose            — decompose a story into tasks');
+  console.log('  technical-analysis   — perform codebase analysis');
+  console.log('  profile-repository   — scan and submit repo profile');
+  console.log('  prototype            — build a UX prototype');
+  console.log('  find-prototype       — find and download prototypes');
+  console.log('  bug-enrich           — enrich a bug report');
+  console.log('');
+  console.log('Reload Cursor to activate (Cmd+Shift+P → "Developer: Reload Window").');
+  console.log('');
+  console.log('To update your token later, run this command again.');
+  console.log('');
+}
+
+main();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@konductro/cursor-plugin",
+  "version": "1.0.0",
+  "description": "Cursor IDE plugin for the Konductro platform: technical analysis, delivery tasks, repository profiling, and prototype workflows.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "homepage": "https://platform.konductro.com",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@ssh.dev.azure.com:v3/idealsolution/Conductor/konductro-cursor-plugin"
+  },
+  "keywords": [
+    "cursor",
+    "konductro",
+    "mcp",
+    "technical-analysis",
+    "delivery",
+    "tickets",
+    "prototype"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "konductro-cursor-setup": "bin/setup.js"
+  },
+  "files": [
+    "bin/",
+    "servers/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node bin/postinstall.js",
+    "setup": "node bin/setup.js",
+    "check": "node --check servers/konductro-api.js && node --check bin/setup.js && node --check bin/postinstall.js",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}