taskover-mcp 1.0.0

package/README.md

@@ -0,0 +1,26 @@
+# taskover-mcp
+
+MCP server for [TaskOver.gg](https://taskover.gg) - connect Claude Desktop, Claude Code, Cursor, or Windsurf to your game dev project data.
+
+## Setup
+
+1. Get your API key from taskover.gg -> Settings -> Security
+2. Add to your AI host config:
+
+```json
+{
+  "mcpServers": {
+    "taskover": {
+      "command": "npx",
+      "args": ["-y", "taskover-mcp@latest"],
+      "env": {
+        "TASKOVER_API_KEY": "tok_paste-your-key-here"
+      }
+    }
+  }
+}
+```
+
+3. Restart your AI host
+
+Your API key is stored in plaintext in the config file. For better security, use Bridge Mode when available.

package/cloud-adapter.js

@@ -0,0 +1,222 @@
+// mcp-server/cloud-adapter.js
+// SECURITY: This module is the cloud-mode replacement for direct data-store access.
+// It forwards allowed methods to api.taskover.gg/api/rpc with the user's API key.
+// The server is the final authority on auth, scope, ownership, and rate limits.
+// Client-side allowlist is defense-in-depth only.
+
+const API_BASE = "https://api.taskover.gg";
+const REQUEST_TIMEOUT_MS = 15000;
+const MAX_REQUEST_BYTES = 1 * 1024 * 1024;   // 1 MB
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;   // 5 MB
+
+// SECURITY: Default is DENY. New methods must be explicitly added here after security review.
+// Delete operations are deferred past beta -- users must delete via the web UI.
+// Settings, admin, billing, team, import/export are permanently blocked.
+// REVISED per M0 matrix (33 read methods). Removed: getProject, getTask, getSystem,
+// getMilestone, getLastSession, getBlueprintGraphs (DEFERRED), searchProject,
+// getActivityFeed (no MCP tool). Singular get methods don't exist in RPC.
+const MCP_ALLOWED_READS = new Set([
+  "listProjects",
+  "getTasks",
+  "getBugs",
+  "getSystems",
+  "getMilestones",
+  "getSessions",
+  "getChangelog",
+  "getDecisions",
+  "getBlueprints",
+  "getNotes",
+  "getBuildErrors",
+  "getAssets",
+  "getOptimizeItems",
+  "getPerfBudget",
+  "getLevels",
+  "getMarketingItems",
+  "getDialogues",
+  "getSounds", "getControls",
+  "getRefs",
+  "getPlugins",
+  "getShipChecked",
+  "getIterations",
+  "getPlaytests",
+  "getOpenQuestions",
+  "getWikiPages",
+  "getStories", "getScenes", "getSceneContent", "getStoryBible",
+  "search",
+  "dashboard", "contextExport",
+]);
+
+// REVISED per M0 matrix (52 write methods). Removed: updateBug (no MCP tool),
+// setBlueprintGraph, addGraphNodes (DEFERRED ANOMALY-1), addBoardColumn (DEFERRED ANOMALY-2),
+// updateStoryCharacter, updateSceneContent (DEFERRED ANOMALY-3).
+const MCP_ALLOWED_WRITES = new Set([
+  "addTask", "updateTask", "moveTask", "addTaskComment",
+  "addBug", "fixBug",
+  "logSession",
+  "addChangelog",
+  "logDecision",
+  "addSystem", "updateSystem",
+  "addBlueprint", "updateBlueprint",
+  "addNote",
+  "addBuildError", "fixBuildError",
+  "addOptimizeItem", "updateOptimizeItem",
+  "addPerfBudget",
+  "addLevel", "updateLevel", "addActor", "removeActor",
+  "addPlugin", "updatePlugin",
+  "addPlaytest",
+  "addMilestone", "updateMilestone",
+  "addIteration",
+  "addDialogue", "updateDialogue",
+  "addSound", "updateSound",
+  "addControl", "updateControl",
+  "addAsset", "updateAsset",
+  "addRef",
+  "addMarketingItem", "updateMarketingItem",
+  "addWikiPage", "updateWikiPage",
+  "addOpenQuestion", "toggleQuestion",
+  "toggleShipCheck",
+  "logBackup",
+  "addStory", "updateStory",
+  "addScene", "updateScene",
+  "updateStoryBible",
+  "addStoryCharacter",
+]);
+
+// SECURITY: Methods that are NEVER allowed through MCP, regardless of future changes.
+// Commented for documentation -- they are blocked by not being in the allow sets above.
+// addProject, deleteProject, updateProject
+// generateApiKey, revokeApiKey
+// any user/auth/team/billing/subscription methods
+// exportData, importData
+// any settings methods
+// any friend/social methods
+// loadAll (returns entire user dataset -- too broad)
+// deleteSystem, deletePlugin, deleteScene (delete ops deferred past beta)
+// DEFERRED per M0: getBlueprintGraphs, setBlueprintGraph, addGraphNodes (ANOMALY-1: ownership)
+// DEFERRED per M0: addBoardColumn (ANOMALY-2: no RPC method)
+// DEFERRED per M0: updateStoryCharacter, updateSceneContent (ANOMALY-3: arg/ownership)
+// REMOVED (no MCP tool): updateBug, getProject, getTask, getSystem, getMilestone,
+//   getLastSession, searchProject, getActivityFeed
+
+const MCP_ALLOWED_METHODS = new Set([...MCP_ALLOWED_READS, ...MCP_ALLOWED_WRITES]);
+
+let _apiKey = null;
+
+function init(apiKey) {
+  _apiKey = apiKey;
+}
+
+function isAllowed(method) {
+  return MCP_ALLOWED_METHODS.has(method);
+}
+
+function isWrite(method) {
+  return MCP_ALLOWED_WRITES.has(method);
+}
+
+async function callRpc(method, args) {
+  if (!_apiKey) throw new Error("Cloud adapter not initialized -- no API key");
+  if (!isAllowed(method)) throw new Error(`Method "${method}" is not allowed through MCP`);
+
+  const body = JSON.stringify({ method, args: args || [] });
+  if (Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
+    throw new Error("Request too large (max 1 MB)");
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${API_BASE}/api/rpc`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${_apiKey}`,
+      },
+      body,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (res.status === 401) {
+      throw new Error("AUTH_FAILED");
+    }
+    if (res.status === 429) {
+      const retryAfter = res.headers.get("retry-after") || "60";
+      throw new Error(`RATE_LIMITED:${retryAfter}`);
+    }
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => "");
+      throw new Error(`Cloud API error ${res.status}: ${errBody.slice(0, 200)}`);
+    }
+
+    // SECURITY: Enforce response size limit using byte-accurate check.
+    // text.length counts UTF-16 code units, not bytes. Multi-byte content
+    // (emoji, CJK, etc.) would undercount. Buffer.byteLength is correct.
+    const text = await res.text();
+    if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+      throw new Error("Response too large (max 5 MB)");
+    }
+
+    const parsed = JSON.parse(text);
+    return parsed.result !== undefined ? parsed.result : parsed;
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === "AbortError") {
+      throw new Error("Cloud API request timed out (15s)");
+    }
+    throw err;
+  }
+}
+
+async function validateKey() {
+  // SECURITY: Validate auth via dedicated lightweight endpoint.
+  // /api/auth/validate confirms the key is valid and returns userId + displayName.
+  // Does NOT load business data (unlike listProjects which fetches all projects).
+  // /api/health is unauthenticated and must NEVER be used for key validation.
+  if (!_apiKey) return { valid: false, error: "No API key configured" };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${API_BASE}/api/auth/validate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${_apiKey}`,
+      },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (res.status === 401) {
+      return { valid: false, error: "API key is invalid or expired. Generate a new key at taskover.gg -> Settings -> Security." };
+    }
+    if (!res.ok) {
+      return { valid: false, error: `Unexpected response from api.taskover.gg (HTTP ${res.status})` };
+    }
+
+    const data = await res.json();
+    return { valid: true, displayName: data.displayName || "user" };
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === "AbortError") {
+      return { valid: false, error: "Cannot reach api.taskover.gg (timeout). Check your internet connection." };
+    }
+    return { valid: false, error: `Cannot reach api.taskover.gg: ${err.message}` };
+  }
+}
+
+module.exports = {
+  init,
+  isAllowed,
+  isWrite,
+  callRpc,
+  validateKey,
+  MCP_ALLOWED_METHODS,
+  MCP_ALLOWED_READS,
+  MCP_ALLOWED_WRITES,
+};