personascope-mcp 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# PersonaScope MCP Server
+
+Access PersonaScope personality data from any MCP-compatible AI assistant (Claude Code, Cursor, Windsurf, etc.).
+
+## Installation
+
+Add to your Claude Code configuration (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "personascope": {
+      "command": "npx",
+      "args": ["-y", "personascope-mcp"]
+    }
+  }
+}
+```
+
+Or run locally:
+```bash
+cd mcp-server
+npm install
+node index.js
+```
+
+## Available Tools
+
+### `lookup_personality_type`
+Look up any of the 27 SBTI personality types by code.
+```
+Input: { "code": "SLAY" }
+Output: Full type data — archetype, tagline, description, strengths, blind spots
+```
+
+### `list_personality_types`
+List all 27 SBTI types with their codes and archetypes.
+
+### `explain_trait`
+Explain a Big Five personality trait and what scores mean.
+```
+Input: { "trait": "openness" }
+Output: Trait description, high/low descriptors, example behaviors
+```
+
+### `recommend_module`
+Get a PersonaScope module recommendation based on a goal.
+```
+Input: { "goal": "career clarity" }
+Output: Recommended module with description and link
+```
+
+## Configuration
+
+The server connects to `https://persona.sig.ai` by default. Override with:
+```bash
+PERSONASCOPE_API_URL=http://localhost:3001 node index.js
+```
+
+## Data Source
+
+All data comes from the PersonaScope Public API:
+- `GET /api/public/types` — SBTI personality types
+- `GET /api/public/traits` — Big Five traits
+- API docs: https://persona.sig.ai/openapi.json

package/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_BASE = process.env.PERSONASCOPE_API_URL || "https://persona.sig.ai";
+
+async function fetchJSON(path) {
+  const res = await fetch(`${API_BASE}${path}`);
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
+// Module catalog for recommendations
+const MODULES = [
+  { name: "Personality Assessment", url: "/modules/personality.html", keywords: ["personality", "big five", "traits", "mbti", "assessment", "test"], description: "50-question Big Five personality assessment with MBTI-style mapping. The foundation for all other modules." },
+  { name: "Talent Deep Dive", url: "/modules/talent.html", keywords: ["talent", "strengths", "skills", "career", "abilities", "working style"], description: "AI-guided conversation to identify your transferable strengths and natural working style." },
+  { name: "Dream Job Finder", url: "/modules/dream-job.html", keywords: ["job", "career", "work", "employment", "profession", "role"], description: "Match your personality to career environments where you'll thrive." },
+  { name: "Soul Mate Blueprint", url: "/modules/soul-mate.html", keywords: ["relationship", "love", "partner", "dating", "compatibility", "attachment"], description: "Explore your relationship patterns and compatibility needs." },
+  { name: "Dream Home Finder", url: "/modules/dream-home.html", keywords: ["home", "living", "house", "apartment", "space", "environment"], description: "Define your ideal living environment based on your nervous system needs." },
+  { name: "Dream Vacation Planner", url: "/modules/dream-vacation.html", keywords: ["vacation", "travel", "trip", "holiday", "adventure", "destination"], description: "Design travel experiences that restore your specific energy type." },
+  { name: "5/10 Year Vision", url: "/modules/vision.html", keywords: ["vision", "future", "goals", "planning", "life", "purpose", "direction"], description: "Convert ambition into a coherent life strategy aligned with your personality." },
+  { name: "SBTI Test", url: "/modules/sbti.html", keywords: ["sbti", "type", "archetype", "personality type", "which type"], description: "27 unique personality archetypes. Fun, shareable, uncomfortably accurate." },
+  { name: "Quick Tests", url: "/modules/quick-tests.html", keywords: ["quick", "eq", "love language", "attachment", "stress", "communication", "conflict", "energy", "decision"], description: "10 short personality quizzes, 3-5 minutes each." },
+  { name: "Compare Types", url: "/modules/compare.html", keywords: ["compare", "compatibility", "friend", "couple", "match"], description: "Compare personality profiles between two people." },
+  { name: "Teams", url: "/modules/teams.html", keywords: ["team", "group", "organization", "company", "workplace"], description: "Map your team's collective personality landscape." },
+];
+
+const server = new McpServer({
+  name: "personascope",
+  version: "1.0.0",
+});
+
+// Tool: lookup_personality_type
+server.tool(
+  "lookup_personality_type",
+  "Look up a PersonaScope SBTI personality type by its 4-letter code (e.g. SLAY, BOSS, VIBE). Returns archetype name, tagline, description, strengths, and blind spots.",
+  { code: z.string().describe("4-letter SBTI type code (e.g. SLAY, BOSS, LURK)") },
+  async ({ code }) => {
+    try {
+      const data = await fetchJSON(`/api/public/types/${code.toUpperCase()}`);
+      return {
+        content: [{
+          type: "text",
+          text: `**${data.code} — ${data.archetype}**\n"${data.tagline}"\n\n${data.description}\n\n**Strengths:** ${(data.strengths || []).join(", ")}\n\n**Blind spots:** ${(data.blindSpots || []).join(", ")}\n\nLearn more: ${API_BASE}/modules/types/${data.code.toLowerCase()}.html`,
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Type "${code}" not found. Use list_personality_types to see all 27 codes.` }] };
+    }
+  }
+);
+
+// Tool: list_personality_types
+server.tool(
+  "list_personality_types",
+  "List all 27 PersonaScope SBTI personality types with their codes and archetype names.",
+  {},
+  async () => {
+    const types = await fetchJSON("/api/public/types");
+    const list = types.map(t => `**${t.code}** — ${t.archetype}: "${t.tagline}"`).join("\n");
+    return {
+      content: [{
+        type: "text",
+        text: `# 27 SBTI Personality Types\n\n${list}\n\nTake the test: ${API_BASE}/modules/sbti.html`,
+      }],
+    };
+  }
+);
+
+// Tool: explain_trait
+server.tool(
+  "explain_trait",
+  "Explain a Big Five personality trait — what it measures, what high and low scores mean.",
+  { trait: z.string().describe("Trait name: openness, conscientiousness, extraversion, agreeableness, or emotional-stability") },
+  async ({ trait }) => {
+    try {
+      const data = await fetchJSON(`/api/public/traits/${trait}`);
+      return {
+        content: [{
+          type: "text",
+          text: `**${data.name}**\n${data.description}\n\n**High scores:** ${data.highLabel}\n${(data.highBehaviors || []).map(b => `- ${b}`).join("\n")}\n\n**Low scores:** ${data.lowLabel}\n${(data.lowBehaviors || []).map(b => `- ${b}`).join("\n")}\n\nMeasure yours: ${API_BASE}/modules/personality.html`,
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Trait "${trait}" not found. Available: openness, conscientiousness, extraversion, agreeableness, emotional-stability` }] };
+    }
+  }
+);
+
+// Tool: recommend_module
+server.tool(
+  "recommend_module",
+  "Recommend a PersonaScope module based on what the user wants to explore (e.g. 'career clarity', 'relationship patterns', 'ideal home').",
+  { goal: z.string().describe("What the user wants to explore or learn about") },
+  async ({ goal }) => {
+    const words = goal.toLowerCase().split(/\s+/);
+    const scored = MODULES.map(m => ({
+      ...m,
+      score: m.keywords.filter(k => words.some(w => w.includes(k) || k.includes(w))).length,
+    })).sort((a, b) => b.score - a.score);
+
+    const top = scored[0].score > 0 ? scored[0] : MODULES[0]; // Default to personality assessment
+    const alt = scored[1]?.score > 0 ? scored[1] : null;
+
+    let text = `**Recommended: ${top.name}**\n${top.description}\n${API_BASE}${top.url}`;
+    if (alt) text += `\n\n**Also relevant: ${alt.name}**\n${alt.description}\n${API_BASE}${alt.url}`;
+    text += `\n\nAll modules: ${API_BASE}`;
+
+    return { content: [{ type: "text", text }] };
+  }
+);
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "personascope-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for PersonaScope personality data — look up SBTI types, Big Five traits, and module recommendations",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "personascope-mcp": "index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "license": "MIT"
+}