suparank 1.2.5 → 1.2.6

package/mcp-client/config.js

@@ -0,0 +1,37 @@
+/**
+ * Suparank MCP - Configuration
+ *
+ * Centralized configuration and constants
+ */
+
+// Parse command line arguments
+export const projectSlug = process.argv[2]
+export const apiKey = process.argv[3]
+export const apiUrl = process.env.SUPARANK_API_URL || 'https://api.suparank.io'
+
+// External API endpoints - configurable via environment variables
+export const API_ENDPOINTS = {
+  fal: process.env.FAL_API_URL || 'https://fal.run/fal-ai/nano-banana-pro',
+  gemini: process.env.GEMINI_API_URL || 'https://generativelanguage.googleapis.com/v1beta/models',
+  wiro: process.env.WIRO_API_URL || 'https://api.wiro.ai/v1',
+  wiroTaskDetail: process.env.WIRO_TASK_URL || 'https://api.wiro.ai/v1/Task/Detail'
+}
+
+// Session expiration (24 hours)
+export const SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000
+
+// Tools that are visible in the MCP tool list
+export const VISIBLE_TOOLS = [
+  // Essential (5) - Main workflow
+  'create_content', 'keyword_research', 'generate_image', 'publish_content', 'get_session',
+  // Session Management (5) - Content lifecycle
+  'save_content', 'list_content', 'load_content', 'remove_article', 'clear_session'
+]
+
+// Default stats object
+export const DEFAULT_STATS = {
+  tool_calls: 0,
+  images_generated: 0,
+  articles_created: 0,
+  words_written: 0
+}

package/mcp-client/index.js

@@ -0,0 +1,22 @@
+/**
+ * Suparank MCP - Main Entry Point
+ *
+ * Modular MCP server for AI-powered SEO content creation
+ *
+ * This file re-exports from modular components and provides the main entry point.
+ * For now, the main server logic is still in ../mcp-client.js but will be
+ * migrated incrementally.
+ */
+
+// Re-export config
+export * from './config.js'
+
+// Re-export utils
+export * from './utils/index.js'
+
+// Re-export services
+export * from './services/index.js'
+
+// Main entry - for now, delegate to the original mcp-client.js
+// This will be replaced with modular server setup in future versions
+import '../mcp-client.js'

package/mcp-client/services/api.js

@@ -0,0 +1,101 @@
+/**
+ * Suparank MCP - API Service
+ *
+ * HTTP request utilities with retry and timeout handling
+ */
+
+import { log } from '../utils/logging.js'
+
+/**
+ * Fetch with timeout - prevents hanging requests
+ * @param {string} url - URL to fetch
+ * @param {object} options - Fetch options
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<Response>}
+ */
+export async function fetchWithTimeout(url, options = {}, timeoutMs = 30000) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal
+    })
+    return response
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+/**
+ * Fetch with retry - handles transient failures
+ * @param {string} url - URL to fetch
+ * @param {object} options - Fetch options
+ * @param {number} maxRetries - Maximum retry attempts
+ * @param {number} timeoutMs - Timeout per request in milliseconds
+ * @returns {Promise<Response>}
+ */
+export async function fetchWithRetry(url, options = {}, maxRetries = 3, timeoutMs = 30000) {
+  let lastError
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetchWithTimeout(url, options, timeoutMs)
+
+      // Retry on 5xx errors or rate limiting
+      if (response.status >= 500 || response.status === 429) {
+        const retryAfter = response.headers.get('retry-after')
+        const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000
+
+        if (attempt < maxRetries) {
+          log(`Request failed (${response.status}), retrying in ${delay}ms... (attempt ${attempt}/${maxRetries})`)
+          await new Promise(resolve => setTimeout(resolve, delay))
+          continue
+        }
+      }
+
+      return response
+    } catch (error) {
+      lastError = error
+
+      // Don't retry on abort (timeout)
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${timeoutMs}ms: ${url}`)
+      }
+
+      // Retry on network errors
+      if (attempt < maxRetries) {
+        const delay = Math.pow(2, attempt) * 1000
+        log(`Network error, retrying in ${delay}ms... (attempt ${attempt}/${maxRetries}): ${error.message}`)
+        await new Promise(resolve => setTimeout(resolve, delay))
+        continue
+      }
+    }
+  }
+
+  throw lastError || new Error(`Request failed after ${maxRetries} attempts: ${url}`)
+}
+
+/**
+ * Make an authenticated request to the Suparank API
+ * @param {string} apiUrl - Base API URL
+ * @param {string} apiKey - API key
+ * @param {string} endpoint - API endpoint
+ * @param {object} options - Additional fetch options
+ * @returns {Promise<Response>}
+ */
+export async function apiRequest(apiUrl, apiKey, endpoint, options = {}) {
+  const url = `${apiUrl}${endpoint}`
+
+  const headers = {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+    ...options.headers
+  }
+
+  return fetchWithRetry(url, {
+    ...options,
+    headers
+  })
+}

package/mcp-client/services/credentials.js

@@ -0,0 +1,127 @@
+/**
+ * Suparank MCP - Credentials Service
+ *
+ * Local credentials management for CMS and API integrations
+ */
+
+import * as fs from 'fs'
+import { getCredentialsFilePath } from '../utils/paths.js'
+import { log } from '../utils/logging.js'
+
+// Cached credentials
+let localCredentials = null
+
+/**
+ * Load local credentials from ~/.suparank/credentials.json
+ * @returns {object|null} Credentials object or null
+ */
+export function loadCredentials() {
+  if (localCredentials !== null) {
+    return localCredentials
+  }
+
+  const credentialsPath = getCredentialsFilePath()
+
+  try {
+    if (fs.existsSync(credentialsPath)) {
+      const content = fs.readFileSync(credentialsPath, 'utf-8')
+      localCredentials = JSON.parse(content)
+      log(`Loaded credentials from ${credentialsPath}`)
+
+      // Log which integrations are configured (without exposing keys)
+      const configured = []
+      if (localCredentials.wordpress?.secret_key || localCredentials.wordpress?.app_password) {
+        configured.push('WordPress')
+      }
+      if (localCredentials.ghost?.admin_api_key) {
+        configured.push('Ghost')
+      }
+      if (localCredentials.image_provider && localCredentials[localCredentials.image_provider]?.api_key) {
+        configured.push(`Images (${localCredentials.image_provider})`)
+      }
+      if (localCredentials.webhooks && Object.values(localCredentials.webhooks).some(Boolean)) {
+        configured.push('Webhooks')
+      }
+      if (localCredentials.external_mcps?.length) {
+        configured.push(`External MCPs (${localCredentials.external_mcps.length})`)
+      }
+
+      if (configured.length > 0) {
+        log(`Configured integrations: ${configured.join(', ')}`)
+      }
+
+      return localCredentials
+    }
+  } catch (error) {
+    log(`Warning: Could not load credentials: ${error.message}`)
+  }
+
+  localCredentials = {}
+  return localCredentials
+}
+
+/**
+ * Get the current credentials object
+ * @returns {object} Credentials object
+ */
+export function getCredentials() {
+  if (localCredentials === null) {
+    loadCredentials()
+  }
+  return localCredentials || {}
+}
+
+/**
+ * Check if a specific credential type is available
+ * @param {string} type - Credential type (wordpress, ghost, fal, gemini, wiro, image, webhooks)
+ * @returns {boolean} Whether the credential is available
+ */
+export function hasCredential(type) {
+  const creds = getCredentials()
+
+  switch (type) {
+    case 'wordpress':
+      return !!(creds.wordpress?.secret_key || creds.wordpress?.app_password)
+    case 'ghost':
+      return !!creds.ghost?.admin_api_key
+    case 'fal':
+      return !!creds.fal?.api_key
+    case 'gemini':
+      return !!creds.gemini?.api_key
+    case 'wiro':
+      return !!creds.wiro?.api_key
+    case 'image':
+      const provider = creds.image_provider
+      return provider && hasCredential(provider)
+    case 'webhooks':
+      return !!(creds.webhooks && Object.values(creds.webhooks).some(Boolean))
+    default:
+      return false
+  }
+}
+
+/**
+ * Get the configured image provider
+ * @returns {string|null} Image provider name or null
+ */
+export function getImageProvider() {
+  const creds = getCredentials()
+  return creds.image_provider || null
+}
+
+/**
+ * Get configuration for a specific provider
+ * @param {string} provider - Provider name
+ * @returns {object|null} Provider config or null
+ */
+export function getProviderConfig(provider) {
+  const creds = getCredentials()
+  return creds[provider] || null
+}
+
+/**
+ * Clear cached credentials (for testing)
+ */
+export function clearCredentialsCache() {
+  localCredentials = null
+}

package/mcp-client/services/index.js

@@ -0,0 +1,10 @@
+/**
+ * Suparank MCP - Services Index
+ *
+ * Re-exports all service modules
+ */
+
+export * from './api.js'
+export * from './credentials.js'
+export * from './session-state.js'
+export * from './stats.js'

package/mcp-client/services/session-state.js

@@ -0,0 +1,201 @@
+/**
+ * Suparank MCP - Session State Service
+ *
+ * Session state management with persistence and mutex protection
+ */
+
+import * as fs from 'fs'
+import {
+  getSessionFilePath,
+  ensureSuparankDir,
+  atomicWriteSync
+} from '../utils/paths.js'
+import { log, progress } from '../utils/logging.js'
+import { SESSION_EXPIRY_MS } from '../config.js'
+
+// Session state object
+export const sessionState = {
+  currentWorkflow: null,
+  stepResults: {},
+  articles: [],
+  article: null,
+  title: null,
+  imageUrl: null,
+  inlineImages: [],
+  keywords: null,
+  metadata: null,
+  metaTitle: null,
+  metaDescription: null,
+  contentFolder: null
+}
+
+// Session mutex for concurrent access protection
+let sessionLock = false
+const sessionLockQueue = []
+
+/**
+ * Acquire session lock for safe concurrent access
+ * @returns {Promise<void>}
+ */
+export async function acquireSessionLock() {
+  if (!sessionLock) {
+    sessionLock = true
+    return
+  }
+  return new Promise(resolve => {
+    sessionLockQueue.push(resolve)
+  })
+}
+
+/**
+ * Release session lock
+ */
+export function releaseSessionLock() {
+  if (sessionLockQueue.length > 0) {
+    const next = sessionLockQueue.shift()
+    next()
+  } else {
+    sessionLock = false
+  }
+}
+
+/**
+ * Generate a unique article ID
+ * @returns {string} Unique ID
+ */
+export function generateArticleId() {
+  return `article-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`
+}
+
+/**
+ * Check if session has expired
+ * @param {string} savedAt - ISO timestamp when session was saved
+ * @returns {boolean} Whether session has expired
+ */
+export function isSessionExpired(savedAt) {
+  if (!savedAt) return true
+  const savedTime = new Date(savedAt).getTime()
+  const now = Date.now()
+  return (now - savedTime) > SESSION_EXPIRY_MS
+}
+
+/**
+ * Save session state to file
+ * Uses atomic write to prevent corruption
+ */
+export function saveSession() {
+  try {
+    ensureSuparankDir()
+    const sessionFile = getSessionFilePath()
+
+    const toSave = {
+      currentWorkflow: sessionState.currentWorkflow,
+      stepResults: sessionState.stepResults,
+      articles: sessionState.articles,
+      article: sessionState.article,
+      title: sessionState.title,
+      imageUrl: sessionState.imageUrl,
+      inlineImages: sessionState.inlineImages,
+      keywords: sessionState.keywords,
+      metadata: sessionState.metadata,
+      metaTitle: sessionState.metaTitle,
+      metaDescription: sessionState.metaDescription,
+      contentFolder: sessionState.contentFolder,
+      savedAt: new Date().toISOString()
+    }
+
+    atomicWriteSync(sessionFile, JSON.stringify(toSave, null, 2))
+    progress('Session', `Saved to ${sessionFile} (${sessionState.articles.length} articles)`)
+  } catch (error) {
+    log(`Warning: Failed to save session: ${error.message}`)
+    progress('Session', `FAILED to save: ${error.message}`)
+  }
+}
+
+/**
+ * Safe session save with mutex
+ * @returns {Promise<void>}
+ */
+export async function saveSessionSafe() {
+  await acquireSessionLock()
+  try {
+    saveSession()
+  } finally {
+    releaseSessionLock()
+  }
+}
+
+/**
+ * Load session state from file
+ * @returns {boolean} Whether session was restored
+ */
+export function restoreSession() {
+  const sessionFile = getSessionFilePath()
+
+  try {
+    if (fs.existsSync(sessionFile)) {
+      const content = fs.readFileSync(sessionFile, 'utf-8')
+      const saved = JSON.parse(content)
+
+      // Check if session is expired (24 hour max)
+      if (isSessionExpired(saved.savedAt)) {
+        log('Session expired, starting fresh')
+        return false
+      }
+
+      // Restore state
+      sessionState.currentWorkflow = saved.currentWorkflow || null
+      sessionState.stepResults = saved.stepResults || {}
+      sessionState.articles = saved.articles || []
+      sessionState.article = saved.article || null
+      sessionState.title = saved.title || null
+      sessionState.imageUrl = saved.imageUrl || null
+      sessionState.inlineImages = saved.inlineImages || []
+      sessionState.keywords = saved.keywords || null
+      sessionState.metadata = saved.metadata || null
+      sessionState.metaTitle = saved.metaTitle || null
+      sessionState.metaDescription = saved.metaDescription || null
+      sessionState.contentFolder = saved.contentFolder || null
+
+      log(`Session restored: ${sessionState.articles.length} articles, workflow: ${sessionState.currentWorkflow?.workflow_id || 'none'}`)
+      return true
+    }
+  } catch (error) {
+    log(`Warning: Could not restore session: ${error.message}`)
+  }
+
+  return false
+}
+
+/**
+ * Reset session state to initial values
+ */
+export function resetSession() {
+  sessionState.currentWorkflow = null
+  sessionState.stepResults = {}
+  sessionState.articles = []
+  sessionState.article = null
+  sessionState.title = null
+  sessionState.imageUrl = null
+  sessionState.inlineImages = []
+  sessionState.keywords = null
+  sessionState.metadata = null
+  sessionState.metaTitle = null
+  sessionState.metaDescription = null
+  sessionState.contentFolder = null
+}
+
+/**
+ * Clear session file from disk
+ */
+export function clearSessionFile() {
+  const sessionFile = getSessionFilePath()
+  try {
+    if (fs.existsSync(sessionFile)) {
+      fs.unlinkSync(sessionFile)
+      log('Session file cleared')
+    }
+  } catch (error) {
+    log(`Warning: Could not clear session file: ${error.message}`)
+  }
+}

package/mcp-client/services/stats.js

@@ -0,0 +1,50 @@
+/**
+ * Suparank MCP - Stats Service
+ *
+ * Usage statistics tracking
+ */
+
+import * as fs from 'fs'
+import { getStatsFilePath, ensureSuparankDir } from '../utils/paths.js'
+import { log } from '../utils/logging.js'
+import { DEFAULT_STATS } from '../config.js'
+
+/**
+ * Load usage stats from file
+ * @returns {object} Stats object
+ */
+export function loadStats() {
+  try {
+    const file = getStatsFilePath()
+    if (fs.existsSync(file)) {
+      return JSON.parse(fs.readFileSync(file, 'utf-8'))
+    }
+  } catch (e) {
+    log(`Warning: Could not load stats: ${e.message}`)
+  }
+  return { ...DEFAULT_STATS }
+}
+
+/**
+ * Save usage stats to file
+ * @param {object} stats - Stats object to save
+ */
+export function saveStats(stats) {
+  try {
+    ensureSuparankDir()
+    fs.writeFileSync(getStatsFilePath(), JSON.stringify(stats, null, 2))
+  } catch (e) {
+    log(`Error saving stats: ${e.message}`)
+  }
+}
+
+/**
+ * Increment a stat counter
+ * @param {string} key - Stat key to increment
+ * @param {number} amount - Amount to add (default: 1)
+ */
+export function incrementStat(key, amount = 1) {
+  const stats = loadStats()
+  stats[key] = (stats[key] || 0) + amount
+  saveStats(stats)
+}

package/mcp-client/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * Suparank MCP - Utils Index
+ *
+ * Re-exports all utility modules
+ */
+
+export * from './logging.js'
+export * from './paths.js'

package/mcp-client/utils/logging.js

@@ -0,0 +1,38 @@
+/**
+ * Suparank MCP - Logging Utilities
+ *
+ * Standardized logging to stderr (stdout is for MCP protocol)
+ */
+
+/**
+ * Log message to stderr with [suparank] prefix
+ * @param {...any} args - Arguments to log
+ */
+export function log(...args) {
+  console.error('[suparank]', ...args)
+}
+
+/**
+ * Structured progress logging for user visibility
+ * @param {string} step - Current step name
+ * @param {string} message - Progress message
+ */
+export function progress(step, message) {
+  console.error(`[suparank] ${step}: ${message}`)
+}
+
+/**
+ * Log warning message
+ * @param {...any} args - Arguments to log
+ */
+export function warn(...args) {
+  console.error('[suparank] WARNING:', ...args)
+}
+
+/**
+ * Log error message
+ * @param {...any} args - Arguments to log
+ */
+export function error(...args) {
+  console.error('[suparank] ERROR:', ...args)
+}

package/mcp-client/utils/paths.js

@@ -0,0 +1,134 @@
+/**
+ * Suparank MCP - Path Utilities
+ *
+ * Safe path handling and directory management
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import * as os from 'os'
+
+/**
+ * Get the Suparank configuration directory
+ * @returns {string} Path to ~/.suparank
+ */
+export function getSuparankDir() {
+  return path.join(os.homedir(), '.suparank')
+}
+
+/**
+ * Get the content storage directory
+ * @returns {string} Path to ~/.suparank/content
+ */
+export function getContentDir() {
+  return path.join(getSuparankDir(), 'content')
+}
+
+/**
+ * Get session file path
+ * @returns {string} Path to ~/.suparank/session.json
+ */
+export function getSessionFilePath() {
+  return path.join(getSuparankDir(), 'session.json')
+}
+
+/**
+ * Get credentials file path
+ * @returns {string} Path to ~/.suparank/credentials.json
+ */
+export function getCredentialsFilePath() {
+  return path.join(getSuparankDir(), 'credentials.json')
+}
+
+/**
+ * Get stats file path
+ * @returns {string} Path to ~/.suparank/stats.json
+ */
+export function getStatsFilePath() {
+  return path.join(getSuparankDir(), 'stats.json')
+}
+
+/**
+ * Ensure the Suparank directory exists
+ */
+export function ensureSuparankDir() {
+  const dir = getSuparankDir()
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * Ensure the content directory exists
+ */
+export function ensureContentDir() {
+  const dir = getContentDir()
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * Sanitize and validate a path to prevent traversal attacks
+ * @param {string} userPath - User-provided path segment
+ * @param {string} allowedBase - Base directory that paths must stay within
+ * @returns {string} Resolved safe path
+ * @throws {Error} If path would escape the allowed base
+ */
+export function sanitizePath(userPath, allowedBase) {
+  // Remove any null bytes (common attack vector)
+  const cleanPath = userPath.replace(/\0/g, '')
+
+  // Resolve to absolute path
+  const resolved = path.resolve(allowedBase, cleanPath)
+
+  // Ensure the resolved path starts with the allowed base
+  const normalizedBase = path.normalize(allowedBase + path.sep)
+  const normalizedResolved = path.normalize(resolved + path.sep)
+
+  if (!normalizedResolved.startsWith(normalizedBase)) {
+    throw new Error(`Path traversal detected: "${userPath}" would escape allowed directory`)
+  }
+
+  return resolved
+}
+
+/**
+ * Get content folder path safely
+ * @param {string} folderName - Folder name (article ID or title slug)
+ * @returns {string} Safe path to content folder
+ */
+export function getContentFolderSafe(folderName) {
+  const contentDir = getContentDir()
+  return sanitizePath(folderName, contentDir)
+}
+
+/**
+ * Generate a slug from title for folder naming
+ * @param {string} text - Text to slugify
+ * @returns {string} URL-safe slug
+ */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 50)
+}
+
+/**
+ * Atomic file write - prevents corruption on concurrent writes
+ * @param {string} filePath - Target file path
+ * @param {string} data - Data to write
+ */
+export function atomicWriteSync(filePath, data) {
+  const tmpFile = filePath + '.tmp.' + process.pid
+  try {
+    fs.writeFileSync(tmpFile, data)
+    fs.renameSync(tmpFile, filePath) // Atomic on POSIX
+  } catch (error) {
+    // Clean up temp file if rename failed
+    try { fs.unlinkSync(tmpFile) } catch (e) { /* ignore */ }
+    throw error
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suparank",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "AI-powered SEO content creation MCP - generate and publish optimized blog posts with Claude, ChatGPT, or Cursor",
   "main": "mcp-client.js",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "mcp-client.js",
+    "mcp-client/",
     "credentials.example.json",
     "README.md",
     "LICENSE"