sqlitedata-swift-mcp 1.1.0

package/README.md

@@ -0,0 +1,61 @@
+# SQLiteData Swift MCP Server
+
+Model Context Protocol server for the SQLiteData skills collection.
+
+Exposes SQLiteData skills as MCP resources, commands as prompts, and tools for ask-style routing, search, and skill reads.
+
+## Install
+
+### Published package
+
+```bash
+npx -y sqlitedata-swift-mcp
+```
+
+### From the repo
+
+```bash
+node mcp-server/src/server.mjs
+```
+
+## Example MCP Config
+
+```json
+{
+  "mcpServers": {
+    "sqlitedata-swift": {
+      "command": "npx",
+      "args": ["-y", "sqlitedata-swift-mcp"]
+    }
+  }
+}
+```
+
+### Local checkout
+
+```json
+{
+  "mcpServers": {
+    "sqlitedata-swift": {
+      "command": "node",
+      "args": ["/path/to/sqlite-data/mcp-server/src/server.mjs"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `ask` — route a question to the best skill
+- `list_skills` — enumerate all skills
+- `search_skills` — search by name/alias/description
+- `get_skill` — retrieve a specific skill
+
+## Resources
+
+- `sqlitedata-swift://skills/{name}` — one resource per skill
+
+## Prompts
+
+- `ask` — with skill routing
+- `audit` — with anti-pattern checklist

package/bin/sqlitedata-swift-mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/server.mjs";

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "sqlitedata-swift-mcp",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "MCP server for SQLiteData Swift skills \u2014 @Table models, CloudKit sync, API reference, and diagnostics",
+  "bin": {
+    "sqlitedata-swift-mcp": "./bin/sqlitedata-swift-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/plugin-catalog.mjs

@@ -0,0 +1,303 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_SKILLS_ROOT = path.resolve(__dirname, "../../skills");
+export const DEFAULT_COMMANDS_ROOT = path.resolve(__dirname, "../../commands");
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function loadFrontmatter(markdown) {
+  const match = markdown.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!match) return { attributes: {}, body: markdown };
+
+  const attributes = {};
+  for (const rawLine of match[1].split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || !line.includes(":")) continue;
+    const sep = line.indexOf(":");
+    const key = line.slice(0, sep).trim();
+    let value = line.slice(sep + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    attributes[key] = value;
+  }
+
+  return { attributes, body: markdown.slice(match[0].length) };
+}
+
+function extractTitle(markdown, fallback) {
+  const match = markdown.match(/^#\s+(.+)$/m);
+  return match?.[1]?.replaceAll("`", "").trim() || fallback;
+}
+
+function wordTokens(query) {
+  return String(query ?? "").toLowerCase().split(/[^a-z0-9_]+/i).filter(Boolean);
+}
+
+function makeSnippet(markdown, query) {
+  const singleLine = markdown.replace(/\s+/g, " ").trim();
+  if (!singleLine) return "";
+  const lower = singleLine.toLowerCase();
+  const normalized = String(query ?? "").trim().toLowerCase();
+  const hit = normalized ? lower.indexOf(normalized) : -1;
+  const start = hit >= 0 ? Math.max(0, hit - 80) : 0;
+  const snippet = singleLine.slice(start, start + 220).trim();
+  return start > 0 ? `...${snippet}` : snippet;
+}
+
+function scoreSkill(skill, query, tokens) {
+  const lowerQuery = query.toLowerCase();
+  const haystacks = [
+    skill.name.toLowerCase(),
+    skill.title.toLowerCase(),
+    skill.description.toLowerCase(),
+    skill.markdown.toLowerCase(),
+    ...skill.aliases.map((a) => a.toLowerCase()),
+  ];
+
+  let score = 0;
+  for (const haystack of haystacks) {
+    if (haystack.includes(lowerQuery)) {
+      score += haystack === skill.markdown.toLowerCase() ? 20 : 80;
+    }
+  }
+  for (const token of tokens) {
+    for (const haystack of haystacks) {
+      if (haystack.includes(token)) {
+        score += haystack === skill.markdown.toLowerCase() ? 2 : 12;
+      }
+    }
+  }
+  return score;
+}
+
+function routePatterns() {
+  // Order matters: more specific patterns first, broad patterns last
+  return [
+    {
+      name: "sqlitedata-swift-diag",
+      reason: "matched error or troubleshooting terms",
+      patterns: [
+        /\b(error|debug|debugging|troubleshoot|fail|fails|failing|crash|constraint|permission|not working)\b/i,
+        /\bwhy does\b/i,
+      ],
+    },
+    {
+      name: "sqlitedata-swift-swiftdata-sync",
+      reason: "matched SwiftData comparison terms",
+      patterns: [/\b(SwiftData sync|SwiftData.*compar|NSPersistentCloudKitContainer|ModelConfiguration)\b/i],
+    },
+    {
+      name: "sqlitedata-swift-icloud-services",
+      reason: "matched iCloud setup terms",
+      patterns: [/\b(iCloud capability|entitlement|iCloud container|Xcode iCloud|iCloud.*setup|iCloud.*capability)\b/i],
+    },
+    {
+      name: "sqlitedata-swift-deploy-schema",
+      reason: "matched schema deployment terms",
+      patterns: [/\b(deploy schema|cloudkit console|production schema|reset development|schema.*production)\b/i],
+    },
+    {
+      name: "sqlitedata-swift-shared-records",
+      reason: "matched sharing terms",
+      patterns: [/\b(CKShare|shared records|sharing permissions|participants|UICloudSharingController)\b/i],
+    },
+    {
+      name: "sqlitedata-swift-ref",
+      reason: "matched API reference terms",
+      patterns: [
+        /\b(api signature|type signature|method signature|init parameter)\b/i,
+        /\bwhat methods\b/i,
+        /\b(FetchKeyRequest|DefaultDatabase|SyncMetadata)\b.*\b(signature|type|init|api)\b/i,
+      ],
+    },
+    {
+      name: "sqlitedata-swift-cloudkit",
+      reason: "matched CloudKit or sync terms",
+      patterns: [
+        /\b(SyncEngine|CloudKit sync|CKRecord|SyncMetadata)\b/i,
+        /\bcloudkit\b/i,
+      ],
+    },
+    {
+      name: "sqlitedata-swift-core",
+      reason: "matched core pattern terms",
+      patterns: [
+        /\b(@Table|@FetchAll|@FetchOne|@Fetch|FetchKeyRequest|@Selection|@Column|DatabaseMigrator|prepareDependencies|defaultDatabase)\b/i,
+        /\b(migration|insert|update|delete|join|leftJoin|@Observable|@ObservationIgnored)\b/i,
+      ],
+    },
+  ];
+}
+
+export function loadPluginCatalog(skillsRoot = DEFAULT_SKILLS_ROOT, commandsRoot = DEFAULT_COMMANDS_ROOT) {
+  const skillMetadataPath = path.join(skillsRoot, "catalog.json");
+  const skillMetadata = existsSync(skillMetadataPath)
+    ? JSON.parse(readFileSync(skillMetadataPath, "utf8")).skills ?? []
+    : [];
+  const metadataByName = new Map(skillMetadata.filter((e) => e?.name).map((e) => [e.name, e]));
+
+  const skills = [];
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = path.join(skillsRoot, entry.name, "SKILL.md");
+    if (!existsSync(skillPath)) continue;
+
+    const markdown = readFileSync(skillPath, "utf8");
+    const { attributes, body } = loadFrontmatter(markdown);
+    const metadata = metadataByName.get(entry.name) ?? {};
+    const name = attributes.name || entry.name;
+
+    skills.push({
+      name,
+      title: extractTitle(body, entry.name),
+      description: attributes.description || metadata.description || "",
+      category: metadata.category || null,
+      kind: metadata.kind || null,
+      entrypointPriority: metadata.entrypoint_priority ?? Number.MAX_SAFE_INTEGER,
+      aliases: Array.isArray(metadata.aliases) ? metadata.aliases : [],
+      relatedSkills: Array.isArray(metadata.related_skills) ? metadata.related_skills : [],
+      uri: `sqlitedata-swift://skills/${encodeURIComponent(name)}`,
+      relativePath: toPosixPath(path.relative(skillsRoot, skillPath)),
+      markdown,
+    });
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+
+  const commands = [];
+  if (existsSync(commandsRoot)) {
+    for (const entry of readdirSync(commandsRoot, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const commandPath = path.join(commandsRoot, entry.name);
+      const markdown = readFileSync(commandPath, "utf8");
+      const { attributes, body } = loadFrontmatter(markdown);
+      const name = path.basename(entry.name, ".md");
+
+      commands.push({
+        name,
+        title: extractTitle(body, name),
+        description: attributes.description || "",
+        argumentHint: attributes["argument-hint"] || "",
+        markdown,
+        uri: `sqlitedata-swift://commands/${encodeURIComponent(name)}`,
+        relativePath: toPosixPath(path.relative(commandsRoot, commandPath)),
+      });
+    }
+  }
+  commands.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    skills,
+    commands,
+    skillByName: new Map(skills.map((s) => [s.name.toLowerCase(), s])),
+    skillByUri: new Map(skills.map((s) => [s.uri, s])),
+    commandByName: new Map(commands.map((c) => [c.name.toLowerCase(), c])),
+  };
+}
+
+export function listSkills(catalog) {
+  return catalog.skills.map((s) => ({
+    name: s.name, title: s.title, description: s.description,
+    category: s.category, kind: s.kind, uri: s.uri, relatedSkills: s.relatedSkills,
+  }));
+}
+
+export function findSkill(catalog, locator = {}) {
+  if (locator.uri) return catalog.skillByUri.get(String(locator.uri)) ?? null;
+  if (locator.name) return catalog.skillByName.get(String(locator.name).toLowerCase()) ?? null;
+  return null;
+}
+
+export function searchSkills(catalog, query, limit = 5) {
+  const trimmed = String(query ?? "").trim();
+  if (!trimmed) return [];
+  const tokens = wordTokens(trimmed);
+  return catalog.skills
+    .map((s) => ({ skill: s, score: scoreSkill(s, trimmed, tokens) }))
+    .filter((e) => e.score > 0)
+    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+    .slice(0, limit)
+    .map(({ skill, score }) => ({
+      name: skill.name, title: skill.title, description: skill.description,
+      category: skill.category, kind: skill.kind, uri: skill.uri, score,
+      snippet: makeSnippet(skill.markdown, trimmed),
+    }));
+}
+
+export function routeAsk(catalog, question) {
+  const normalized = String(question ?? "").trim();
+  if (!normalized) return null;
+
+  for (const route of routePatterns()) {
+    if (route.patterns.some((p) => p.test(normalized))) {
+      const skill = findSkill(catalog, { name: route.name });
+      if (skill) return { skill, reason: route.reason };
+    }
+  }
+
+  const [best] = searchSkills(catalog, normalized, 1);
+  if (best) {
+    const skill = findSkill(catalog, { name: best.name });
+    if (skill) return { skill, reason: "matched the closest skill by aliases and description" };
+  }
+
+  const fallback = findSkill(catalog, { name: "sqlitedata-swift" });
+  return fallback ? { skill: fallback, reason: "fell back to the broad SQLiteData router" } : null;
+}
+
+export function buildAskResponse(catalog, question, options = {}) {
+  const route = routeAsk(catalog, question);
+  if (!route) return null;
+
+  const { skill, reason } = route;
+  const lines = [
+    `Recommended skill: ${skill.name}`,
+    `Title: ${skill.title}`,
+    `Why: ${reason}`,
+    `Resource URI: ${skill.uri}`,
+  ];
+  if (skill.description) lines.push(`Description: ${skill.description}`);
+  if (options.includeSkillContent !== false) {
+    lines.push("", "---", "", skill.markdown.trim());
+  }
+  return lines.join("\n");
+}
+
+export function getPrompt(catalog, name, args = {}) {
+  const command = catalog.commandByName.get(String(name).toLowerCase());
+  if (!command) return null;
+
+  if (command.name === "ask") {
+    const question = String(args.question ?? args.arguments ?? "").trim();
+    const routed = question ? buildAskResponse(catalog, question, { includeSkillContent: true }) : null;
+    return {
+      description: command.description,
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: routed
+            ? `${routed}\n\n---\n\nPrompt template:\n\n${command.markdown.trim()}`
+            : command.markdown.trim(),
+        },
+      }],
+    };
+  }
+
+  const suffix = String(args.area ?? args.arguments ?? "").trim();
+  return {
+    description: command.description,
+    messages: [{
+      role: "user",
+      content: {
+        type: "text",
+        text: suffix ? `${command.markdown.trim()}\n\nArguments: ${suffix}` : command.markdown.trim(),
+      },
+    }],
+  };
+}

package/src/server.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildAskResponse,
+  findSkill,
+  getPrompt,
+  listSkills,
+  loadPluginCatalog,
+  searchSkills,
+} from "./plugin-catalog.mjs";
+
+const SERVER_INFO = {
+  name: "sqlitedata-swift-mcp",
+  version: "1.0.0",
+};
+
+const LATEST_PROTOCOL_VERSION = "2025-11-25";
+const SUPPORTED_PROTOCOL_VERSIONS = [
+  LATEST_PROTOCOL_VERSION,
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+  "2024-10-07",
+];
+
+function jsonResponse(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function jsonError(id, code, message, data) {
+  return { jsonrpc: "2.0", id, error: { code, message, data } };
+}
+
+function makeTextResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function formatSkill(skill) {
+  return [
+    `- Name: ${skill.name}`,
+    `- Title: ${skill.title}`,
+    `- Kind: ${skill.kind ?? "workflow"}`,
+    `- Category: ${skill.category ?? "uncategorized"}`,
+    `- Resource URI: ${skill.uri}`,
+    "",
+    "---",
+    "",
+    skill.markdown.trim(),
+    "",
+  ].join("\n");
+}
+
+function toolDefinitions() {
+  return [
+    {
+      name: "list_skills",
+      description: "List the SQLiteData skills exposed by this MCP server.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "search_skills",
+      description: "Search SQLiteData skills by name, aliases, and description.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search text." },
+          limit: { type: "integer", minimum: 1, maximum: 20, description: "Max results.", default: 5 },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "get_skill",
+      description: "Return the full markdown for a specific SQLiteData skill by name or URI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Skill name, e.g. sqlitedata-swift-core." },
+          uri: { type: "string", description: "Skill resource URI." },
+        },
+      },
+    },
+    {
+      name: "ask",
+      description: "Route a natural-language SQLiteData question to the most relevant skill and return its guidance.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "A natural-language SQLiteData question." },
+          includeSkillContent: { type: "boolean", description: "Include the full skill markdown.", default: true },
+        },
+        required: ["question"],
+      },
+    },
+  ];
+}
+
+export function createServer() {
+  const pluginCatalog = loadPluginCatalog();
+
+  function handleRequest(request) {
+    const { method, params, id } = request;
+
+    switch (method) {
+      case "initialize": {
+        const clientVersion = params?.protocolVersion ?? "2024-11-05";
+        const negotiated = SUPPORTED_PROTOCOL_VERSIONS.includes(clientVersion)
+          ? clientVersion
+          : LATEST_PROTOCOL_VERSION;
+        return jsonResponse(id, {
+          protocolVersion: negotiated,
+          capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+          },
+          serverInfo: SERVER_INFO,
+        });
+      }
+
+      case "notifications/initialized":
+      case "notifications/cancelled":
+        return null;
+
+      case "tools/list":
+        return jsonResponse(id, { tools: toolDefinitions() });
+
+      case "tools/call": {
+        const toolName = params?.name;
+        const args = params?.arguments ?? {};
+
+        switch (toolName) {
+          case "list_skills":
+            return jsonResponse(id, makeTextResult(JSON.stringify(listSkills(pluginCatalog), null, 2)));
+
+          case "search_skills": {
+            const results = searchSkills(pluginCatalog, args.query, args.limit);
+            return jsonResponse(id, makeTextResult(JSON.stringify(results, null, 2)));
+          }
+
+          case "get_skill": {
+            const skill = findSkill(pluginCatalog, { name: args.name, uri: args.uri });
+            if (!skill) return jsonError(id, -32602, `Skill not found: ${args.name ?? args.uri}`);
+            return jsonResponse(id, makeTextResult(formatSkill(skill)));
+          }
+
+          case "ask": {
+            const response = buildAskResponse(pluginCatalog, args.question, {
+              includeSkillContent: args.includeSkillContent,
+            });
+            if (!response) return jsonError(id, -32602, "Could not route the question to a skill");
+            return jsonResponse(id, makeTextResult(response));
+          }
+
+          default:
+            return jsonError(id, -32601, `Unknown tool: ${toolName}`);
+        }
+      }
+
+      case "resources/list": {
+        const resources = pluginCatalog.skills.map((s) => ({
+          uri: s.uri,
+          name: s.name,
+          description: s.description,
+          mimeType: "text/markdown",
+        }));
+        return jsonResponse(id, { resources });
+      }
+
+      case "resources/read": {
+        const uri = params?.uri;
+        const skill = findSkill(pluginCatalog, { uri });
+        if (!skill) return jsonError(id, -32602, `Resource not found: ${uri}`);
+        return jsonResponse(id, {
+          contents: [{ uri: skill.uri, mimeType: "text/markdown", text: skill.markdown }],
+        });
+      }
+
+      case "resources/templates/list":
+        return jsonResponse(id, { resourceTemplates: [] });
+
+      case "prompts/list": {
+        const prompts = pluginCatalog.commands.map((c) => ({
+          name: c.name,
+          description: c.description,
+          arguments: c.name === "ask"
+            ? [{ name: "question", description: "SQLiteData question", required: true }]
+            : [{ name: "area", description: "Optional focus area", required: false }],
+        }));
+        return jsonResponse(id, { prompts });
+      }
+
+      case "prompts/get": {
+        const prompt = getPrompt(pluginCatalog, params?.name, params?.arguments ?? {});
+        if (!prompt) return jsonError(id, -32602, `Prompt not found: ${params?.name}`);
+        return jsonResponse(id, prompt);
+      }
+
+      default:
+        return jsonError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  return { handleRequest, pluginCatalog };
+}
+
+// ── stdio transport ─────────────────────────────────────────────────────────
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  const server = createServer();
+  let framing = null; // auto-detect
+  let buffer = "";
+
+  function writeMessage(message) {
+    const payload = JSON.stringify(message);
+    if (framing === "raw-json") {
+      process.stdout.write(`${payload}\n`);
+    } else {
+      process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, "utf8")}\r\n\r\n${payload}`);
+    }
+  }
+
+  function processMessage(text) {
+    let request;
+    try {
+      request = JSON.parse(text);
+    } catch {
+      writeMessage(jsonError(null, -32700, "Parse error"));
+      return;
+    }
+    const response = server.handleRequest(request);
+    if (response) writeMessage(response);
+  }
+
+  function findHeaderBoundary(buf) {
+    const crlf = buf.indexOf("\r\n\r\n");
+    if (crlf !== -1) return { headerEnd: crlf, separatorLength: 4 };
+    const lf = buf.indexOf("\n\n");
+    if (lf !== -1) return { headerEnd: lf, separatorLength: 2 };
+    return null;
+  }
+
+  function drain() {
+    while (buffer.length > 0) {
+      if (framing === null) {
+        // Auto-detect framing from first bytes
+        if (buffer.startsWith("{")) {
+          framing = "raw-json";
+        } else if (buffer.startsWith("Content-Length:") || buffer.startsWith("content-length:")) {
+          framing = "content-length";
+        } else if (buffer.length < 16) {
+          return; // wait for more data
+        } else {
+          framing = "content-length";
+        }
+      }
+
+      if (framing === "raw-json") {
+        const newline = buffer.indexOf("\n");
+        if (newline === -1) {
+          // Try to parse what we have if it's a complete JSON object
+          if (buffer.endsWith("}")) {
+            const text = buffer;
+            buffer = "";
+            processMessage(text);
+            continue;
+          }
+          return;
+        }
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) processMessage(line);
+        continue;
+      }
+
+      // content-length framing
+      const boundary = findHeaderBoundary(buffer);
+      if (!boundary) return;
+
+      const header = buffer.slice(0, boundary.headerEnd);
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) {
+        buffer = buffer.slice(boundary.headerEnd + boundary.separatorLength);
+        continue;
+      }
+
+      const contentLength = parseInt(match[1], 10);
+      const bodyStart = boundary.headerEnd + boundary.separatorLength;
+      if (buffer.length < bodyStart + contentLength) return;
+
+      const body = buffer.slice(bodyStart, bodyStart + contentLength);
+      buffer = buffer.slice(bodyStart + contentLength);
+      processMessage(body);
+    }
+  }
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    drain();
+  });
+}