slima-mcp 0.1.15 → 0.2.0

package/dist/index.js

@@ -95,16 +95,34 @@ var SlimaApiClient = class {
       headers: {
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
-        "User-Agent": "slima-mcp-server/0.1.0"
+        "User-Agent": `slima-mcp-server/${"0.2.0"}`
       },
       body: body ? JSON.stringify(body) : void 0
     });
+    this.handleUpgradeHint(response);
     if (!response.ok) {
       await this.handleErrorResponse(response);
     }
     const json = await response.json();
     return json.data;
   }
+  /**
+   * Surface the X-Slima-MCP-Upgrade-Hint header (if present) as a warn log.
+   * Deduped per (hint, baseUrl) to keep stderr quiet during long sessions.
+   * Defensive: mocked Response objects in tests may not carry a full Headers
+   * interface, so guard the access rather than hard-crashing the request.
+   */
+  loggedUpgradeHints = /* @__PURE__ */ new Set();
+  handleUpgradeHint(response) {
+    const hint = response?.headers?.get?.("X-Slima-MCP-Upgrade-Hint");
+    if (!hint) return;
+    const key = `${hint}::${this.baseUrl}`;
+    if (this.loggedUpgradeHints.has(key)) return;
+    this.loggedUpgradeHints.add(key);
+    this.logger.warn(
+      `[slima-mcp] ${hint} \u2014 upgrade options: npm install -g slima-mcp@latest, or change your Claude Desktop config to "npx -y slima-mcp@0".`
+    );
+  }
   /**
    * Handle error response
    */
@@ -409,10 +427,30 @@ function formatFileTree(files, indent = 0) {
 }
 
 // src/core/tools/books.ts
+function studioLabel(book) {
+  return book.bookType === "script" ? "\u{1F4DD} Script Studio" : "\u{1F4D6} Writing Studio";
+}
+function scriptStudioWriteRulesBlock(book) {
+  return `### \u{1F512} Write Restrictions (Script Studio)
+
+This book uses **structured schemas**. Via MCP you can:
+- \u2705 **Read** any file (series.json, *.character, *.scene, etc.)
+- \u2705 **Write / Edit / Delete** under \`.script_studio/planning/**/*\` only (free-form reference tree)
+- \u274C **Cannot modify** structured files (\`series.json\`, \`season.json\`, \`episode.json\`, \`*.character\`, \`*.location\`, \`*.scene\`, \`*.storyline\`, \`*.note\`)
+- \u274C **Cannot modify** \`.script_studio/planning/.initialized\` (frontend bootstrap sentinel)
+
+To add characters / scenes / storylines, use the Script Studio UI in the Slima app.
+
+For full per-book details, read the MCP resource: \`slima://books/${book.token}/schema\`.`;
+}
 function registerBookTools(server, client) {
   server.tool(
     "create_book",
-    "Create a new book in your Slima library",
+    `Create a new **Writing Studio** book in your Slima library.
+
+Only Writing Studio (free-form novels / long-form prose) books can be created via MCP.
+To create a **Script Studio** book (screenwriting with structured series/seasons/episodes/scenes),
+please use the Slima app UI \u2014 MCP does not yet support Script Studio scaffolding.`,
     {
       title: z.string().describe("Book title (required)"),
       author_name: z.string().optional().describe("Author name (optional)"),
@@ -468,7 +506,7 @@ You can now add files using create_file with book_token: ${book.token}`
         }
         const formatted = books.map((book) => {
           const words = book.totalWordCount?.toLocaleString() || "0";
-          return `- **${book.title}** (${book.token})
+          return `- **${book.title}** (${book.token}) \u2014 ${studioLabel(book)}
   Author: ${book.authorName || "N/A"} | Words: ${words}`;
         }).join("\n\n");
         return {
@@ -477,7 +515,9 @@ You can now add files using create_file with book_token: ${book.token}`
               type: "text",
               text: `Found ${books.length} book(s):
 
-${formatted}`
+${formatted}
+
+_\u{1F4DD} Script Studio books have write restrictions via MCP (see \`get_book\` or resource \`slima://books/{token}/schema\`). \u{1F4D6} Writing Studio books are fully writable._`
             }
           ]
         };
@@ -499,7 +539,7 @@ ${formatted}`
     async ({ book_token }) => {
       try {
         const book = await client.getBook(book_token);
-        const text = `# ${book.title}
+        const header = `# ${studioLabel(book)} \u2014 ${book.title}
 
 - **Token**: ${book.token}
 - **Author**: ${book.authorName || "N/A"}
@@ -510,6 +550,9 @@ ${formatted}`
 - **Reference Words**: ${book.referenceWordCount?.toLocaleString() || "0"}
 - **Created**: ${book.createdAt}
 - **Updated**: ${book.updatedAt}`;
+        const text = book.bookType === "script" ? `${header}
+
+${scriptStudioWriteRulesBlock(book)}` : header;
         return {
           content: [{ type: "text", text }]
         };
@@ -530,7 +573,10 @@ ${formatted}`
     { readOnlyHint: true, openWorldHint: true },
     async ({ book_token }) => {
       try {
-        const commits = await client.listCommits(book_token, 1);
+        const [book, commits] = await Promise.all([
+          client.getBook(book_token),
+          client.listCommits(book_token, 1)
+        ]);
         if (commits.length === 0) {
           return {
             content: [
@@ -544,13 +590,16 @@ ${formatted}`
         const flatSnapshot = commits[0].filesSnapshot;
         const nestedTree = buildFileTree(flatSnapshot);
         const tree = formatFileTree(nestedTree);
+        const footer = book.bookType === "script" ? `
+
+_\u{1F4DD} This is a Script Studio book. Via MCP, writes are restricted to \`.script_studio/planning/**/*\`. For the full write-restriction spec, read resource \`slima://books/${book.token}/schema\`._` : "";
         return {
           content: [
             {
               type: "text",
-              text: `File structure for book ${book_token}:
+              text: `File structure for ${studioLabel(book)} \u2014 ${book.title} (${book_token}):
 
-${tree}`
+${tree}${footer}`
             }
           ]
         };
@@ -826,15 +875,31 @@ ${formatted}
   );
   server.tool(
     "analyze_chapter",
-    "Get AI Beta Reader feedback on a chapter from a specific reader persona. This may take a moment to complete.",
+    `Get AI Beta Reader feedback on a chapter from a specific reader persona. This may take a moment to complete.
+
+**Not supported for Script Studio books** (\`book_type: "script"\`) \u2014 AI Beta Reader is a Writing Studio feature and does not yet parse \`.scene\` or \`series.json\` structures. Use the Script Studio UI's built-in analysis for screenplays.`,
     {
-      book_token: z3.string().describe("Book token (e.g., bk_abc123)"),
+      book_token: z3.string().describe('Book token (e.g., bk_abc123) \u2014 must be a Writing Studio book (book_type: "book").'),
       file_path: z3.string().describe("Chapter file path (e.g., /chapters/01.md)"),
       persona_token: z3.string().describe("Persona token (e.g., psn_xxx). Use list_personas to find available personas.")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     async ({ book_token, file_path, persona_token }) => {
       try {
+        const book = await client.getBook(book_token);
+        if (book.bookType === "script") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u274C analyze_chapter is not available for Script Studio books.
+
+Book "${book.title}" (${book.token}) is a Script Studio book. Please use the Script Studio UI's built-in analysis features (structural notes, character consistency, scene-level feedback) \u2014 AI Beta Reader is a Writing Studio feature.`
+              }
+            ],
+            isError: true
+          };
+        }
         const commits = await client.listCommits(book_token, 1);
         if (commits.length === 0) {
           return {
@@ -1179,6 +1244,18 @@ function searchByName2(files, name) {
 
 // src/core/tools/files.ts
 import { z as z4 } from "zod";
+var SCRIPT_STUDIO_WRITE_WARNING = `
+**IMPORTANT \u2014 Script Studio books (\`book_type: "script"\`):**
+Writes are restricted to \`.script_studio/planning/**/*\` only.
+Structured files (\`series.json\`, \`*.character\`, \`*.scene\`, \`*.storyline\`, \`*.note\`, \`*.location\`, \`season.json\`, \`episode.json\`) are READ-ONLY via MCP \u2014 structural edits must go through the Script Studio UI.
+The sentinel file \`.script_studio/planning/.initialized\` is also read-only (frontend bootstrap marker).
+Attempting to write outside \`planning/\` returns HTTP 400 with code \`INVALID_PATH\`.
+For per-book details, read resource \`slima://books/{book_token}/schema\`.
+
+For Writing Studio books (\`book_type: "book"\`), all paths remain writable.
+Always check \`book_type\` via \`list_books\` or \`get_book\` before writing to an unfamiliar book.`;
+var PATH_PARAM_HINT = 'File path relative to book root. For Script Studio books: MUST be under ".script_studio/planning/" (e.g., ".script_studio/planning/references/outline.md"). For Writing Studio books: any path (e.g., "characters/protagonist.md").';
+var SCRIPT_STRUCTURED_EXTENSIONS = ["character", "scene", "storyline", "note", "location"];
 function registerFileTools(server, client) {
   server.tool(
     "read_file",
@@ -1215,10 +1292,11 @@ function registerFileTools(server, client) {
   );
   server.tool(
     "write_file",
-    "Replace the entire content of an existing file (creates a new commit)",
+    `Replace the entire content of an existing file (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "characters/protagonist.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       content: z4.string().describe("New content to write"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
@@ -1251,10 +1329,11 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "edit_file",
-    "Edit a file by replacing a specific text segment (search and replace). Use this for precise edits instead of rewriting the entire file.",
+    `Edit a file by replacing a specific text segment (search and replace). Use this for precise edits instead of rewriting the entire file.
+${SCRIPT_STUDIO_WRITE_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "characters/protagonist.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       old_string: z4.string().describe("The exact text to find and replace (must match exactly, including whitespace)"),
       new_string: z4.string().describe("The new text to replace it with"),
       replace_all: z4.boolean().optional().describe("Replace all occurrences (default: false, replaces only first match)"),
@@ -1326,10 +1405,13 @@ ${old_string.slice(0, 200)}${old_string.length > 200 ? "..." : ""}
   );
   server.tool(
     "create_file",
-    "Create a new file in a book (creates a new commit)",
+    `Create a new file in a book (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path including parent folders (e.g., "characters/new-character.md")'),
+      path: z4.string().describe(
+        `${PATH_PARAM_HINT} Parent folders are auto-created (mkdir -p behavior).`
+      ),
       content: z4.string().optional().describe("Initial content (optional, defaults to empty)"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
@@ -1363,10 +1445,11 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "delete_file",
-    "Delete a file from a book (creates a new commit)",
+    `Delete a file from a book (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path to delete (e.g., "old-notes.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
@@ -1397,10 +1480,11 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "append_to_file",
-    "Append content to the end of an existing file (creates a new commit)",
+    `Append content to the end of an existing file (creates a new commit).
+${SCRIPT_STUDIO_WRITE_WARNING}`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
-      path: z4.string().describe('File path (e.g., "notes.md")'),
+      path: z4.string().describe(PATH_PARAM_HINT),
       content: z4.string().describe("Content to append"),
       commit_message: z4.string().optional().describe("Commit message (optional, auto-generated if not provided)")
     },
@@ -1433,27 +1517,45 @@ Message: ${result.commit.name || result.commit.message}`
   );
   server.tool(
     "search_content",
-    "Search for content across all files in a book",
+    `Search for content across all files in a book.
+
+**Script Studio behavior:** By default, structured files (\`*.character\`, \`*.scene\`, \`*.storyline\`, \`*.note\`, \`*.location\`, and \`*.json\` under \`.script_studio/\`) are **excluded** from search results \u2014 their raw JSON is noisy and not useful for full-text search.
+Pass \`include_structured: true\` to search those files too.
+Writing Studio books are unaffected by this filter.`,
     {
       book_token: z4.string().describe("Book token (e.g., bk_abc123)"),
       query: z4.string().describe('Search query (e.g., "blue eyes" or "protagonist name")'),
       file_types: z4.array(z4.string()).optional().describe('Filter by file types (e.g., ["markdown", "txt"])'),
-      limit: z4.number().optional().describe("Maximum number of matches to return (default: 20)")
+      limit: z4.number().optional().describe("Maximum number of matches to return (default: 20)"),
+      include_structured: z4.boolean().optional().describe(
+        "Script Studio only: set to true to include structured files (*.character / *.scene / etc.) in search results. Default: false (excluded)."
+      )
     },
     { readOnlyHint: true, openWorldHint: true },
-    async ({ book_token, query, file_types, limit }) => {
+    async ({ book_token, query, file_types, limit, include_structured }) => {
       try {
+        let bookType;
+        if (!include_structured) {
+          try {
+            const book = await client.getBook(book_token);
+            bookType = book.bookType;
+          } catch {
+          }
+        }
         const result = await client.searchFiles(book_token, {
           query,
           fileTypes: file_types,
           limit
         });
-        if (result.matches.length === 0) {
+        const shouldFilter = !include_structured && bookType === "script";
+        const filteredMatches = shouldFilter ? result.matches.filter((m) => !isStructuredScriptFile(m.file.path)) : result.matches;
+        if (filteredMatches.length === 0) {
+          const suffix = shouldFilter && result.matches.length > 0 ? ` (${result.matches.length} match(es) in structured files were excluded \u2014 pass include_structured: true to see them)` : "";
           return {
             content: [
               {
                 type: "text",
-                text: `No matches found for "${query}".`
+                text: `No matches found for "${query}"${suffix}.`
               }
             ]
           };
@@ -1461,10 +1563,17 @@ Message: ${result.commit.name || result.commit.message}`
         const output = [
           `# Search Results for "${query}"`,
           "",
-          `Found ${result.matches.length} file(s) with matches:`,
+          `Found ${filteredMatches.length} file(s) with matches:`,
           ""
         ];
-        for (const match of result.matches) {
+        if (shouldFilter && filteredMatches.length < result.matches.length) {
+          const excluded = result.matches.length - filteredMatches.length;
+          output.push(
+            `_Note: excluded ${excluded} Script Studio structured file(s). Pass include_structured: true to include them._`
+          );
+          output.push("");
+        }
+        for (const match of filteredMatches) {
           output.push(`## ${match.file.path}`);
           output.push(`Words: ${match.file.wordCount} | Matches: ${match.matchCount}`);
           output.push("");
@@ -1485,6 +1594,105 @@ Message: ${result.commit.name || result.commit.message}`
     }
   );
 }
+function isStructuredScriptFile(path) {
+  if (!path) return false;
+  const lower = path.toLowerCase();
+  if (lower.startsWith(".script_studio/") && lower.endsWith(".json")) return true;
+  const ext = lower.split(".").pop();
+  if (!ext) return false;
+  return SCRIPT_STRUCTURED_EXTENSIONS.includes(ext);
+}
+
+// src/core/resources/book_schema.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+var BOOK_SCHEMA_URI_TEMPLATE = "slima://books/{book_token}/schema";
+function registerBookSchemaResource(server, client) {
+  server.resource(
+    "slima-book-schema",
+    new ResourceTemplate(BOOK_SCHEMA_URI_TEMPLATE, {
+      // Intentionally no `list` callback — books may number in the hundreds, so
+      // we expose only the URI template via `resources/templates/list` and let
+      // clients call `resources/read` with a concrete token.
+      list: void 0
+    }),
+    {
+      description: "Per-book MCP operation schema: which paths are readable/writable, which are structured (read-only), and the structured file catalog. Read this before planning writes on an unfamiliar book.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const rawToken = variables["book_token"];
+      const bookToken = Array.isArray(rawToken) ? rawToken[0] : rawToken;
+      if (!bookToken) {
+        throw new Error(
+          `Invalid Slima book schema URI: missing book_token in ${uri.toString()}`
+        );
+      }
+      const book = await client.getBook(bookToken);
+      const schema = buildBookSchema(book);
+      return {
+        contents: [
+          {
+            uri: uri.toString(),
+            mimeType: "application/json",
+            text: JSON.stringify(schema, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+function buildBookSchema(book) {
+  const isScript = book.bookType === "script";
+  return {
+    book_token: book.token,
+    book_title: book.title,
+    book_type: book.bookType ?? "book",
+    studio_label: isScript ? "Script Studio" : "Writing Studio",
+    mcp_capabilities: {
+      // Note: actual reads still go through validate_safe_path!
+      // (blocks absolute paths, traversal, control chars) even though it's
+      // not reflected in this allowlist.
+      readable_paths: "Any path within the book tree (path-traversal and absolute paths still rejected).",
+      writable_paths: isScript ? [".script_studio/planning/**/*"] : ["**/*"],
+      writable_exceptions: isScript ? [".script_studio/planning/.initialized"] : [],
+      readonly_paths: isScript ? [
+        ".script_studio/series.json",
+        ".script_studio/seasons/**/season.json",
+        ".script_studio/seasons/**/episodes/**/episode.json",
+        ".script_studio/seasons/**/scenes/*.scene",
+        ".script_studio/characters/**/*.character",
+        ".script_studio/locations/**/*.location",
+        ".script_studio/storylines/**/*.storyline",
+        ".script_studio/notes/**/*.note",
+        ".script_studio/planning/.initialized"
+      ] : [],
+      reserved_sentinels: isScript ? [".script_studio/planning/.initialized"] : []
+    },
+    structured_file_types: isScript ? {
+      "series.json": "Series metadata (title, genre, logline, theme, synopsis, acts)",
+      "season.json": "Season metadata",
+      "episode.json": "Episode metadata",
+      "*.scene": "Scene content with scene-specific format",
+      "*.character": "Character definition with scope (series / season / episode)",
+      "*.location": "Location definition with scope",
+      "*.storyline": "Storyline with tier and ID linkage",
+      "*.note": "Note with scope"
+    } : {},
+    notes: isScript ? "Structured files require schema-aware edits \u2014 use the Script Studio UI. MCP write access is restricted to planning/ (free-form reference tree) to prevent schema corruption." : "Writing Studio books are free-form. No schema restrictions; any path is writable.",
+    policy_source: "Rails: Mcp::FileOperationService#validate_studio_write_path!"
+  };
+}
+
+// src/core/server-instructions.ts
+var SERVER_INSTRUCTIONS = `Slima is an AI writing IDE with two product lines, distinguished by the \`book_type\` field on every book:
+
+1. **Writing Studio** (\`book_type: "book"\`) \u2014 free-form markdown file tree for novels and long-form prose. All paths are writable via MCP.
+
+2. **Script Studio** (\`book_type: "script"\`) \u2014 structured schema for screenwriting with series / seasons / episodes / scenes / characters / locations / storylines / notes. Via MCP, only \`.script_studio/planning/**/*\` is writable; all structured files (series.json, *.character, *.scene, *.storyline, *.note, *.location, season.json, episode.json) and the \`.script_studio/planning/.initialized\` sentinel are READ-ONLY. Structural edits must happen through the Slima app UI.
+
+**Before writing to a book you haven't inspected this session:** call \`list_books\` or \`get_book\` to see \`book_type\`. For per-book write rules, read the resource \`slima://books/{book_token}/schema\`.
+
+Reads (\`read_file\`, \`search_content\`, \`get_book_structure\`) work the same way for both studio types \u2014 AI coaching, critique, and analysis are fully supported even on Script Studio books.`;
 
 // src/core/utils/logger.ts
 var isDebug = process.env.DEBUG === "true" || process.env.DEBUG === "1";
@@ -1521,14 +1729,20 @@ function createSlimaServer(config) {
     getToken: async () => config.apiToken,
     logger
   });
-  const server = new McpServer({
-    name: "slima",
-    version: "0.1.15"
-  });
+  const server = new McpServer(
+    {
+      name: "slima",
+      version: "0.2.0"
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS
+    }
+  );
   registerBookTools(server, client);
   registerContentTools(server, client);
   registerBetaReaderTools(server, client, logger);
   registerFileTools(server, client);
+  registerBookSchemaResource(server, client);
   logger.info("Slima MCP Server initialized");
   logger.info(`API endpoint: ${config.baseUrl || "https://api.slima.ai"}`);
   return server;
@@ -1975,7 +2189,7 @@ async function runStatus() {
 }
 
 // src/cli/index.ts
-var VERSION = "0.1.15";
+var VERSION = "0.2.0";
 function showHelp() {
   console.log(`
 Slima MCP v${VERSION}