@higrowth/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# @higrowth/mcp-server
+
+Connect AI assistants to [HiGrowth](https://higrowthdev.com) SEO tools via the Model Context Protocol (MCP).
+
+## Features
+
+- 🔍 **Discover Opportunities** - Find SEO optimization opportunities
+- 💡 **Keyword Ideas** - Generate keyword variations and ideas
+- 📝 **Content Planning** - Create comprehensive content strategies
+- ✍️ **Content Generation** - Generate SEO-optimized content
+- 🔬 **Content Reviews** - Review content for SEO quality
+- 📊 **Page Analysis** - Analyze page performance
+- 🛠️ **Optimization Fixes** - Get specific optimization recommendations
+- 📈 **Keyword Data** - Get keyword performance metrics
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Sign up at [higrowthdev.com](https://higrowthdev.com) to get your MCP API key.
+
+### 2. Connect to Cursor
+
+Add this to your `.mcp.json` file (usually in your project root or `~/.cursor/`):
+
+```json
+{
+  "mcpServers": {
+    "higrowth": {
+      "command": "npx",
+      "args": ["-y", "@higrowth/mcp-server", "--api-key=YOUR_API_KEY"]
+    }
+  }
+}
+```
+
+### 3. Restart Cursor
+
+Restart Cursor to load the MCP server. You should see "higrowth" in your available tools.
+
+## Usage
+
+Once connected, you can ask your AI assistant questions like:
+
+- "Find SEO opportunities for my site"
+- "Generate keyword ideas for 'cloud computing'"
+- "Create a content plan for 'kubernetes best practices'"
+- "Analyze the page at https://example.com/blog/post"
+- "What optimization fixes should I make?"
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `discover_opportunities` | Discover SEO optimization opportunities |
+| `list_opportunities` | List existing opportunities with filters |
+| `suggest_keyword_ideas` | Generate keyword variations from a seed |
+| `create_content_plan` | Create content strategy and outlines |
+| `generate_content` | Generate full SEO-optimized content |
+| `run_content_reviews` | Run SEO and quality reviews |
+| `analyze_page` | Analyze a page for SEO performance |
+| `get_optimization_fixes` | Get specific optimization recommendations |
+| `get_task_status` | Check status of async operations |
+| `get_page_keyword_data` | Get keyword performance metrics |
+| `search_page_keywords` | Semantic search for keywords |
+
+## Configuration Options
+
+### Command Line
+
+```bash
+npx @higrowth/mcp-server --api-key=YOUR_KEY
+npx @higrowth/mcp-server --api-key=YOUR_KEY --url=https://custom.api.com/api/v1/mcp
+```
+
+### Environment Variables
+
+```bash
+export HIGROWTH_API_KEY=your_api_key
+export HIGROWTH_MCP_URL=https://api.higrowthdev.com/api/v1/mcp  # optional
+
+npx @higrowth/mcp-server
+```
+
+### Cursor Configuration with Environment Variables
+
+```json
+{
+  "mcpServers": {
+    "higrowth": {
+      "command": "npx",
+      "args": ["-y", "@higrowth/mcp-server"],
+      "env": {
+        "HIGROWTH_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Self-Hosted / Enterprise
+
+For self-hosted HiGrowth installations, specify your custom API URL:
+
+```json
+{
+  "mcpServers": {
+    "higrowth": {
+      "command": "npx",
+      "args": [
+        "-y", 
+        "@higrowth/mcp-server", 
+        "--api-key=YOUR_KEY",
+        "--url=https://your-api.company.com/api/v1/mcp"
+      ]
+    }
+  }
+}
+```
+
+## Programmatic Usage
+
+You can also use the server programmatically:
+
+```javascript
+import { MCPServer } from '@higrowth/mcp-server';
+
+const server = new MCPServer(
+  'https://api.higrowthdev.com/api/v1/mcp',
+  'your-api-key'
+);
+
+await server.start();
+```
+
+## Troubleshooting
+
+### Server not appearing in Cursor
+
+1. Ensure your `.mcp.json` is valid JSON
+2. Restart Cursor completely (Cmd/Ctrl+Q, then reopen)
+3. Check Cursor's developer console for errors (Help → Toggle Developer Tools)
+
+### Authentication errors
+
+1. Verify your API key is correct
+2. Test the connection directly:
+   ```bash
+   curl https://api.higrowthdev.com/api/v1/mcp/tools \
+     -H "X-API-Key: YOUR_KEY"
+   ```
+
+### Connection timeouts
+
+1. Check your network connection
+2. Verify the API URL is accessible
+3. For enterprise installations, check firewall rules
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Valid HiGrowth API key
+
+## License
+
+MIT
+
+## Support
+
+- 📧 Email: support@higrowthdev.com
+- 📖 Docs: https://docs.higrowthdev.com
+- 🐛 Issues: https://github.com/higrowth/mcp-server/issues

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@higrowth/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for HiGrowth SEO platform - connect AI assistants to SEO tools",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seo",
+    "ai",
+    "cursor",
+    "claude",
+    "higrowth"
+  ],
+  "author": "HiGrowth",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/higrowth/mcp-server.git"
+  },
+  "homepage": "https://higrowthdev.com",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "higrowth-mcp": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test src/*.test.js"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * HiGrowth MCP Server CLI
+ * 
+ * Usage:
+ *   npx @higrowth/mcp-server --api-key=YOUR_KEY
+ *   npx @higrowth/mcp-server --api-key=YOUR_KEY --url=https://custom.api.com/api/v1/mcp
+ * 
+ * Environment variables:
+ *   HIGROWTH_API_KEY - Your MCP API key
+ *   HIGROWTH_MCP_URL - Custom MCP endpoint URL (optional)
+ */
+
+import { MCPServer } from './server.js';
+
+const DEFAULT_URL = 'https://api.higrowthdev.com/api/v1/mcp';
+
+function parseArgs(args) {
+  const config = {
+    apiKey: process.env.HIGROWTH_API_KEY || process.env.CGEN_API_KEY,
+    url: process.env.HIGROWTH_MCP_URL || process.env.CGEN_MCP_URL || DEFAULT_URL,
+    help: false,
+  };
+
+  for (const arg of args) {
+    if (arg === '--help' || arg === '-h') {
+      config.help = true;
+    } else if (arg.startsWith('--api-key=')) {
+      config.apiKey = arg.split('=')[1];
+    } else if (arg.startsWith('--url=')) {
+      config.url = arg.split('=')[1];
+    }
+  }
+
+  return config;
+}
+
+function showHelp() {
+  console.error(`
+HiGrowth MCP Server - Connect AI assistants to HiGrowth SEO tools
+
+USAGE:
+  npx @higrowth/mcp-server --api-key=YOUR_KEY [options]
+
+OPTIONS:
+  --api-key=KEY    Your HiGrowth MCP API key (required)
+  --url=URL        Custom MCP endpoint URL (default: ${DEFAULT_URL})
+  --help, -h       Show this help message
+
+ENVIRONMENT VARIABLES:
+  HIGROWTH_API_KEY  Your MCP API key (alternative to --api-key)
+  HIGROWTH_MCP_URL  Custom endpoint URL (alternative to --url)
+
+CURSOR CONFIGURATION:
+  Add to your .mcp.json:
+  
+  {
+    "mcpServers": {
+      "higrowth": {
+        "command": "npx",
+        "args": ["-y", "@higrowth/mcp-server", "--api-key=YOUR_KEY"]
+      }
+    }
+  }
+
+AVAILABLE TOOLS:
+  • discover_opportunities  - Find SEO optimization opportunities
+  • suggest_keyword_ideas   - Generate keyword variations
+  • create_content_plan     - Create content strategies
+  • generate_content        - Generate SEO-optimized content
+  • run_content_reviews     - Review content for SEO quality
+  • analyze_page            - Analyze page performance
+  • get_optimization_fixes  - Get specific optimization recommendations
+  • get_task_status         - Check async task status
+  • get_page_keyword_data   - Get keyword performance data
+  • search_page_keywords    - Search keywords semantically
+  • list_opportunities      - List existing opportunities
+
+Get your API key at: https://higrowthdev.com
+`);
+}
+
+async function main() {
+  const config = parseArgs(process.argv.slice(2));
+
+  if (config.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (!config.apiKey) {
+    console.error('Error: API key is required.');
+    console.error('');
+    console.error('Provide it via:');
+    console.error('  --api-key=YOUR_KEY argument');
+    console.error('  HIGROWTH_API_KEY environment variable');
+    console.error('');
+    console.error('Run with --help for more information.');
+    process.exit(1);
+  }
+
+  const server = new MCPServer(config.url, config.apiKey);
+  await server.start();
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error.message);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * HiGrowth MCP Server
+ * 
+ * Programmatic API for embedding the MCP server in other applications.
+ * 
+ * @example
+ * import { MCPServer } from '@higrowth/mcp-server';
+ * 
+ * const server = new MCPServer(
+ *   'https://api.higrowthdev.com/api/v1/mcp',
+ *   'your-api-key'
+ * );
+ * await server.start();
+ */
+
+export { MCPServer } from './server.js';

package/src/server.js

@@ -0,0 +1,188 @@
+/**
+ * HiGrowth MCP Server
+ * 
+ * Bridges the Model Context Protocol (MCP) to the HiGrowth SEO API.
+ * Communicates via stdio with MCP clients like Cursor.
+ */
+
+import * as readline from 'readline';
+
+const SERVER_INFO = {
+  name: 'higrowth-mcp-server',
+  version: '1.0.0',
+};
+
+const CAPABILITIES = {
+  tools: {},
+};
+
+export class MCPServer {
+  constructor(apiUrl, apiKey) {
+    this.apiUrl = apiUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.apiKey = apiKey;
+    this.tools = null;
+  }
+
+  async start() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+
+    rl.on('line', async (line) => {
+      if (!line.trim()) return;
+
+      try {
+        const request = JSON.parse(line);
+        const response = await this.handleRequest(request);
+        if (response) {
+          console.log(JSON.stringify(response));
+        }
+      } catch (error) {
+        const errorResponse = {
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32700,
+            message: 'Parse error',
+            data: error.message,
+          },
+        };
+        console.log(JSON.stringify(errorResponse));
+      }
+    });
+
+    rl.on('close', () => {
+      process.exit(0);
+    });
+
+    // Keep process alive
+    process.stdin.resume();
+  }
+
+  async handleRequest(request) {
+    const { id, method, params } = request;
+
+    // Notifications (no id) don't need responses
+    if (id === undefined && method === 'notifications/initialized') {
+      return null;
+    }
+
+    try {
+      let result;
+
+      switch (method) {
+        case 'initialize':
+          result = await this.handleInitialize(params);
+          break;
+        case 'tools/list':
+          result = await this.handleListTools();
+          break;
+        case 'tools/call':
+          result = await this.handleCallTool(params);
+          break;
+        case 'ping':
+          result = {};
+          break;
+        default:
+          return {
+            jsonrpc: '2.0',
+            id,
+            error: {
+              code: -32601,
+              message: `Method not found: ${method}`,
+            },
+          };
+      }
+
+      return {
+        jsonrpc: '2.0',
+        id,
+        result,
+      };
+    } catch (error) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32000,
+          message: error.message,
+          data: error.stack,
+        },
+      };
+    }
+  }
+
+  async handleInitialize(params) {
+    // Fetch tools on initialization to validate connection
+    await this.fetchTools();
+
+    return {
+      protocolVersion: '2024-11-05',
+      serverInfo: SERVER_INFO,
+      capabilities: CAPABILITIES,
+    };
+  }
+
+  async handleListTools() {
+    if (!this.tools) {
+      await this.fetchTools();
+    }
+    return { tools: this.tools };
+  }
+
+  async handleCallTool(params) {
+    const { name, arguments: args } = params;
+
+    try {
+      const response = await fetch(`${this.apiUrl}/tools/call`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+        body: JSON.stringify({ name, arguments: args || {} }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`API error (${response.status}): ${errorText}`);
+      }
+
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error calling tool ${name}: ${error.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  async fetchTools() {
+    try {
+      const response = await fetch(`${this.apiUrl}/tools`, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': this.apiKey,
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to fetch tools (${response.status}): ${errorText}`);
+      }
+
+      const data = await response.json();
+      this.tools = data.tools || [];
+    } catch (error) {
+      throw new Error(`Cannot connect to HiGrowth API: ${error.message}`);
+    }
+  }
+}