huly-mcp-sdk 0.2.1

package/scripts/demo.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * Live demo of huly-mcp-sdk tools against a real Huly workspace.
+ * Runs through: list projects → create issue → add comment → add label →
+ *               update issue → add relation → get issue → delete issue
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// Load .env
+const envPath = path.join(__dirname, '..', '.env')
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const m = line.match(/^([^#=\s]+)\s*=\s*(.*)$/)
+    if (m) process.env[m[1]] = m[2].trim()
+  }
+}
+
+const distDir = path.join(__dirname, '..', 'dist')
+const { getConnection, closeConnection } = require(path.join(distDir, 'connection'))
+const tracker = require('@hcengineering/tracker')
+const task = require('@hcengineering/task')
+const tags = require('@hcengineering/tags')
+const { generateId, SortingOrder } = require('@hcengineering/core')
+const { makeRank } = require('@hcengineering/rank')
+
+const GREEN  = '\x1b[32m'
+const CYAN   = '\x1b[36m'
+const YELLOW = '\x1b[33m'
+const BOLD   = '\x1b[1m'
+const RESET  = '\x1b[0m'
+
+function header (text) {
+  console.log(`\n${BOLD}${CYAN}━━━  ${text}  ━━━${RESET}`)
+}
+function ok (text) { console.log(`${GREEN}✅  ${text}${RESET}`) }
+function info (text) { console.log(`${YELLOW}    ${text}${RESET}`) }
+function print (text) { console.log(`    ${text}`) }
+
+async function main () {
+  console.log(`\n${BOLD}🚀  huly-mcp-sdk live demo${RESET}`)
+  console.log(`    Workspace: ${process.env.HULY_WORKSPACE}\n`)
+
+  const client = await getConnection()
+  ok('Connected to Huly')
+
+  // ── 1. List projects ──────────────────────────────────────────────────────
+  header('1 / 8  —  list_projects')
+  const projects = await client.findAll(tracker.default.class.Project, {})
+  ok(`Found ${projects.length} project(s)`)
+  for (const p of projects) {
+    print(`• ${BOLD}${p.identifier}${RESET}  ${p.name}`)
+  }
+
+  // Pick first project for the rest of the demo
+  const project = projects[0]
+  if (project == null) { console.error('No projects found — aborting.'); return }
+  info(`Using project: ${project.identifier}`)
+
+  // ── 2. List issues (top 5) ────────────────────────────────────────────────
+  header('2 / 8  —  list_issues')
+  const issues = await client.findAll(
+    tracker.default.class.Issue,
+    { space: project._id },
+    { limit: 5, sort: { modifiedOn: SortingOrder.Descending } }
+  )
+  const statuses = await client.findAll(tracker.default.class.IssueStatus, {})
+  const statusMap = new Map(statuses.map(s => [s._id, s.name]))
+  ok(`Showing 5 most-recent issues in ${project.identifier}`)
+  for (const i of issues) {
+    print(`• ${BOLD}${i.identifier}${RESET}  [${statusMap.get(i.status) ?? '?'}]  ${i.title}`)
+  }
+
+  // ── 3. Create issue ───────────────────────────────────────────────────────
+  header('3 / 8  —  create_issue')
+  const incResult = await client.updateDoc(
+    tracker.default.class.Project, project.space, project._id,
+    { $inc: { sequence: 1 } }, true
+  )
+  const issueNumber = incResult?.object?.sequence ?? project.sequence + 1
+  const identifier = `${project.identifier}-${issueNumber}`
+
+  const defaultStatus = project.defaultIssueStatus != null
+    ? (statuses.find(s => s._id === project.defaultIssueStatus) ?? statuses[0])
+    : statuses[0]
+  const kind = await client.findOne(task.default.class.TaskType,
+    project.type != null ? { parent: project.type } : {})
+  const lastIssue = await client.findOne(
+    tracker.default.class.Issue, { space: project._id },
+    { sort: { rank: SortingOrder.Descending } }
+  )
+  const rank = makeRank(lastIssue?.rank, undefined)
+
+  const issueId = generateId()
+  await client.addCollection(
+    tracker.default.class.Issue, project._id,
+    tracker.default.ids.NoParent, tracker.default.class.Issue, 'subIssues',
+    {
+      title: '🧪 huly-mcp-sdk demo issue',
+      description: null,
+      status: defaultStatus._id,
+      priority: 2, // High
+      number: issueNumber, identifier, rank,
+      kind: kind._id,
+      comments: 0, subIssues: 0,
+      dueDate: null, assignee: null, component: null, milestone: null,
+      parents: [], remainingTime: 0, estimation: 0,
+      reportedTime: 0, reports: 0, childInfo: [], relations: []
+    },
+    issueId
+  )
+  ok(`Created ${BOLD}${identifier}${RESET}: 🧪 huly-mcp-sdk demo issue`)
+
+  // ── 4. Add comment ────────────────────────────────────────────────────────
+  header('4 / 8  —  add_comment')
+  const chunter = require('@hcengineering/chunter')
+  await client.addCollection(
+    chunter.default.class.ChatMessage, project._id,
+    issueId, tracker.default.class.Issue, 'comments',
+    { message: 'This issue was created by the **huly-mcp-sdk** demo script 🎉', attachments: 0 }
+  )
+  ok(`Added comment to ${identifier}`)
+
+  // ── 5. Add label ──────────────────────────────────────────────────────────
+  header('5 / 8  —  add_label')
+  const core = require('@hcengineering/core')
+  let label = await client.findOne(tags.default.class.TagElement, {
+    targetClass: tracker.default.class.Issue, title: 'demo'
+  })
+  if (label == null) {
+    const cat = await client.findOne(tags.default.class.TagCategory, {
+      targetClass: tracker.default.class.Issue
+    })
+    const labelId = generateId()
+    await client.createDoc(
+      tags.default.class.TagElement, core.default.space.Workspace,
+      {
+        title: 'demo', targetClass: tracker.default.class.Issue,
+        description: '', color: 0x6366f1,
+        category: cat?._id ?? tags.default.category.NoCategory, refCount: 0
+      }, labelId
+    )
+    label = await client.findOne(tags.default.class.TagElement, { _id: labelId })
+    info('Auto-created label "demo" (color: #6366f1)')
+  }
+  const issue = await client.findOne(tracker.default.class.Issue, { identifier })
+  await client.addCollection(
+    tags.default.class.TagReference, issue.space, issue._id,
+    tracker.default.class.Issue, 'labels',
+    { tag: label._id, title: label.title, color: label.color }
+  )
+  ok(`Labeled ${identifier} with "demo"`)
+
+  // ── 6. Update issue ───────────────────────────────────────────────────────
+  header('6 / 8  —  update_issue')
+  const inProgress = statuses.find(s => s.name.toLowerCase().includes('progress')) ?? statuses[1] ?? statuses[0]
+  await client.updateDoc(
+    tracker.default.class.Issue, issue.space, issue._id,
+    { status: inProgress._id, priority: 1 /* Urgent */ }
+  )
+  ok(`Updated ${identifier} → status: "${inProgress.name}", priority: Urgent`)
+
+  // ── 7. Get issue (full details) ───────────────────────────────────────────
+  header('7 / 8  —  get_issue')
+  const fresh = await client.findOne(tracker.default.class.Issue, { identifier })
+  const freshStatus = statusMap.get(fresh.status) ?? 'Unknown'
+  const PRIORITY = ['No priority', 'Urgent', 'High', 'Medium', 'Low']
+  ok(`Full details for ${identifier}`)
+  print(`  Title:    ${fresh.title}`)
+  print(`  Status:   ${freshStatus}`)
+  print(`  Priority: ${PRIORITY[fresh.priority] ?? fresh.priority}`)
+  print(`  Comments: ${fresh.comments}`)
+
+  // ── 8. Delete issue (cleanup) ─────────────────────────────────────────────
+  header('8 / 8  —  delete_issue  (cleanup)')
+  await client.removeCollection(
+    tracker.default.class.Issue, fresh.space, fresh._id,
+    fresh.attachedTo, fresh.attachedToClass, fresh.collection
+  )
+  ok(`Deleted ${identifier} — workspace is clean`)
+
+  await closeConnection()
+
+  console.log(`\n${BOLD}${GREEN}🎉  Demo complete! All 8 tools exercised successfully.${RESET}\n`)
+}
+
+main().catch(err => {
+  console.error('\n❌  Demo failed:', err.message)
+  process.exit(1)
+})

package/scripts/import-csv.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * Bulk-import issues from a CSV file into a Huly tracker project.
+ *
+ * Usage:
+ *   node scripts/import-csv.js <csv-file> <project-identifier>
+ *
+ * Example:
+ *   node scripts/import-csv.js tasks.csv PROJ
+ *
+ * CSV format (first row = headers):
+ *   title,priority,status,dueDate
+ *   Fix login bug,High,In Progress,2025-04-01
+ *   Add dark mode,Medium,,
+ *
+ * Required columns:
+ *   title       — issue title (required)
+ *
+ * Optional columns:
+ *   priority    — Urgent | High | Medium | Low | No priority  (default: No priority)
+ *   status      — name of an existing status in the project    (default: project default)
+ *   dueDate     — YYYY-MM-DD                                   (default: none)
+ *
+ * Auth (set ONE option as env vars):
+ *   Option A (SSO/Google/GitHub):
+ *     HULY_TOKEN=eyJ...          — token from DevTools → Application → IndexedDB database name
+ *
+ *   Option B (email + password):
+ *     HULY_EMAIL=you@example.com
+ *     HULY_PASSWORD=yourpassword
+ *
+ *   Always required:
+ *     HULY_WORKSPACE=your-workspace-slug
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// ── Load compiled huly-mcp modules ──────────────────────────────────────────
+const distDir = path.join(__dirname, '..', 'dist')
+if (!fs.existsSync(path.join(distDir, 'connection.js'))) {
+  console.error('❌  dist/ not found. Run `npm run build` first.')
+  process.exit(1)
+}
+const { getConnection, closeConnection } = require(path.join(distDir, 'connection'))
+const tracker = require('@hcengineering/tracker')
+const task = require('@hcengineering/task')
+const { SortingOrder, generateId } = require('@hcengineering/core')
+const { makeRank } = require('@hcengineering/rank')
+
+// ── Parse CLI args ────────────────────────────────────────────────────────────
+const [,, csvFile, projectIdentifier] = process.argv
+if (!csvFile || !projectIdentifier) {
+  console.error('Usage: node scripts/import-csv.js <csv-file> <project-identifier>')
+  process.exit(1)
+}
+if (!fs.existsSync(csvFile)) {
+  console.error(`❌  File not found: ${csvFile}`)
+  process.exit(1)
+}
+
+// ── CSV parser (no dependencies) ─────────────────────────────────────────────
+function parseCsv (text) {
+  const lines = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').filter(Boolean)
+  if (lines.length < 2) return []
+
+  const headers = lines[0].split(',').map(h => h.trim().toLowerCase())
+  return lines.slice(1).map(line => {
+    // Handle quoted fields
+    const fields = []
+    let current = ''
+    let inQuotes = false
+    for (const ch of line) {
+      if (ch === '"') { inQuotes = !inQuotes }
+      else if (ch === ',' && !inQuotes) { fields.push(current.trim()); current = '' }
+      else { current += ch }
+    }
+    fields.push(current.trim())
+    return Object.fromEntries(headers.map((h, i) => [h, fields[i] ?? '']))
+  })
+}
+
+// ── Priority mapping ──────────────────────────────────────────────────────────
+const PRIORITY_MAP = {
+  'urgent': 1,    // IssuePriority.Urgent
+  'high': 2,      // IssuePriority.High
+  'medium': 3,    // IssuePriority.Medium
+  'low': 4,       // IssuePriority.Low
+  'no priority': 0,
+  '': 0
+}
+
+function parsePriority (str) {
+  const key = (str || '').toLowerCase().trim()
+  return PRIORITY_MAP[key] ?? 0
+}
+
+// ── Main import ───────────────────────────────────────────────────────────────
+async function main () {
+  console.log(`\n📋  Huly CSV Importer`)
+  console.log(`    File:    ${csvFile}`)
+  console.log(`    Project: ${projectIdentifier}`)
+  console.log(`    Workspace: ${process.env.HULY_WORKSPACE}\n`)
+
+  // Parse CSV
+  const rows = parseCsv(fs.readFileSync(csvFile, 'utf8'))
+  const validRows = rows.filter(r => r.title && r.title.trim())
+  console.log(`📂  Found ${rows.length} rows, ${validRows.length} with titles.\n`)
+
+  if (validRows.length === 0) {
+    console.error('❌  No valid rows found. Make sure CSV has a "title" column.')
+    process.exit(1)
+  }
+
+  // Connect to Huly
+  console.log('🔌  Connecting to Huly...')
+  const client = await getConnection()
+  console.log('✅  Connected.\n')
+
+  // Find project
+  const project = await client.findOne(tracker.default.class.Project, { identifier: projectIdentifier })
+  if (project == null) {
+    console.error(`❌  Project '${projectIdentifier}' not found.`)
+    await closeConnection()
+    process.exit(1)
+  }
+
+  // Load statuses — Huly stores them in project space OR global model space
+  let statuses = await client.findAll(tracker.default.class.IssueStatus, { space: project._id })
+  if (statuses.length === 0) {
+    // Fall back to global model-level statuses (used by default project types)
+    statuses = await client.findAll(tracker.default.class.IssueStatus, {})
+  }
+  const statusMap = new Map(statuses.map(s => [s.name.toLowerCase(), s]))
+  const defaultStatus = project.defaultIssueStatus != null
+    ? (statuses.find(s => s._id === project.defaultIssueStatus) ?? statuses[0])
+    : statuses[0]
+
+  // Find TaskType
+  const kind = await client.findOne(task.default.class.TaskType,
+    project.type != null ? { parent: project.type } : {})
+  if (kind == null) {
+    console.error('❌  Could not find a TaskType for this project.')
+    await closeConnection()
+    process.exit(1)
+  }
+
+  console.log(`📁  Project: ${project.name}`)
+  console.log(`📊  Available statuses: ${statuses.map(s => s.name).join(', ')}`)
+  console.log(`🎯  Default status: ${defaultStatus.name}\n`)
+
+  // Import rows
+  let created = 0
+  let failed = 0
+
+  for (let i = 0; i < validRows.length; i++) {
+    const row = validRows[i]
+    const num = i + 1
+
+    process.stdout.write(`[${num}/${validRows.length}] Creating: "${row.title.slice(0, 60)}"... `)
+
+    try {
+      // Increment sequence
+      const incResult = await client.updateDoc(
+        tracker.default.class.Project,
+        project.space,
+        project._id,
+        { $inc: { sequence: 1 } },
+        true
+      )
+      const issueNumber = incResult?.object?.sequence ?? project.sequence + 1
+      const identifier = `${project.identifier}-${issueNumber}`
+
+      // Resolve status
+      const statusName = (row.status || '').toLowerCase().trim()
+      const status = statusName ? (statusMap.get(statusName) ?? defaultStatus) : defaultStatus
+
+      // Compute rank
+      const lastIssue = await client.findOne(
+        tracker.default.class.Issue,
+        { space: project._id },
+        { sort: { rank: SortingOrder.Descending } }
+      )
+      const rank = makeRank(lastIssue?.rank, undefined)
+
+      // Create issue
+      const issueId = generateId()
+      await client.addCollection(
+        tracker.default.class.Issue,
+        project._id,
+        tracker.default.ids.NoParent,
+        tracker.default.class.Issue,
+        'subIssues',
+        {
+          title: row.title.trim(),
+          description: null,
+          status: status._id,
+          priority: parsePriority(row.priority),
+          number: issueNumber,
+          identifier,
+          rank,
+          kind: kind._id,
+          comments: 0,
+          subIssues: 0,
+          dueDate: row.duedate || row.dueDate
+            ? new Date(row.duedate || row.dueDate).getTime()
+            : null,
+          assignee: null,
+          component: null,
+          milestone: null,
+          parents: [],
+          remainingTime: 0,
+          estimation: 0,
+          reportedTime: 0,
+          reports: 0,
+          childInfo: [],
+          relations: []
+        },
+        issueId
+      )
+
+      console.log(`✅ ${identifier}`)
+      created++
+    } catch (err) {
+      console.log(`❌ ERROR: ${err.message}`)
+      failed++
+    }
+  }
+
+  await closeConnection()
+
+  console.log(`\n${'─'.repeat(50)}`)
+  console.log(`✅  Created: ${created}   ❌ Failed: ${failed}`)
+  console.log(`${'─'.repeat(50)}\n`)
+}
+
+main().catch(err => {
+  console.error('\n❌  Fatal error:', err.message)
+  process.exit(1)
+})

package/scripts/sample-tasks.csv

@@ -0,0 +1,11 @@
+title,priority,status,dueDate
+Fix login timeout bug,High,In Progress,2025-04-01
+Add dark mode support,Medium,,
+Update onboarding flow,Low,,2025-05-15
+Write API documentation,Medium,,
+Fix mobile layout issues,High,,
+Performance optimization for dashboard,Urgent,,2025-03-31
+Add two-factor authentication,High,,
+Update privacy policy page,Low,,
+Fix broken image uploads,High,In Progress,
+Improve search functionality,Medium,,

package/scripts/setup.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * One-time setup: authenticate via OTP and save your token to .env
+ *
+ * Usage:
+ *   node scripts/setup.js
+ *
+ * What it does:
+ *   1. Sends a one-time code to your email
+ *   2. You paste the code
+ *   3. Saves HULY_TOKEN + HULY_WORKSPACE to .env
+ *
+ * After setup, the MCP server and import script work without any manual token steps.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const readline = require('readline')
+
+const { getClient } = require('@hcengineering/account-client')
+
+const envFile = path.join(__dirname, '..', '.env')
+const accountsUrl = process.env.HULY_ACCOUNTS_URL ?? 'https://account.huly.app'
+
+function ask (question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()) }))
+}
+
+function writeEnv (token, workspace, accountsUrl) {
+  const lines = [
+    `HULY_WORKSPACE=${workspace}`,
+    `HULY_TOKEN=${token}`,
+    accountsUrl !== 'https://account.huly.app' ? `HULY_ACCOUNTS_URL=${accountsUrl}` : null
+  ].filter(Boolean)
+
+  // Merge with existing .env (don't overwrite unrelated vars)
+  let existing = ''
+  if (fs.existsSync(envFile)) {
+    existing = fs.readFileSync(envFile, 'utf8')
+  }
+
+  const keep = existing.split('\n').filter(line => {
+    const key = line.split('=')[0]
+    return !['HULY_TOKEN', 'HULY_WORKSPACE', 'HULY_EMAIL', 'HULY_PASSWORD', 'HULY_ACCOUNTS_URL'].includes(key)
+  })
+
+  fs.writeFileSync(envFile, [...keep.filter(Boolean), ...lines].join('\n') + '\n')
+}
+
+async function main () {
+  console.log('\n🔧  Huly MCP Setup\n')
+
+  const email = await ask('  Email address (the one you use for huly.app): ')
+  if (!email.includes('@')) { console.error('Invalid email.'); process.exit(1) }
+
+  const workspace = await ask('  Workspace slug (e.g. "medics" from huly.app/medics): ')
+  if (!workspace) { console.error('Workspace is required.'); process.exit(1) }
+
+  console.log(`\n  Sending OTP to ${email}...`)
+  const unauthClient = getClient(accountsUrl)
+  await unauthClient.loginOtp(email)
+  console.log('  ✅ Code sent!\n')
+
+  const code = await ask('  Enter the 6-digit code from your email: ')
+
+  console.log('\n  Validating...')
+  const loginInfo = await unauthClient.validateOtp(email, code.trim())
+
+  if (!loginInfo?.token) {
+    console.error('  ❌ Invalid or expired code. Run setup again.')
+    process.exit(1)
+  }
+
+  // Verify workspace is accessible
+  const authedClient = getClient(accountsUrl, loginInfo.token)
+  const wsInfo = await authedClient.selectWorkspace(workspace, 'external').catch(e => {
+    console.error(`  ❌ Could not access workspace '${workspace}': ${e.message}`)
+    process.exit(1)
+  })
+
+  if (!wsInfo?.endpoint) {
+    console.error(`  ❌ Workspace '${workspace}' not found or not accessible.`)
+    process.exit(1)
+  }
+
+  // Save token to .env
+  writeEnv(loginInfo.token, workspace, accountsUrl)
+
+  console.log(`\n  ✅ Setup complete!`)
+  console.log(`     Workspace : ${workspace}`)
+  console.log(`     Endpoint  : ${wsInfo.endpoint}`)
+  console.log(`     Token saved to .env\n`)
+  console.log('  You can now run:')
+  console.log('    node scripts/import-csv.js your-tasks.csv PROJ\n')
+}
+
+main().catch(err => {
+  console.error('\n❌ Setup failed:', err.message)
+  process.exit(1)
+})