convai-character-mcp 1.0.0

package/.env.example

@@ -0,0 +1 @@
+CONVAI_API_KEY=your_convai_api_key_here

package/README.md

@@ -0,0 +1,136 @@
+# Convai MCP Server
+
+Create and manage Convai AI characters directly from Claude — no dashboard needed.
+
+---
+
+## For New Users: Quick Setup Guide
+
+### Step 1 — Get your Convai API key
+
+1. Go to [convai.com](https://convai.com) and sign in (or create a free account)
+2. Open your dashboard and find **API Keys** in the settings/profile menu
+3. Copy your API key — you'll need it in Step 3
+
+---
+
+### Step 2 — Find your Claude Desktop config file
+
+**On Mac:**
+
+1. Open **Finder**
+2. Press `Cmd + Shift + G`
+3. Paste this path and press Enter:
+   ```
+   ~/Library/Application Support/Claude/
+   ```
+4. Open the file named `claude_desktop_config.json` in a text editor (TextEdit, VS Code, etc.)
+
+> If the file doesn't exist yet, create it with `{}` as the content first.
+
+---
+
+### Step 3 — Add the Convai MCP config
+
+Paste this into `claude_desktop_config.json`, replacing `your_api_key_here` with the key from Step 1:
+
+```json
+{
+  "mcpServers": {
+    "convai": {
+      "command": "npx",
+      "args": ["-y", "convai-mcp-server"],
+      "env": {
+        "CONVAI_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+> If the file already has other `mcpServers` entries, add the `"convai": { ... }` block inside the existing `mcpServers` object — don't replace the whole file.
+
+---
+
+### Step 4 — Restart Claude Desktop
+
+1. Fully **quit** Claude Desktop (right-click the dock icon → Quit, or use the menu bar → Quit)
+2. Reopen Claude Desktop from your Applications folder or Dock
+3. Open a new chat
+
+---
+
+### Step 5 — Test it!
+
+In a new Claude chat, type:
+
+```
+List my Convai characters
+```
+
+Claude will call the Convai API and show your characters. If you don't have any yet, it will say so — that means it's working!
+
+---
+
+## Troubleshooting
+
+**"I don't see any Convai tools"**
+- Make sure you fully quit and reopened Claude Desktop (not just closed the window)
+- Check that the JSON in your config file is valid — use [jsonlint.com](https://jsonlint.com) to verify
+- Make sure your API key has no extra spaces
+
+**"Error: CONVAI_API_KEY is not set"**
+- Double-check that `"CONVAI_API_KEY"` is inside the `"env"` block in your config
+
+**"API error 401 / Unauthorized"**
+- Your API key may be incorrect or expired — regenerate it from the Convai dashboard
+
+---
+
+## All Available Tools
+
+| Tool | What it does | Required inputs |
+|------|-------------|-----------------|
+| `create_character` | Create a new AI character | `name`, `backstory` |
+| `get_character` | Get full details of a character | `character_id` |
+| `update_character` | Update name, backstory, or voice | `character_id` |
+| `list_characters` | List all your characters | _(none)_ |
+| `delete_character` | Delete a character | `character_id` |
+| `add_knowledge` | Add knowledge to a character | `character_id`, `knowledge_text` |
+| `list_knowledge` | List a character's knowledge entries | `character_id` |
+| `set_narrative_design` | Set role, emotional range, speaking style | `character_id` |
+| `clone_character` | Clone a character with a new name/backstory | `source_character_id`, `new_name` |
+
+---
+
+## Example Prompts
+
+Once connected, just describe what you want — Claude picks the right tool:
+
+> "Create a wise elven librarian named Sylara with a female voice who speaks in archaic formal english"
+
+> "Add knowledge about the Forbidden Archives to Sylara"
+
+> "Give Sylara a narrative design as a Guide NPC with a calm to mysterious emotional range"
+
+> "Clone Sylara into a new character called The Shadow Librarian with a darker, more paranoid personality"
+
+> "List all my characters"
+
+> "Delete the character with ID abc123"
+
+---
+
+## Prerequisites (for local/dev setup)
+
+- Node.js 18+
+- A Convai account and API key
+
+```bash
+git clone https://github.com/noyonika25/convaimcp
+cd convaimcp
+npm install
+cp .env.example .env
+# Edit .env and add your CONVAI_API_KEY
+node index.js
+```

package/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import {
+  characterToolDefinitions,
+  handleCharacterTool,
+} from "./tools/character.js";
+import {
+  knowledgeToolDefinitions,
+  handleKnowledgeTool,
+} from "./tools/knowledge.js";
+import {
+  narrativeToolDefinitions,
+  handleNarrativeTool,
+} from "./tools/narrative.js";
+
+const allTools = [
+  ...characterToolDefinitions,
+  ...knowledgeToolDefinitions,
+  ...narrativeToolDefinitions,
+];
+
+const server = new Server(
+  { name: "convai-mcp-server", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: allTools };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    // Route by tool name prefix / ownership
+    if (name.startsWith("create_character") || name === "get_character" ||
+        name === "update_character" || name === "list_characters" ||
+        name === "delete_character") {
+      return await handleCharacterTool(name, args ?? {});
+    }
+
+    if (name === "add_knowledge" || name === "list_knowledge") {
+      return await handleKnowledgeTool(name, args ?? {});
+    }
+
+    if (name === "set_narrative_design" || name === "clone_character") {
+      return await handleNarrativeTool(name, args ?? {});
+    }
+
+    return {
+      content: [{ type: "text", text: `❌ Unknown tool: ${name}` }],
+      isError: true,
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `❌ Error in ${name}: ${err.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("✅ Convai MCP server running");

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "convai-character-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Convai — create and manage AI characters from Claude",
+  "type": "module",
+  "main": "index.js",
+  "bin": { "convai-character-mcp": "./index.js" },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.0.0"
+  }
+}

package/tools/character.js

@@ -0,0 +1,225 @@
+import { convaiRequest } from "../utils/api.js";
+
+export const characterToolDefinitions = [
+  {
+    name: "create_character",
+    description:
+      "Create a new Convai AI character with a name, backstory, voice type, and language.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Character name (required)" },
+        backstory: {
+          type: "string",
+          description: "Character backstory / personality description (required)",
+        },
+        voice_type: {
+          type: "string",
+          enum: ["MALE", "FEMALE"],
+          description: "Voice type — MALE or FEMALE (default: FEMALE)",
+        },
+        language: {
+          type: "string",
+          description: 'Language code (default: "en-US")',
+        },
+      },
+      required: ["name", "backstory"],
+    },
+  },
+  {
+    name: "get_character",
+    description: "Retrieve full details of a Convai character by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: { type: "string", description: "The character ID" },
+      },
+      required: ["character_id"],
+    },
+  },
+  {
+    name: "update_character",
+    description:
+      "Update an existing Convai character's name, backstory, or voice type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: {
+          type: "string",
+          description: "The character ID (required)",
+        },
+        name: { type: "string", description: "New character name (optional)" },
+        backstory: {
+          type: "string",
+          description: "New backstory (optional)",
+        },
+        voice_type: {
+          type: "string",
+          enum: ["MALE", "FEMALE"],
+          description: "New voice type (optional)",
+        },
+      },
+      required: ["character_id"],
+    },
+  },
+  {
+    name: "list_characters",
+    description: "List all Convai characters in your account.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "delete_character",
+    description: "Delete a Convai character by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: {
+          type: "string",
+          description: "The character ID to delete",
+        },
+      },
+      required: ["character_id"],
+    },
+  },
+];
+
+export async function handleCharacterTool(name, args) {
+  switch (name) {
+    case "create_character":
+      return await createCharacter(args);
+    case "get_character":
+      return await getCharacter(args);
+    case "update_character":
+      return await updateCharacter(args);
+    case "list_characters":
+      return await listCharacters();
+    case "delete_character":
+      return await deleteCharacter(args);
+    default:
+      throw new Error(`Unknown character tool: ${name}`);
+  }
+}
+
+async function createCharacter({ name, backstory, voice_type = "FEMALE", language = "en-US" }) {
+  // Convai returns: { charID, status } — exact shape may vary
+  const data = await convaiRequest("POST", "/v1/character/create", {
+    charName: name,
+    backstory,
+    voiceType: voice_type,
+    languageCode: language,
+  });
+
+  const charId = data?.charID ?? data?.character_id ?? data?.id ?? "unknown";
+  const status = data?.status ?? "created";
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `✅ Character created successfully!\n\n**Name:** ${name}\n**ID:** ${charId}\n**Voice:** ${voice_type}\n**Language:** ${language}\n**Status:** ${status}\n\n**Next steps:**\n- Use \`add_knowledge\` to give ${name} specialized knowledge\n- Use \`set_narrative_design\` to define their role and speaking style\n- Use \`get_character\` to review the full character profile`,
+      },
+    ],
+  };
+}
+
+async function getCharacter({ character_id }) {
+  // Convai returns: full character object — exact shape may vary
+  const data = await convaiRequest("GET", `/v1/character/get?charID=${character_id}`);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Character Details (ID: ${character_id})**\n\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``,
+      },
+    ],
+  };
+}
+
+async function updateCharacter({ character_id, name, backstory, voice_type }) {
+  const updates = { charID: character_id };
+  const updated = [];
+
+  if (name !== undefined) {
+    updates.charName = name;
+    updated.push(`name → "${name}"`);
+  }
+  if (backstory !== undefined) {
+    updates.backstory = backstory;
+    updated.push("backstory");
+  }
+  if (voice_type !== undefined) {
+    updates.voiceType = voice_type;
+    updated.push(`voice_type → ${voice_type}`);
+  }
+
+  if (updated.length === 0) {
+    return {
+      content: [{ type: "text", text: "⚠️ No fields provided to update." }],
+    };
+  }
+
+  // Convai returns: { status } or similar — exact shape may vary
+  const data = await convaiRequest("POST", "/v1/character/update", updates);
+
+  const status = data?.status ?? "updated";
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `✅ Character updated (ID: ${character_id})\n\n**Updated:** ${updated.join(", ")}\n**Status:** ${status}`,
+      },
+    ],
+  };
+}
+
+async function listCharacters() {
+  // Convai returns: array or object containing characters — exact shape may vary
+  const data = await convaiRequest("GET", "/v1/characters");
+
+  const characters = Array.isArray(data)
+    ? data
+    : data?.characters ?? data?.data ?? [];
+
+  if (characters.length === 0) {
+    return {
+      content: [{ type: "text", text: "No characters found in your account." }],
+    };
+  }
+
+  const list = characters
+    .map((c, i) => {
+      const id = c?.charID ?? c?.character_id ?? c?.id ?? "unknown";
+      const name = c?.charName ?? c?.name ?? "Unnamed";
+      const voice = c?.voiceType ?? c?.voice_type ?? "—";
+      return `${i + 1}. **${name}** — ID: \`${id}\` | Voice: ${voice}`;
+    })
+    .join("\n");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Your Convai Characters (${characters.length} total)**\n\n${list}`,
+      },
+    ],
+  };
+}
+
+async function deleteCharacter({ character_id }) {
+  // Convai returns: empty or { status } — exact shape may vary
+  await convaiRequest("DELETE", `/v1/character/${character_id}`);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `✅ Character \`${character_id}\` has been deleted.`,
+      },
+    ],
+  };
+}

package/tools/knowledge.js

@@ -0,0 +1,132 @@
+import { convaiRequest } from "../utils/api.js";
+
+export const knowledgeToolDefinitions = [
+  {
+    name: "add_knowledge",
+    description:
+      "Add a knowledge entry to a Convai character's knowledge bank.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: {
+          type: "string",
+          description: "The character ID to add knowledge to (required)",
+        },
+        knowledge_text: {
+          type: "string",
+          description: "The knowledge content to add (required)",
+        },
+        knowledge_title: {
+          type: "string",
+          description: "A short title for this knowledge entry (optional)",
+        },
+      },
+      required: ["character_id", "knowledge_text"],
+    },
+  },
+  {
+    name: "list_knowledge",
+    description: "List all knowledge entries for a Convai character.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: {
+          type: "string",
+          description: "The character ID to list knowledge for (required)",
+        },
+      },
+      required: ["character_id"],
+    },
+  },
+];
+
+export async function handleKnowledgeTool(name, args) {
+  switch (name) {
+    case "add_knowledge":
+      return await addKnowledge(args);
+    case "list_knowledge":
+      return await listKnowledge(args);
+    default:
+      throw new Error(`Unknown knowledge tool: ${name}`);
+  }
+}
+
+async function addKnowledge({ character_id, knowledge_text, knowledge_title }) {
+  const body = {
+    charID: character_id,
+    knowledge: knowledge_text,
+  };
+  if (knowledge_title !== undefined) {
+    body.title = knowledge_title;
+  }
+
+  // Convai returns: { status, knowledgeID } or similar — exact shape may vary
+  const data = await convaiRequest("POST", "/v1/knowledge/upload", body);
+
+  const status = data?.status ?? "uploaded";
+  const knowledgeId = data?.knowledgeID ?? data?.knowledge_id ?? data?.id;
+
+  const preview =
+    knowledge_text.length > 120
+      ? knowledge_text.slice(0, 120) + "…"
+      : knowledge_text;
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: [
+          `✅ Knowledge added to character \`${character_id}\``,
+          knowledge_title ? `**Title:** ${knowledge_title}` : null,
+          knowledgeId ? `**Knowledge ID:** ${knowledgeId}` : null,
+          `**Status:** ${status}`,
+          `**Preview:** "${preview}"`,
+        ]
+          .filter(Boolean)
+          .join("\n"),
+      },
+    ],
+  };
+}
+
+async function listKnowledge({ character_id }) {
+  // Convai returns: array or object of knowledge entries — exact shape may vary
+  const data = await convaiRequest(
+    "GET",
+    `/v1/knowledge/list?charID=${character_id}`
+  );
+
+  const entries = Array.isArray(data)
+    ? data
+    : data?.knowledge ?? data?.entries ?? data?.data ?? [];
+
+  if (entries.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No knowledge entries found for character \`${character_id}\`.`,
+        },
+      ],
+    };
+  }
+
+  const list = entries
+    .map((e, i) => {
+      const id = e?.knowledgeID ?? e?.knowledge_id ?? e?.id ?? "unknown";
+      const title = e?.title ?? e?.name ?? "Untitled";
+      const preview = (e?.knowledge ?? e?.text ?? e?.content ?? "")
+        .slice(0, 80);
+      return `${i + 1}. **${title}** (ID: \`${id}\`)\n   ${preview}${preview.length === 80 ? "…" : ""}`;
+    })
+    .join("\n\n");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Knowledge entries for character \`${character_id}\` (${entries.length} total)**\n\n${list}`,
+      },
+    ],
+  };
+}

package/tools/narrative.js

@@ -0,0 +1,175 @@
+import { convaiRequest } from "../utils/api.js";
+
+export const narrativeToolDefinitions = [
+  {
+    name: "set_narrative_design",
+    description:
+      "Set the narrative design of a Convai character — their role classification, emotional range, speaking style, and key topics of expertise. This appends a structured addendum to the character's backstory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        character_id: {
+          type: "string",
+          description: "The character ID (required)",
+        },
+        classification: {
+          type: "string",
+          description: 'Character role, e.g. "NPC", "Guide", "Antagonist"',
+        },
+        emotional_range: {
+          type: "string",
+          description: 'Emotional range, e.g. "calm to aggressive"',
+        },
+        speaking_style: {
+          type: "string",
+          description: 'Speaking style, e.g. "formal", "casual", "archaic"',
+        },
+        key_topics: {
+          type: "array",
+          items: { type: "string" },
+          description: "Topics this character is an expert in",
+        },
+      },
+      required: ["character_id"],
+    },
+  },
+  {
+    name: "clone_character",
+    description:
+      "Clone an existing Convai character into a new character with the same voice settings, optionally overriding the backstory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_character_id: {
+          type: "string",
+          description: "ID of the character to clone (required)",
+        },
+        new_name: {
+          type: "string",
+          description: "Name for the new character (required)",
+        },
+        backstory_override: {
+          type: "string",
+          description:
+            "If provided, use this backstory instead of the source character's (optional)",
+        },
+      },
+      required: ["source_character_id", "new_name"],
+    },
+  },
+];
+
+export async function handleNarrativeTool(name, args) {
+  switch (name) {
+    case "set_narrative_design":
+      return await setNarrativeDesign(args);
+    case "clone_character":
+      return await cloneCharacter(args);
+    default:
+      throw new Error(`Unknown narrative tool: ${name}`);
+  }
+}
+
+async function setNarrativeDesign({
+  character_id,
+  classification,
+  emotional_range,
+  speaking_style,
+  key_topics,
+}) {
+  // Fetch existing character to preserve current backstory
+  // Convai returns: full character object — exact shape may vary
+  const existing = await convaiRequest(
+    "GET",
+    `/v1/character/get?charID=${character_id}`
+  );
+
+  const currentBackstory =
+    existing?.backstory ?? existing?.charBackstory ?? existing?.description ?? "";
+
+  // Build the narrative addendum
+  const addendumLines = ["--- Narrative Design ---"];
+  if (classification) addendumLines.push(`Role: ${classification}`);
+  if (emotional_range) addendumLines.push(`Emotional range: ${emotional_range}`);
+  if (speaking_style) addendumLines.push(`Speaking style: ${speaking_style}`);
+  if (key_topics && key_topics.length > 0) {
+    addendumLines.push(`Key expertise: ${key_topics.join(", ")}`);
+  }
+  addendumLines.push("--- End Narrative Design ---");
+
+  const addendum = addendumLines.join("\n");
+
+  // Remove any previous narrative addendum before appending new one
+  const backstoryWithoutOldAddendum = currentBackstory
+    .replace(/\n?--- Narrative Design ---[\s\S]*?--- End Narrative Design ---/g, "")
+    .trim();
+
+  const newBackstory = backstoryWithoutOldAddendum
+    ? `${backstoryWithoutOldAddendum}\n\n${addendum}`
+    : addendum;
+
+  // Convai returns: { status } or similar — exact shape may vary
+  const data = await convaiRequest("POST", "/v1/character/update", {
+    charID: character_id,
+    backstory: newBackstory,
+  });
+
+  const status = data?.status ?? "updated";
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `✅ Narrative design applied to character \`${character_id}\`\n**Status:** ${status}\n\n**Addendum added to backstory:**\n\`\`\`\n${addendum}\n\`\`\``,
+      },
+    ],
+  };
+}
+
+async function cloneCharacter({ source_character_id, new_name, backstory_override }) {
+  // Fetch source character
+  // Convai returns: full character object — exact shape may vary
+  const source = await convaiRequest(
+    "GET",
+    `/v1/character/get?charID=${source_character_id}`
+  );
+
+  const voiceType =
+    source?.voiceType ?? source?.voice_type ?? "FEMALE";
+  const languageCode =
+    source?.languageCode ?? source?.language_code ?? source?.language ?? "en-US";
+  const backstory =
+    backstory_override ??
+    source?.backstory ??
+    source?.charBackstory ??
+    source?.description ??
+    "";
+
+  // Create the new character
+  // Convai returns: { charID, status } — exact shape may vary
+  const newChar = await convaiRequest("POST", "/v1/character/create", {
+    charName: new_name,
+    backstory,
+    voiceType,
+    languageCode,
+  });
+
+  const newCharId = newChar?.charID ?? newChar?.character_id ?? newChar?.id ?? "unknown";
+  const status = newChar?.status ?? "created";
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: [
+          `✅ Character cloned successfully!`,
+          `**Source:** \`${source_character_id}\``,
+          `**New character:** ${new_name} (ID: \`${newCharId}\`)`,
+          `**Voice:** ${voiceType} | **Language:** ${languageCode}`,
+          `**Backstory:** ${backstory_override ? "custom override applied" : "copied from source"}`,
+          `**Status:** ${status}`,
+        ].join("\n"),
+      },
+    ],
+  };
+}

package/utils/api.js

@@ -0,0 +1,52 @@
+import "dotenv/config";
+
+/**
+ * Reusable Convai API client.
+ * @param {string} method - HTTP method (GET, POST, DELETE, etc.)
+ * @param {string} path   - API path, e.g. "/v1/character/create"
+ * @param {object} [body] - Optional request body (will be JSON-encoded)
+ * @returns {Promise<any>} Parsed JSON response
+ */
+export async function convaiRequest(method, path, body) {
+  const apiKey = process.env.CONVAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("CONVAI_API_KEY is not set in environment variables");
+  }
+
+  const url = `https://api.convai.com${path}`;
+  const options = {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "CONVAI-API-KEY": apiKey,
+    },
+  };
+
+  if (body !== undefined) {
+    options.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, options);
+
+  if (!res.ok) {
+    let errorBody = "";
+    try {
+      errorBody = await res.text();
+    } catch {
+      // ignore
+    }
+    throw new Error(
+      `Convai API error ${res.status} ${res.statusText}: ${errorBody}`
+    );
+  }
+
+  // Some endpoints may return empty body (e.g. DELETE)
+  const text = await res.text();
+  if (!text) return {};
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}