signal-relay-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SocioLogic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Signal Relay - SocioLogic MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+
+A remote MCP (Model Context Protocol) server that connects AI agents to [SocioLogic's](https://sociologic.ai) synthetic persona platform. Interview realistic customer personas, run multi-persona research campaigns, and export board-ready reports—all through natural conversation.
+
+## Features
+
+- **15 MCP Tools** - Full access to personas, campaigns, focus groups, and credits
+- **High-Fidelity Personas** - Synthetic personas with consistent demographics, psychographics, and behavior
+- **Semantic Memory** - RAG-powered memory retrieval for persona continuity across conversations
+- **Edge Deployed** - Runs on Cloudflare Workers (300+ locations, <50ms latency)
+- **Secure** - API key authentication, request validation, no data stored on edge
+
+## Quick Start
+
+### Use the Hosted Server (Recommended)
+
+The fastest way to get started is using our hosted server at `https://mcp.sociologicai.com`.
+
+1. **Get an API key** at [sociologic.ai/dashboard/api-keys](https://sociologic.ai/dashboard/api-keys) (100 free credits on signup)
+
+2. **Configure your MCP client:**
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+```json
+{
+  "mcpServers": {
+    "sociologic": {
+      "transport": "http",
+      "url": "https://mcp.sociologicai.com",
+      "headers": {
+        "X-API-Key": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json` in your project):
+```json
+{
+  "mcpServers": {
+    "sociologic": {
+      "transport": "http",
+      "url": "https://mcp.sociologicai.com",
+      "headers": {
+        "X-API-Key": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+3. **Start chatting!** Ask Claude to interview personas, create campaigns, or explore the marketplace.
+
+## Self-Hosting
+
+Deploy your own instance to Cloudflare Workers:
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) v18+
+- [Cloudflare account](https://dash.cloudflare.com/sign-up) (free tier works)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/SocioLogicAI/signal-relay.git
+cd signal-relay
+
+# Install dependencies
+npm install
+
+# Login to Cloudflare
+npx wrangler login
+
+# Deploy
+npx wrangler deploy
+```
+
+Your server will be available at `https://sociologic-mcp-server.<your-subdomain>.workers.dev`
+
+### Local Development
+
+```bash
+npm run dev
+```
+
+Starts a local server at `http://localhost:8787`.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `sociologic_list_personas` | List synthetic personas from marketplace or private collection |
+| `sociologic_get_persona` | Get detailed persona information (demographics, psychographics, traits) |
+| `sociologic_create_persona` | Generate a new persona from natural language description |
+| `sociologic_interview_persona` | Conduct adversarial interview with a persona |
+| `sociologic_get_persona_memories` | Retrieve persona's semantic memories via vector search |
+| `sociologic_list_campaigns` | List research campaigns with status and results |
+| `sociologic_get_campaign` | Get campaign details including interviews and findings |
+| `sociologic_create_campaign` | Create multi-persona research campaign with custom questions |
+| `sociologic_execute_campaign` | Execute draft campaign (async background processing) |
+| `sociologic_export_campaign` | Export campaign results as PDF or JSON |
+| `sociologic_list_focus_groups` | List focus groups for cohort-based research |
+| `sociologic_get_focus_group` | Get focus group details with member personas |
+| `sociologic_create_focus_group` | Create new focus group to organize personas |
+| `sociologic_add_personas_to_focus_group` | Add personas to an existing focus group |
+| `sociologic_get_credits_balance` | Check current credits balance and usage |
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | POST | JSON-RPC 2.0 endpoint for MCP protocol |
+| `/health` | GET | Health check (requires API key) |
+| `/info` | GET | Server information and available tools |
+
+## Example Usage
+
+### Interview a Persona
+
+```bash
+curl -X POST https://mcp.sociologicai.com/ \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "sociologic_interview_persona",
+      "arguments": {
+        "slug": "enterprise-buyer",
+        "message": "What would make you hesitant to try a new AI product?"
+      }
+    }
+  }'
+```
+
+### List Available Personas
+
+```bash
+curl -X POST https://mcp.sociologicai.com/ \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "sociologic_list_personas",
+      "arguments": {
+        "visibility": "public",
+        "per_page": 10
+      }
+    }
+  }'
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SOCIOLOGIC_API_URL` | Backend API URL | `https://www.sociologic.ai` |
+
+### wrangler.toml
+
+```toml
+[vars]
+SOCIOLOGIC_API_URL = "https://www.sociologic.ai"
+```
+
+## Security
+
+- **API keys** are passed via `X-API-Key` header or `Authorization: Bearer` header
+- **Request size** limited to 1MB to prevent DoS
+- **Input validation** via Zod schemas on all tool parameters
+- **No data stored** on edge - all data flows through to the SocioLogic API
+
+### Rate Limiting
+
+For production deployments, we recommend enabling Cloudflare's rate limiting:
+
+1. Go to Cloudflare Dashboard > Security > WAF > Rate limiting rules
+2. Create a rule: 100 requests per 10 seconds per IP
+
+## Architecture
+
+```
+┌─────────────────┐      ┌─────────────────────┐      ┌─────────────────┐
+│                 │      │                     │      │                 │
+│   MCP Client    │─────▶│  Cloudflare Worker  │─────▶│  SocioLogic API │
+│  (Claude, etc)  │      │   (This Server)     │      │                 │
+│                 │◀─────│                     │◀─────│                 │
+└─────────────────┘      └─────────────────────┘      └─────────────────┘
+        │                         │                          │
+        │    MCP Protocol         │    REST API              │
+        │    (JSON-RPC 2.0)       │    (HTTPS)               │
+        └─────────────────────────┴──────────────────────────┘
+```
+
+## Pricing
+
+| Operation | Credits |
+|-----------|---------|
+| List personas | 1 |
+| Get persona | 1 |
+| Create persona | 5-50 (by fidelity tier) |
+| Interview persona | 1 per message |
+| Campaign execution | Varies by size |
+
+**Free tier:** 100 credits on signup. See [sociologic.ai/pricing](https://sociologic.ai/pricing) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [SocioLogic Website](https://sociologic.ai)
+- [API Documentation](https://sociologic.ai/docs)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "signal-relay-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for SocioLogic Revenue Intelligence Platform - Interview synthetic personas, run research campaigns, and export insights",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SocioLogicAI/signal-relay.git"
+  },
+  "homepage": "https://sociologic.ai/signal-relay",
+  "bugs": {
+    "url": "https://github.com/SocioLogicAI/signal-relay/issues"
+  },
+  "author": {
+    "name": "SocioLogic",
+    "url": "https://sociologic.ai"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241230.0",
+    "typescript": "^5.7.2",
+    "wrangler": "^4.59.2"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sociologic",
+    "ai",
+    "personas",
+    "synthetic-users",
+    "market-research",
+    "customer-intelligence",
+    "revenue-intelligence",
+    "interviews",
+    "focus-groups"
+  ],
+  "license": "MIT"
+}

package/src/api-client.ts

@@ -0,0 +1,311 @@
+/**
+ * SocioLogic API Client
+ *
+ * Wraps all API calls to the SocioLogic REST API.
+ */
+
+export interface SocioLogicConfig {
+  apiUrl: string;
+  apiKey: string;
+}
+
+export interface ApiResponse<T> {
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  meta?: {
+    request_id: string;
+    credits_used?: number;
+    credits_remaining?: number;
+    [key: string]: unknown;
+  };
+}
+
+export class SocioLogicClient {
+  private apiUrl: string;
+  private apiKey: string;
+
+  constructor(config: SocioLogicConfig) {
+    this.apiUrl = config.apiUrl.replace(/\/$/, ""); // Remove trailing slash
+    this.apiKey = config.apiKey;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    queryParams?: Record<string, string | number | boolean | undefined>,
+    timeoutMs: number = 30000 // 30 second default timeout
+  ): Promise<ApiResponse<T>> {
+    const url = new URL(`${this.apiUrl}${path}`);
+
+    // Add query parameters
+    if (queryParams) {
+      Object.entries(queryParams).forEach(([key, value]) => {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+    };
+
+    // Setup timeout with AbortController
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    const options: RequestInit = {
+      method,
+      headers,
+      signal: controller.signal,
+    };
+
+    if (body && method !== "GET") {
+      options.body = JSON.stringify(body);
+    }
+
+    try {
+      const response = await fetch(url.toString(), options);
+
+      // Handle HTTP errors
+      if (!response.ok) {
+        // Try to parse error response body
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        let errorCode = `HTTP_${response.status}`;
+
+        try {
+          const errorBody = await response.json() as ApiResponse<unknown>;
+          if (errorBody.error) {
+            errorMessage = errorBody.error.message || errorMessage;
+            errorCode = errorBody.error.code || errorCode;
+          }
+        } catch {
+          // If JSON parsing fails, use the status text
+        }
+
+        return {
+          error: {
+            code: errorCode,
+            message: errorMessage,
+          },
+        };
+      }
+
+      const json = await response.json() as ApiResponse<T>;
+      return json;
+    } catch (error) {
+      // Handle timeout
+      if (error instanceof Error && error.name === "AbortError") {
+        return {
+          error: {
+            code: "TIMEOUT",
+            message: `Request timed out after ${timeoutMs}ms`,
+          },
+        };
+      }
+
+      // Handle other network errors
+      return {
+        error: {
+          code: "NETWORK_ERROR",
+          message: error instanceof Error ? error.message : "Network request failed",
+        },
+      };
+    } finally {
+      // Always clear timeout to prevent memory leaks
+      clearTimeout(timeoutId);
+    }
+  }
+
+  // ============================================
+  // PERSONAS
+  // ============================================
+
+  async listPersonas(params: {
+    visibility?: "public" | "private" | "all";
+    category?: string;
+    fidelity_tier?: string;
+    search?: string;
+    page?: number;
+    per_page?: number;
+  }) {
+    return this.request<{
+      data: unknown[];
+      pagination: {
+        total: number;
+        page: number;
+        per_page: number;
+        total_pages: number;
+      };
+    }>("GET", "/api/v1/personas", undefined, params);
+  }
+
+  async getPersona(slug: string) {
+    return this.request<unknown>("GET", `/api/v1/personas/${encodeURIComponent(slug)}`);
+  }
+
+  async createPersona(params: {
+    description: string;
+    fidelity_tier?: string;
+  }) {
+    return this.request<unknown>("POST", "/api/v1/personas", params);
+  }
+
+  async interviewPersona(
+    slug: string,
+    params: {
+      message: string;
+      conversation_id?: string;
+      include_memory?: boolean;
+      save_conversation?: boolean;
+      stream?: boolean;
+    }
+  ) {
+    // Note: Streaming is handled differently - this returns non-streaming response
+    return this.request<{
+      response: string;
+      conversation_id: string;
+      persona: {
+        id: string;
+        slug: string;
+        name: string;
+      };
+      memory_context_used: boolean;
+    }>("POST", `/api/v1/personas/${encodeURIComponent(slug)}/interview`, {
+      ...params,
+      stream: false, // Force non-streaming for MCP
+    });
+  }
+
+  async getPersonaMemories(
+    slug: string,
+    params: {
+      query?: string;
+      limit?: number;
+    }
+  ) {
+    return this.request<{
+      memories: Array<{
+        id: string;
+        content: string;
+        similarity?: number;
+        created_at: string;
+      }>;
+    }>("GET", `/api/v1/personas/${encodeURIComponent(slug)}/memories`, undefined, params);
+  }
+
+  // ============================================
+  // CAMPAIGNS
+  // ============================================
+
+  async listCampaigns(params: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+    include_interviews?: boolean;
+  }) {
+    return this.request<unknown[]>("GET", "/api/v1/campaigns", undefined, params);
+  }
+
+  async getCampaign(id: string) {
+    return this.request<unknown>("GET", `/api/v1/campaigns/${encodeURIComponent(id)}`);
+  }
+
+  async createCampaign(params: {
+    name: string;
+    description?: string;
+    questions: Array<{
+      id: string;
+      text: string;
+      type?: string;
+      required?: boolean;
+      options?: string[];
+    }>;
+    persona_brief?: string;
+    persona_count?: number;
+    fidelity_tier?: string;
+    existing_persona_ids?: string[];
+    focus_group_ids?: string[];
+    research_context?: {
+      subjectName: string;
+      subjectDescription: string;
+      currentChallenge: string;
+      areasToExplore?: string[];
+      knownIssues?: string[];
+    };
+  }) {
+    return this.request<unknown>("POST", "/api/v1/campaigns", params);
+  }
+
+  async executeCampaign(id: string) {
+    return this.request<{
+      status: string;
+      message: string;
+    }>("POST", `/api/v1/campaigns/${encodeURIComponent(id)}/execute`);
+  }
+
+  async exportCampaign(id: string, format: "pdf" | "json" = "pdf") {
+    // For PDF, we return the URL rather than the binary
+    const encodedId = encodeURIComponent(id);
+    if (format === "pdf") {
+      return {
+        data: {
+          export_url: `${this.apiUrl}/api/v1/campaigns/${encodedId}/export?format=pdf`,
+          format: "pdf",
+          message: "Use the export_url to download the PDF report. Include your API key in the X-API-Key header.",
+        },
+        meta: { request_id: `mcp_${Date.now()}` },
+      };
+    }
+    return this.request<unknown>("GET", `/api/v1/campaigns/${encodedId}/export`, undefined, { format });
+  }
+
+  // ============================================
+  // FOCUS GROUPS
+  // ============================================
+
+  async listFocusGroups(params: {
+    limit?: number;
+    offset?: number;
+  }) {
+    return this.request<unknown[]>("GET", "/api/v1/focus-groups", undefined, params);
+  }
+
+  async getFocusGroup(id: string) {
+    return this.request<unknown>("GET", `/api/v1/focus-groups/${encodeURIComponent(id)}`);
+  }
+
+  async createFocusGroup(params: {
+    name: string;
+    description?: string;
+  }) {
+    return this.request<unknown>("POST", "/api/v1/focus-groups", params);
+  }
+
+  async addPersonasToFocusGroup(focusGroupId: string, personaIds: string[]) {
+    return this.request<unknown>(
+      "POST",
+      `/api/v1/focus-groups/${encodeURIComponent(focusGroupId)}/personas`,
+      { persona_ids: personaIds }
+    );
+  }
+
+  // ============================================
+  // AUTH / CREDITS
+  // ============================================
+
+  async getCreditsBalance() {
+    return this.request<{
+      valid: boolean;
+      credits_balance: number;
+      credits_used_total: number;
+      rate_limit_tier: string;
+    }>("GET", "/api/v1/auth/validate");
+  }
+}