@thallylabs/mcp 0.10.8 → 0.10.10

package/dist/index.js

@@ -1217,6 +1217,103 @@ async function handleSyncFromRepo(input) {
   return `\u2705 Dispatched docs task for ${target.owner}/${target.repo}#${pr.number} to ${input.docsRepo}. The "Thally docs agent" workflow there will draft the PR \u2014 watch its Actions tab.`;
 }
 
+// src/tools/read-api-spec.ts
+import { readFileSync as readFileSync8 } from "fs";
+import { z as z15 } from "zod";
+
+// src/lib/api-spec.ts
+import { existsSync as existsSync8, lstatSync, realpathSync } from "fs";
+import { isAbsolute, join as join9, posix, relative as relative2, resolve, sep } from "path";
+var CONVENTIONAL_API_SOURCES = ["openapi.yaml", "openapi.yml", "openapi.json"];
+function normalizeApiSource(source) {
+  const normalized = posix.normalize(source.trim().replace(/^\/+/, ""));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,239}$/.test(normalized) || !/\.(?:json|ya?ml)$/i.test(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+function configuredApiSources(projectDir) {
+  const configured = readDocsJson(projectDir).tabs.map((tab) => tab.api?.source).filter((source) => typeof source === "string").map(normalizeApiSource).filter((source) => source !== null);
+  const conventional = CONVENTIONAL_API_SOURCES.filter(
+    (source) => existsSync8(join9(projectDir, source))
+  );
+  return [.../* @__PURE__ */ new Set([...configured, ...conventional])];
+}
+function resolveApiSource(projectDir, requested) {
+  const sources = configuredApiSources(projectDir);
+  const normalizedRequested = requested ? normalizeApiSource(requested) : null;
+  if (requested && !normalizedRequested) {
+    throw new Error("API source must be a repository-relative JSON or YAML file.");
+  }
+  if (normalizedRequested && sources.includes(normalizedRequested)) {
+    return normalizedRequested;
+  }
+  if (!requested && sources.length === 1) return sources[0];
+  if (normalizedRequested) {
+    throw new Error(`API source is not configured in docs.json: ${normalizedRequested}`);
+  }
+  if (sources.length === 0) {
+    throw new Error("No OpenAPI source is configured in docs.json.");
+  }
+  throw new Error(`Multiple OpenAPI sources are configured; choose one of: ${sources.join(", ")}`);
+}
+function resolveApiSourcePath(projectDir, requested) {
+  const source = resolveApiSource(projectDir, requested);
+  const projectRoot = realpathSync(projectDir);
+  const candidate = resolve(projectRoot, source);
+  try {
+    const resolved = realpathSync(candidate);
+    const fromRoot = relative2(projectRoot, resolved);
+    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot) || !lstatSync(candidate).isFile() || lstatSync(candidate).isSymbolicLink()) {
+      throw new Error("unsafe");
+    }
+    return { source, path: resolved };
+  } catch {
+    throw new Error(`API source must be an existing regular file inside the project: ${source}`);
+  }
+}
+
+// src/tools/read-api-spec.ts
+var readApiSpecSchema = z15.object({
+  projectDir: z15.string().describe("Path to the Thally project root"),
+  source: z15.string().optional().describe("Configured OpenAPI source; omit when the project has one")
+});
+async function handleReadApiSpec(input) {
+  const source = resolveApiSourcePath(input.projectDir, input.source);
+  return [`API source: ${source.source}`, "", readFileSync8(source.path, "utf8")].join("\n");
+}
+
+// src/tools/update-api-spec.ts
+import { writeFileSync as writeFileSync6 } from "fs";
+import { extname as extname2 } from "path";
+import { z as z16 } from "zod";
+import { parse as parseYaml } from "yaml";
+var updateApiSpecSchema = z16.object({
+  projectDir: z16.string().describe("Path to the Thally project root"),
+  source: z16.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
+  content: z16.string().min(2).max(512e3).describe("Complete replacement OpenAPI JSON or YAML document")
+});
+function parseDocument(source, content) {
+  try {
+    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml(content);
+  } catch {
+    throw new Error(
+      `OpenAPI source is not valid ${extname2(source).toLowerCase() === ".json" ? "JSON" : "YAML"}.`
+    );
+  }
+}
+async function handleUpdateApiSpec(input) {
+  const source = resolveApiSourcePath(input.projectDir, input.source);
+  const parsed = parseDocument(source.source, input.content);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("openapi" in parsed) || !("paths" in parsed)) {
+    throw new Error("OpenAPI source must contain top-level openapi and paths fields.");
+  }
+  const content = input.content.endsWith("\n") ? input.content : `${input.content}
+`;
+  writeFileSync6(source.path, content, "utf8");
+  return `\u2705 API source updated: ${source.source}`;
+}
+
 // src/lib/tools.ts
 function defineTool(def) {
   return def;
@@ -1257,6 +1354,20 @@ var tools = [
     schema: updatePageSchema,
     handler: handleUpdatePage
   }),
+  defineTool({
+    name: "read_api_spec",
+    description: "Read an OpenAPI JSON or YAML source explicitly configured by this Thally project",
+    scope: "project",
+    schema: readApiSpecSchema,
+    handler: handleReadApiSpec
+  }),
+  defineTool({
+    name: "update_api_spec",
+    description: "Replace and validate an OpenAPI JSON or YAML source explicitly configured by this Thally project",
+    scope: "project",
+    schema: updateApiSpecSchema,
+    handler: handleUpdateApiSpec
+  }),
   defineTool({
     name: "migrate_docs",
     description: "Create a fresh canonical Thally template, then migrate a GitHub repository or public docs site into it; the target must be new or empty",

package/dist/tools.js

@@ -1208,6 +1208,103 @@ async function handleSyncFromRepo(input) {
   return `\u2705 Dispatched docs task for ${target.owner}/${target.repo}#${pr.number} to ${input.docsRepo}. The "Thally docs agent" workflow there will draft the PR \u2014 watch its Actions tab.`;
 }
 
+// src/tools/read-api-spec.ts
+import { readFileSync as readFileSync8 } from "fs";
+import { z as z15 } from "zod";
+
+// src/lib/api-spec.ts
+import { existsSync as existsSync8, lstatSync, realpathSync } from "fs";
+import { isAbsolute, join as join9, posix, relative as relative2, resolve, sep } from "path";
+var CONVENTIONAL_API_SOURCES = ["openapi.yaml", "openapi.yml", "openapi.json"];
+function normalizeApiSource(source) {
+  const normalized = posix.normalize(source.trim().replace(/^\/+/, ""));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,239}$/.test(normalized) || !/\.(?:json|ya?ml)$/i.test(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+function configuredApiSources(projectDir) {
+  const configured = readDocsJson(projectDir).tabs.map((tab) => tab.api?.source).filter((source) => typeof source === "string").map(normalizeApiSource).filter((source) => source !== null);
+  const conventional = CONVENTIONAL_API_SOURCES.filter(
+    (source) => existsSync8(join9(projectDir, source))
+  );
+  return [.../* @__PURE__ */ new Set([...configured, ...conventional])];
+}
+function resolveApiSource(projectDir, requested) {
+  const sources = configuredApiSources(projectDir);
+  const normalizedRequested = requested ? normalizeApiSource(requested) : null;
+  if (requested && !normalizedRequested) {
+    throw new Error("API source must be a repository-relative JSON or YAML file.");
+  }
+  if (normalizedRequested && sources.includes(normalizedRequested)) {
+    return normalizedRequested;
+  }
+  if (!requested && sources.length === 1) return sources[0];
+  if (normalizedRequested) {
+    throw new Error(`API source is not configured in docs.json: ${normalizedRequested}`);
+  }
+  if (sources.length === 0) {
+    throw new Error("No OpenAPI source is configured in docs.json.");
+  }
+  throw new Error(`Multiple OpenAPI sources are configured; choose one of: ${sources.join(", ")}`);
+}
+function resolveApiSourcePath(projectDir, requested) {
+  const source = resolveApiSource(projectDir, requested);
+  const projectRoot = realpathSync(projectDir);
+  const candidate = resolve(projectRoot, source);
+  try {
+    const resolved = realpathSync(candidate);
+    const fromRoot = relative2(projectRoot, resolved);
+    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot) || !lstatSync(candidate).isFile() || lstatSync(candidate).isSymbolicLink()) {
+      throw new Error("unsafe");
+    }
+    return { source, path: resolved };
+  } catch {
+    throw new Error(`API source must be an existing regular file inside the project: ${source}`);
+  }
+}
+
+// src/tools/read-api-spec.ts
+var readApiSpecSchema = z15.object({
+  projectDir: z15.string().describe("Path to the Thally project root"),
+  source: z15.string().optional().describe("Configured OpenAPI source; omit when the project has one")
+});
+async function handleReadApiSpec(input) {
+  const source = resolveApiSourcePath(input.projectDir, input.source);
+  return [`API source: ${source.source}`, "", readFileSync8(source.path, "utf8")].join("\n");
+}
+
+// src/tools/update-api-spec.ts
+import { writeFileSync as writeFileSync6 } from "fs";
+import { extname as extname2 } from "path";
+import { z as z16 } from "zod";
+import { parse as parseYaml } from "yaml";
+var updateApiSpecSchema = z16.object({
+  projectDir: z16.string().describe("Path to the Thally project root"),
+  source: z16.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
+  content: z16.string().min(2).max(512e3).describe("Complete replacement OpenAPI JSON or YAML document")
+});
+function parseDocument(source, content) {
+  try {
+    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml(content);
+  } catch {
+    throw new Error(
+      `OpenAPI source is not valid ${extname2(source).toLowerCase() === ".json" ? "JSON" : "YAML"}.`
+    );
+  }
+}
+async function handleUpdateApiSpec(input) {
+  const source = resolveApiSourcePath(input.projectDir, input.source);
+  const parsed = parseDocument(source.source, input.content);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("openapi" in parsed) || !("paths" in parsed)) {
+    throw new Error("OpenAPI source must contain top-level openapi and paths fields.");
+  }
+  const content = input.content.endsWith("\n") ? input.content : `${input.content}
+`;
+  writeFileSync6(source.path, content, "utf8");
+  return `\u2705 API source updated: ${source.source}`;
+}
+
 // src/lib/tools.ts
 function defineTool(def) {
   return def;
@@ -1248,6 +1345,20 @@ var tools = [
     schema: updatePageSchema,
     handler: handleUpdatePage
   }),
+  defineTool({
+    name: "read_api_spec",
+    description: "Read an OpenAPI JSON or YAML source explicitly configured by this Thally project",
+    scope: "project",
+    schema: readApiSpecSchema,
+    handler: handleReadApiSpec
+  }),
+  defineTool({
+    name: "update_api_spec",
+    description: "Replace and validate an OpenAPI JSON or YAML source explicitly configured by this Thally project",
+    scope: "project",
+    schema: updateApiSpecSchema,
+    handler: handleUpdateApiSpec
+  }),
   defineTool({
     name: "migrate_docs",
     description: "Create a fresh canonical Thally template, then migrate a GitHub repository or public docs site into it; the target must be new or empty",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thallylabs/mcp",
-  "version": "0.10.8",
+  "version": "0.10.10",
   "description": "MCP server for managing Thally knowledge surfaces and tracing product changes into documentation work.",
   "type": "module",
   "engines": {
@@ -38,9 +38,10 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.36.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
-    "create-thally-docs": "0.10.8",
+    "create-thally-docs": "0.10.9",
     "gray-matter": "^4.0.3",
     "p-limit": "^6.1.0",
+    "yaml": "^2.8.2",
     "zod": "^3.0.0"
   },
   "devDependencies": {