@cancia/mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonino Dell'Albani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/annotate/index.d.ts

@@ -0,0 +1,45 @@
+/** One element that received (or would receive) a data-cms attribute. */
+interface AnnotationTag {
+    /** The i18n key extracted from the t("…") call. */
+    key: string;
+    /** Tag name of the element that was annotated (e.g. "h1"). */
+    tag: string;
+    /** 1-based line number of the element's opening tag in the source. */
+    line: number;
+}
+/**
+ * A t() call we deliberately did not annotate, with the reason. The agent
+ * surfaces these so a human can decide whether any need manual handling.
+ */
+interface AnnotationSkip {
+    key: string | null;
+    /** 1-based line number where the skipped call appears. */
+    line: number;
+    reason: "attribute" | "mixed-children" | "already-annotated" | "non-literal-key" | "unlocatable-tag";
+}
+interface AnnotateResult {
+    /** The rewritten source. Identical to input when nothing changed. */
+    code: string;
+    /** True when `code` differs from the input. */
+    changed: boolean;
+    /** Elements that got a data-cms attribute. */
+    tagged: AnnotationTag[];
+    /** t() calls intentionally left alone, with reasons. */
+    skipped: AnnotationSkip[];
+}
+interface AnnotateOptions {
+    /**
+     * Name of the translation function to match. Defaults to "t" — the
+     * convention used by useTranslations(lang). Set this if a project aliases
+     * it (e.g. "translate").
+     */
+    tFunction?: string;
+}
+
+/**
+ * Annotate Astro/JSX source: add data-cms="KEY" to every element whose only
+ * meaningful child is a t("KEY") call.
+ */
+declare function annotateSource(source: string, opts?: AnnotateOptions): Promise<AnnotateResult>;
+
+export { type AnnotateOptions, type AnnotateResult, type AnnotationSkip, type AnnotationTag, annotateSource };

package/dist/annotate/index.js

@@ -0,0 +1,6 @@
+import {
+  annotateSource
+} from "../chunk-4DOTVUP2.js";
+export {
+  annotateSource
+};

package/dist/chunk-4DOTVUP2.js

@@ -0,0 +1,167 @@
+// src/annotate/index.ts
+import { parse } from "@astrojs/compiler";
+function isElement(n) {
+  return n.type === "element" || n.type === "component" || n.type === "custom-element";
+}
+function expressionSource(node) {
+  return (node.children ?? []).map((c) => c.value ?? "").join("");
+}
+function matchTCall(src, tFn) {
+  const trimmed = src.trim();
+  const re = new RegExp(`^${escapeRegex(tFn)}\\(\\s*(["'])([^"']+)\\1\\s*\\)$`);
+  const m = trimmed.match(re);
+  return m ? m[2] : null;
+}
+function isNonLiteralTCall(src, tFn) {
+  const trimmed = src.trim();
+  return new RegExp(`^${escapeRegex(tFn)}\\s*\\(`).test(trimmed) && matchTCall(src, tFn) === null;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function meaningfulChildren(node) {
+  return (node.children ?? []).filter((c) => {
+    if (c.type === "text") return (c.value ?? "").trim() !== "";
+    if (c.type === "comment") return false;
+    return true;
+  });
+}
+function findOpenAngle(node, src) {
+  const reported = node.position?.start?.offset;
+  if (reported === void 0) return null;
+  const name = node.name;
+  const floor = Math.max(0, reported - 4096);
+  for (let i = Math.min(reported, src.length - 1); i >= floor; i--) {
+    if (src[i] !== "<") continue;
+    const after = src.slice(i + 1, i + 1 + name.length);
+    if (after !== name) continue;
+    const boundary = src[i + 1 + name.length];
+    if (boundary === void 0 || /[\s/>]/.test(boundary)) return i;
+  }
+  return null;
+}
+function hasDataCmsAttr(node, src) {
+  const lt = findOpenAngle(node, src);
+  if (lt === null) return false;
+  const gt = src.indexOf(">", lt);
+  if (gt === -1) return false;
+  const openTag = src.slice(lt, gt);
+  return /\sdata-cms\s*=/.test(openTag);
+}
+function tagNameEnd(node, src) {
+  const lt = findOpenAngle(node, src);
+  if (lt === null) return null;
+  let i = lt + 1;
+  while (i < src.length && /[A-Za-z0-9\-:.]/.test(src[i])) i++;
+  return i;
+}
+function lineAt(src, offset) {
+  if (offset === void 0) return 0;
+  let line = 1;
+  for (let i = 0; i < offset && i < src.length; i++) {
+    if (src[i] === "\n") line++;
+  }
+  return line;
+}
+async function annotateSource(source, opts = {}) {
+  const tFn = opts.tFunction ?? "t";
+  const { ast } = await parse(source, { position: true });
+  const tagged = [];
+  const skipped = [];
+  const edits = [];
+  const claimed = /* @__PURE__ */ new Set();
+  function visit(node) {
+    if (isElement(node)) {
+      const kids = meaningfulChildren(node);
+      const onlyChild = kids.length === 1 ? kids[0] : null;
+      if (onlyChild && onlyChild.type === "expression") {
+        const exprSrc = expressionSource(onlyChild);
+        const key = matchTCall(exprSrc, tFn);
+        if (key !== null) {
+          claimed.add(onlyChild);
+          if (hasDataCmsAttr(node, source)) {
+            skipped.push({
+              key,
+              line: lineAt(source, node.position?.start?.offset),
+              reason: "already-annotated"
+            });
+          } else {
+            const at = tagNameEnd(node, source);
+            if (at !== null) {
+              edits.push({ at, text: ` data-cms="${key}"` });
+              tagged.push({
+                key,
+                tag: node.name,
+                line: lineAt(source, node.position?.start?.offset)
+              });
+            } else {
+              skipped.push({
+                key,
+                line: lineAt(source, node.position?.start?.offset),
+                reason: "unlocatable-tag"
+              });
+            }
+          }
+        } else if (isNonLiteralTCall(exprSrc, tFn)) {
+          claimed.add(onlyChild);
+          skipped.push({
+            key: null,
+            line: lineAt(source, onlyChild.position?.start?.offset),
+            reason: "non-literal-key"
+          });
+        }
+      } else if (kids.length > 1) {
+        for (const k of kids) {
+          if (k.type === "expression") {
+            const key = matchTCall(expressionSource(k), tFn);
+            if (key !== null) {
+              claimed.add(k);
+              skipped.push({
+                key,
+                line: lineAt(source, k.position?.start?.offset),
+                reason: "mixed-children"
+              });
+            }
+          }
+        }
+      }
+    }
+    for (const c of node.children ?? []) visit(c);
+  }
+  visit(ast);
+  function sweepAttributes(node) {
+    if (isElement(node)) {
+      for (const attr of node.attributes ?? []) {
+        for (const c of attr.children ?? []) {
+          if (c.type === "expression") {
+            const key = matchTCall(expressionSource(c), tFn);
+            if (key !== null && !claimed.has(c)) {
+              skipped.push({
+                key,
+                line: lineAt(source, c.position?.start?.offset),
+                reason: "attribute"
+              });
+            }
+          }
+        }
+      }
+    }
+    for (const c of node.children ?? []) sweepAttributes(c);
+  }
+  sweepAttributes(ast);
+  if (edits.length === 0) {
+    return { code: source, changed: false, tagged, skipped };
+  }
+  edits.sort((a, b) => b.at - a.at);
+  let code = source;
+  for (const e of edits) {
+    code = code.slice(0, e.at) + e.text + code.slice(e.at);
+  }
+  tagged.sort((a, b) => a.line - b.line);
+  skipped.sort((a, b) => a.line - b.line);
+  return { code, changed: true, tagged, skipped };
+}
+
+export {
+  annotateSource
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { AnnotateOptions, AnnotateResult, AnnotationSkip, AnnotationTag, annotateSource } from './annotate/index.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  annotateSource
+} from "./chunk-4DOTVUP2.js";
+export {
+  annotateSource
+};

package/dist/server.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/server.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import {
+  annotateSource
+} from "./chunk-4DOTVUP2.js";
+
+// src/server.ts
+import { readFile, writeFile } from "fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/paths.ts
+import { resolve, relative, isAbsolute, extname } from "path";
+var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([".astro", ".tsx", ".jsx"]);
+function resolveTargetPath(path, root = process.env.CANCIA_MCP_ROOT ?? process.cwd()) {
+  const absRoot = resolve(root);
+  const abs = resolve(absRoot, path);
+  const rel = relative(absRoot, abs);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { ok: false, error: `Path escapes the project root (${absRoot}): ${path}` };
+  }
+  if (!ALLOWED_EXTENSIONS.has(extname(abs))) {
+    return { ok: false, error: `Unsupported file type "${extname(abs)}" \u2014 expected .astro, .tsx, or .jsx` };
+  }
+  return { ok: true, abs };
+}
+
+// src/server.ts
+function renderReport(path, result, wrote) {
+  const lines = [];
+  lines.push(`File: ${path}`);
+  lines.push(
+    result.changed ? wrote ? `Status: ${result.tagged.length} element(s) annotated and written.` : `Status: ${result.tagged.length} element(s) would be annotated (dry run \u2014 nothing written).` : `Status: no changes \u2014 nothing to annotate.`
+  );
+  if (result.tagged.length) {
+    lines.push("");
+    lines.push("Annotated:");
+    for (const t of result.tagged) {
+      lines.push(`  L${t.line}  <${t.tag}>  data-cms="${t.key}"`);
+    }
+  }
+  if (result.skipped.length) {
+    lines.push("");
+    lines.push("Skipped (review if any of these should be editable):");
+    for (const s of result.skipped) {
+      const label = s.reason === "attribute" ? `attribute t() \u2014 not a clickable text node` : s.reason === "mixed-children" ? `mixed children \u2014 element has other content besides the t() call` : s.reason === "already-annotated" ? `already has data-cms` : s.reason === "unlocatable-tag" ? `could not locate the opening tag \u2014 annotate manually` : `non-literal key \u2014 t(expr) not a string literal`;
+      lines.push(`  L${s.line}  ${s.key ? `"${s.key}"  ` : ""}${label}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function main() {
+  const server = new McpServer({
+    name: "cancia",
+    version: "0.0.1"
+  });
+  server.registerTool(
+    "annotate_page",
+    {
+      title: "Annotate page for CMS editing",
+      description: `Make an Astro/JSX component editable in the Cancia inline editor. Scans the file for t("KEY") calls rendered as the sole child of an element and inserts data-cms="KEY" on that element. Skips t() calls inside attributes (alt/title/aria) and flags elements with mixed children for manual review. Defaults to a dry run \u2014 pass write:true to save changes. The i18n keys themselves are assumed to already exist in the project's ui.ts (this tool only wires the markup, it does not create keys).`,
+      inputSchema: {
+        path: z.string().describe(
+          "Path to the .astro/.tsx/.jsx file, resolved against the project root (CANCIA_MCP_ROOT or the server's cwd). Paths may not escape the project root."
+        ),
+        write: z.boolean().optional().describe("Write changes to disk. Defaults to false (dry run)."),
+        tFunction: z.string().optional().describe('Translation function name to match. Defaults to "t".')
+      }
+    },
+    async ({ path, write, tFunction }) => {
+      const resolved = resolveTargetPath(path);
+      if (!resolved.ok) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: resolved.error }]
+        };
+      }
+      const abs = resolved.abs;
+      let source;
+      try {
+        source = await readFile(abs, "utf8");
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Could not read ${abs}: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+      const result = await annotateSource(source, { tFunction });
+      let wrote = false;
+      if (write && result.changed) {
+        await writeFile(abs, result.code, "utf8");
+        wrote = true;
+      }
+      return {
+        content: [{ type: "text", text: renderReport(abs, result, wrote) }]
+      };
+    }
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("cancia-mcp fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cancia/mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Cancia — agent tools for annotating Astro sites and editing content",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ninuzdellalb/cancia",
+    "directory": "packages/mcp"
+  },
+  "type": "module",
+  "bin": {
+    "cancia-mcp": "./dist/server.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./annotate": {
+      "types": "./dist/annotate/index.d.ts",
+      "import": "./dist/annotate/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@astrojs/compiler": "^2.10.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}