@tideorg/mcp 1.4.1 → 1.4.2

package/mcp-server/dist/server.js

@@ -0,0 +1,415 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, resolve } from "path";
+// Resolve pack root.
+// - TIDE_PACK_ROOT env var takes priority (custom deployments)
+// - Default: two levels up from dist/ → repo/package root
+const PACK_ROOT = process.env.TIDE_PACK_ROOT
+    ? resolve(process.env.TIDE_PACK_ROOT)
+    : resolve(import.meta.dirname, "..", "..");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function listMarkdownFiles(dir) {
+    const full = join(PACK_ROOT, dir);
+    if (!existsSync(full))
+        return [];
+    return readdirSync(full)
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => f.replace(/\.md$/, ""));
+}
+function listDirectories(dir) {
+    const full = join(PACK_ROOT, dir);
+    if (!existsSync(full))
+        return [];
+    return readdirSync(full, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+}
+function readPackFile(dir, name) {
+    const file = name.endsWith(".md") ? name : `${name}.md`;
+    const full = join(PACK_ROOT, dir, file);
+    if (!existsSync(full))
+        return null;
+    return readFileSync(full, "utf-8");
+}
+function readSkill(name) {
+    const full = join(PACK_ROOT, "skills", name, "SKILL.md");
+    if (!existsSync(full))
+        return null;
+    return readFileSync(full, "utf-8");
+}
+function scenarioExists(scenario) {
+    return existsSync(join(PACK_ROOT, "reference-apps", scenario));
+}
+function readScenarioFile(scenario, fileName) {
+    const full = join(PACK_ROOT, "reference-apps", scenario, fileName);
+    if (!existsSync(full))
+        return null;
+    return readFileSync(full, "utf-8");
+}
+function scenarioKeywordsFromName(name) {
+    return name
+        .toLowerCase()
+        .split(/[-_\s]+/)
+        .filter(Boolean);
+}
+function parseScenarioManifest(raw) {
+    if (!raw)
+        return {};
+    const result = {};
+    const lines = raw.split("\n");
+    let currentListKey = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const keyMatch = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(trimmed);
+        if (keyMatch) {
+            const [, key, value] = keyMatch;
+            if (value === "") {
+                currentListKey = key;
+                result[key] = [];
+            }
+            else {
+                currentListKey = null;
+                result[key] = value.replace(/^["']|["']$/g, "");
+            }
+            continue;
+        }
+        if (currentListKey && trimmed.startsWith("- ")) {
+            const arr = result[currentListKey] ?? [];
+            arr.push(trimmed.replace(/^- /, "").trim());
+            result[currentListKey] = arr;
+        }
+    }
+    return result;
+}
+function textResponse(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResponse(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function formatList(title, items) {
+    return `## ${title}\n${items.length ? items.map((i) => `- ${i}`).join("\n") : "- (none)"}`;
+}
+function getScenarioSummary(scenario) {
+    const manifest = parseScenarioManifest(readScenarioFile(scenario, "manifest.yaml"));
+    const title = typeof manifest.title === "string" ? manifest.title : scenario;
+    const category = typeof manifest.category === "string" ? manifest.category : "uncategorized";
+    const corePatterns = Array.isArray(manifest.core_patterns) ? manifest.core_patterns : [];
+    const defaultPlaybooks = Array.isArray(manifest.default_playbooks) ? manifest.default_playbooks : [];
+    const matchKeywords = Array.isArray(manifest.match_keywords) ? manifest.match_keywords : [];
+    return {
+        scenario,
+        title,
+        category,
+        corePatterns,
+        defaultPlaybooks,
+        matchKeywords,
+        manifest,
+    };
+}
+// Negative signals: if the situation contains these words and the scenario
+// is not the right match, suppress the score.
+const SCENARIO_NEGATIVE_SIGNALS = {
+    "policy-governed-signing": ["ssh", "sign", "signing", "document", "transaction", "certificate"],
+    "git-pr-signing-service": ["git", "commit", "merge", "pr", "pull request", "verified", "github"],
+};
+function scoreScenarioMatch(scenario, situation) {
+    const lower = situation.toLowerCase();
+    const summary = getScenarioSummary(scenario);
+    const manifestKeywords = [
+        scenario,
+        ...scenarioKeywordsFromName(scenario),
+        ...summary.corePatterns.map((p) => String(p).toLowerCase()),
+        ...summary.title.toLowerCase().split(/\s+/),
+        ...summary.category.toLowerCase().split(/\s+/),
+    ];
+    const unique = Array.from(new Set(manifestKeywords.filter(Boolean)));
+    let score = unique.reduce((acc, kw) => acc + (lower.includes(kw) ? 1 : 0), 0);
+    for (const phrase of summary.matchKeywords) {
+        if (lower.includes(String(phrase).toLowerCase())) {
+            score += 3;
+        }
+    }
+    const requiredSignals = SCENARIO_NEGATIVE_SIGNALS[scenario];
+    if (requiredSignals && score > 0) {
+        const hasAnySignal = requiredSignals.some((sig) => lower.includes(sig));
+        if (!hasAnySignal) {
+            score = 0;
+        }
+    }
+    return {
+        ...summary,
+        score,
+    };
+}
+// ---------------------------------------------------------------------------
+// Content catalogs
+// ---------------------------------------------------------------------------
+const CANON_FILES = listMarkdownFiles("canon");
+const PLAYBOOK_FILES = listMarkdownFiles("playbooks");
+const PROMPT_FILES = listMarkdownFiles("prompts");
+const ADAPTER_FILES = listMarkdownFiles("adapters");
+const SKILL_DIRS = listDirectories("skills");
+const REFERENCE_APP_DIRS = listDirectories("reference-apps");
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+export function createServer() {
+    const server = new McpServer({
+        name: "@tideorg/mcp",
+        version: "1.4.1",
+    });
+    // 1. List available content
+    server.tool("tide_list", "List all available content in the Tide agent pack by category", {
+        category: z
+            .enum(["canon", "playbooks", "skills", "prompts", "adapters", "scenarios", "all"])
+            .describe("Which category to list, or 'all' for everything"),
+    }, async ({ category }) => {
+        const sections = {};
+        if (category === "all" || category === "canon")
+            sections.canon = CANON_FILES;
+        if (category === "all" || category === "playbooks")
+            sections.playbooks = PLAYBOOK_FILES;
+        if (category === "all" || category === "skills")
+            sections.skills = SKILL_DIRS;
+        if (category === "all" || category === "prompts")
+            sections.prompts = PROMPT_FILES;
+        if (category === "all" || category === "adapters")
+            sections.adapters = ADAPTER_FILES;
+        if (category === "all" || category === "scenarios")
+            sections.scenarios = REFERENCE_APP_DIRS;
+        const text = Object.entries(sections)
+            .map(([cat, items]) => formatList(cat, items))
+            .join("\n\n");
+        return textResponse(text);
+    });
+    // 2. Read a specific canon file
+    server.tool("tide_canon", "Read a canon file (invariants, anti-patterns, concepts, framework-matrix, feature-mapping, troubleshooting, tidecloak-bootstrap, etc.)", { name: z.string().describe(`Canon file name. Available: ${CANON_FILES.join(", ")}`) }, async ({ name }) => {
+        const content = readPackFile("canon", name);
+        if (!content)
+            return errorResponse(`Canon file '${name}' not found. Available: ${CANON_FILES.join(", ")}`);
+        return textResponse(content);
+    });
+    // 3. Read a playbook
+    server.tool("tide_playbook", "Read a step-by-step playbook for a specific Tide task", { name: z.string().describe(`Playbook name. Available: ${PLAYBOOK_FILES.join(", ")}`) }, async ({ name }) => {
+        const content = readPackFile("playbooks", name);
+        if (!content)
+            return errorResponse(`Playbook '${name}' not found. Available: ${PLAYBOOK_FILES.join(", ")}`);
+        return textResponse(content);
+    });
+    // 4. Read a skill
+    server.tool("tide_skill", "Read a composable skill definition", { name: z.string().describe(`Skill name. Available: ${SKILL_DIRS.join(", ")}`) }, async ({ name }) => {
+        const content = readSkill(name);
+        if (!content)
+            return errorResponse(`Skill '${name}' not found. Available: ${SKILL_DIRS.join(", ")}`);
+        return textResponse(content);
+    });
+    // 5. Read a prompt file
+    server.tool("tide_prompt", "Read a reusable starter prompt from the pack", { name: z.string().describe(`Prompt file name. Available: ${PROMPT_FILES.join(", ")}`) }, async ({ name }) => {
+        const content = readPackFile("prompts", name);
+        if (!content)
+            return errorResponse(`Prompt '${name}' not found. Available: ${PROMPT_FILES.join(", ")}`);
+        return textResponse(content);
+    });
+    // 6. Read an adapter file
+    server.tool("tide_adapter", "Read an adapter instruction file (AGENTS, CLAUDE, replit)", { name: z.string().describe(`Adapter file name. Available: ${ADAPTER_FILES.join(", ")}`) }, async ({ name }) => {
+        const content = readPackFile("adapters", name);
+        if (!content)
+            return errorResponse(`Adapter '${name}' not found. Available: ${ADAPTER_FILES.join(", ")}`);
+        return textResponse(content);
+    });
+    // 7. List available scenarios
+    server.tool("tide_list_scenarios", "List all available scenario patterns under reference-apps/", async () => {
+        if (REFERENCE_APP_DIRS.length === 0)
+            return textResponse("No scenarios found under reference-apps/");
+        const lines = REFERENCE_APP_DIRS.map((name) => {
+            const summary = getScenarioSummary(name);
+            return `- ${summary.scenario} — ${summary.title} [${summary.category}]`;
+        });
+        return textResponse(`Available scenarios:\n\n${lines.join("\n")}`);
+    });
+    // 8. Read scenario summary
+    server.tool("tide_scenario", "Read a scenario summary from reference-apps/<scenario>/scenario.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+        if (!scenarioExists(name))
+            return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
+        const scenarioContent = readScenarioFile(name, "scenario.md");
+        if (!scenarioContent)
+            return errorResponse(`Scenario '${name}' exists but scenario.md is missing.`);
+        const antiPatterns = readScenarioFile(name, "anti-patterns.md");
+        const text = antiPatterns ? `${scenarioContent}\n\n---\n\n## Anti-patterns\n\n${antiPatterns}` : scenarioContent;
+        return textResponse(text);
+    });
+    // 9. Read scenario manifest
+    server.tool("tide_scenario_manifest", "Read a scenario manifest from reference-apps/<scenario>/manifest.yaml", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+        if (!scenarioExists(name))
+            return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
+        const content = readScenarioFile(name, "manifest.yaml");
+        if (!content)
+            return errorResponse(`Scenario '${name}' exists but manifest.yaml is missing.`);
+        return textResponse(content);
+    });
+    // 10. Read scenario role/policy matrix
+    server.tool("tide_scenario_roles", "Read a scenario role-policy matrix from reference-apps/<scenario>/role-policy-matrix.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+        if (!scenarioExists(name))
+            return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
+        const content = readScenarioFile(name, "role-policy-matrix.md");
+        if (!content)
+            return errorResponse(`Scenario '${name}' exists but role-policy-matrix.md is missing.`);
+        return textResponse(content);
+    });
+    // 11. Read scenario bootstrap sequence
+    server.tool("tide_scenario_bootstrap", "Read a scenario bootstrap sequence from reference-apps/<scenario>/bootstrap-sequence.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+        if (!scenarioExists(name))
+            return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
+        const content = readScenarioFile(name, "bootstrap-sequence.md");
+        if (!content)
+            return errorResponse(`Scenario '${name}' exists but bootstrap-sequence.md is missing.`);
+        return textResponse(content);
+    });
+    // 12. Choose best matching scenario
+    server.tool("tide_choose_scenario", "Match a user request to a known scenario pattern before falling back to generic playbooks", { situation: z.string().describe("Describe the app or problem, e.g. 'build an organisation password manager'") }, async ({ situation }) => {
+        const matches = REFERENCE_APP_DIRS
+            .map((scenario) => scoreScenarioMatch(scenario, situation))
+            .filter((m) => m.score > 0)
+            .sort((a, b) => b.score - a.score);
+        if (matches.length === 0) {
+            return textResponse(`No scenario match for "${situation}". Available scenarios:\n${REFERENCE_APP_DIRS.map((s) => `- ${s}`).join("\n")}`);
+        }
+        const best = matches[0];
+        const second = matches.length > 1 ? matches[1] : null;
+        const autoSelect = best.score >= 6 && (!second || best.score - second.score >= 3);
+        const closeMatches = autoSelect ? [best] : matches.filter((m) => m.score >= best.score * 0.6 && m.score > 0);
+        if (closeMatches.length > 1) {
+            const lines = closeMatches.map((m) => {
+                const dq = typeof m.manifest.discriminating_question === "string" ? m.manifest.discriminating_question : "";
+                return `- **${m.scenario}** (${m.title}, score ${m.score})${dq ? `\n  Disambiguate: ${dq}` : ""}`;
+            });
+            return textResponse([
+                `Multiple scenarios match "${situation}" (I-17 — resolve before proceeding):`,
+                "", ...lines, "",
+                `Resolve the ambiguity before selecting a playbook path.`,
+            ].join("\n"));
+        }
+        const defaultPlaybooks = best.defaultPlaybooks;
+        return textResponse([
+            `Best scenario match: ${best.scenario}`,
+            `Title: ${best.title}`,
+            `Category: ${best.category}`,
+            defaultPlaybooks.length
+                ? `Default playbooks:\n${defaultPlaybooks.map((p) => `- ${p}`).join("\n")}`
+                : `Default playbooks: not declared in manifest.yaml`,
+            `Use tide_scenario_manifest, tide_scenario_roles, and tide_scenario_bootstrap for scenario-specific details.`,
+        ].join("\n\n"));
+    });
+    // 13. Recommend the right playbook
+    server.tool("tide_choose_playbook", "Recommend the right playbook for a given situation", { situation: z.string().describe("Describe what the builder wants to do, e.g. 'add login to a new Next.js app'") }, async ({ situation }) => {
+        const lower = situation.toLowerCase();
+        const scenarioMatches = REFERENCE_APP_DIRS
+            .map((scenario) => scoreScenarioMatch(scenario, situation))
+            .filter((m) => m.score > 0)
+            .sort((a, b) => b.score - a.score);
+        if (scenarioMatches.length > 0) {
+            const best = scenarioMatches[0];
+            const closeMatches = scenarioMatches.filter((m) => m.score >= best.score * 0.6 && m.score > 0);
+            if (closeMatches.length > 1) {
+                const lines = closeMatches.map((m) => {
+                    const dq = typeof m.manifest.discriminating_question === "string" ? m.manifest.discriminating_question : "";
+                    return `- **${m.scenario}** (score ${m.score})${dq ? ` — ${dq}` : ""}`;
+                });
+                return textResponse([
+                    `Multiple scenarios match (I-17 — resolve before proceeding):`,
+                    ...lines, ``, `Resolve the ambiguity before selecting a playbook path.`,
+                ].join("\n"));
+            }
+            const defaultPlaybooks = best.defaultPlaybooks;
+            return textResponse([
+                `Scenario match: ${best.scenario}`,
+                defaultPlaybooks.length
+                    ? `Recommended playbook sequence:\n${defaultPlaybooks.map((p) => `- ${p}`).join("\n")}`
+                    : `Scenario matched, but manifest.yaml does not declare default_playbooks.`,
+                `Use tide_scenario_manifest, tide_scenario_roles, and tide_scenario_bootstrap for scenario-specific details.`,
+            ].join("\n\n"));
+        }
+        const matches = [];
+        const rules = [
+            { keywords: ["new", "fresh", "setup", "add login", "add auth", "from scratch"], name: "add-auth-nextjs-fresh", reason: "New app needs Tide auth from scratch" },
+            { keywords: ["existing", "retrofit", "already has", "migrate"], name: "add-auth-nextjs-existing", reason: "Existing app needs Tide added" },
+            { keywords: ["route", "page guard", "redirect", "protect page"], name: "protect-routes-nextjs", reason: "Client-side route protection (UI gating)" },
+            { keywords: ["api", "endpoint", "server", "protect api", "backend"], name: "protect-api-nextjs", reason: "Server-side API protection" },
+            { keywords: ["jwt", "dpop", "verify", "token"], name: "verify-jwt-server-side", reason: "Complete JWT + DPoP verification" },
+            { keywords: ["rbac", "role", "permission", "admin", "access control"], name: "add-rbac-nextjs", reason: "Role-based access control" },
+            { keywords: ["login broken", "hang", "stuck", "blank", "csp"], name: "diagnose-broken-login", reason: "Login diagnostics" },
+            { keywords: ["role missing", "claim", "no role", "token empty"], name: "diagnose-missing-roles-or-claims", reason: "Missing roles/claims diagnostics" },
+            { keywords: ["deploy", "docker", "container", "tidecloak"], name: "deploy-tidecloak-docker", reason: "Deploy TideCloak instance" },
+            { keywords: ["e2ee", "encrypt", "decrypt", "forseti", "vault", "share", "sharing", "shared"], name: "setup-forseti-e2ee", reason: "End-to-end encryption setup" },
+            { keywords: ["iga", "approval", "governance", "admin panel"], name: "setup-iga-admin-panel", reason: "IGA admin panel setup" },
+            { keywords: ["bootstrap", "realm", "init", "initialize"], name: "bootstrap-realm-from-template", reason: "Bootstrap realm from template" },
+            { keywords: ["start", "run tidecloak", "launch"], name: "start-tidecloak-dev", reason: "Start TideCloak dev instance" },
+        ];
+        for (const rule of rules) {
+            if (rule.keywords.some((kw) => lower.includes(kw))) {
+                matches.push({ name: rule.name, reason: rule.reason });
+            }
+        }
+        if (matches.length === 0) {
+            return textResponse(`No exact scenario or playbook match for "${situation}". Available playbooks:\n${PLAYBOOK_FILES.map((p) => `- ${p}`).join("\n")}\n\nAvailable scenarios:\n${REFERENCE_APP_DIRS.map((s) => `- ${s}`).join("\n")}\n\nFor a new app, the standard sequence is:\n1. add-auth-nextjs-fresh\n2. protect-routes-nextjs\n3. protect-api-nextjs\n4. verify-jwt-server-side\n5. add-rbac-nextjs`);
+        }
+        const text = matches.map((m) => `**${m.name}** — ${m.reason}`).join("\n");
+        return textResponse(`Recommended playbook(s):\n\n${text}`);
+    });
+    // 14. Read the gap register
+    server.tool("tide_gaps", "Read the gap register — what is still uncertain or unresolved in the pack", async () => {
+        const full = join(PACK_ROOT, "GAP_REGISTER.md");
+        if (!existsSync(full))
+            return errorResponse("GAP_REGISTER.md not found");
+        return textResponse(readFileSync(full, "utf-8"));
+    });
+    // -------------------------------------------------------------------------
+    // Prompts
+    // -------------------------------------------------------------------------
+    server.prompt("tide-build-app", "Start building a Tide-protected app from scratch", { framework: z.enum(["nextjs", "react-vite", "vanilla"]).describe("Target framework") }, async ({ framework }) => {
+        const adapterContent = readPackFile("adapters", "AGENTS") ?? "";
+        const invariantsContent = readPackFile("canon", "invariants") ?? "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `I want to build a new ${framework} app with Tide authentication, authorization, and encryption.\n\nHere are the operational instructions you must follow:\n\n${adapterContent}\n\n---\n\nHere are the security invariants you must never violate:\n\n${invariantsContent}\n\nIf the request matches a known app pattern, start with tide_choose_scenario. Otherwise use tide_choose_playbook. Then follow the resulting bootstrap and playbook path step by step.`,
+                    },
+                }],
+        };
+    });
+    server.prompt("tide-secure-existing", "Add Tide to an existing app", async () => {
+        const promptContent = readPackFile("prompts", "secure-existing-app") ?? "";
+        return { messages: [{ role: "user", content: { type: "text", text: promptContent } }] };
+    });
+    server.prompt("tide-build-from-scenario", "Start building a Tide app from a known scenario pattern", {
+        scenario: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`),
+        framework: z.enum(["nextjs", "react-vite", "vanilla"]).describe("Target framework"),
+    }, async ({ scenario, framework }) => {
+        if (!scenarioExists(scenario))
+            throw new Error(`Scenario '${scenario}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
+        const adapterContent = readPackFile("adapters", "AGENTS") ?? "";
+        const invariantsContent = readPackFile("canon", "invariants") ?? "";
+        const scenarioContent = readScenarioFile(scenario, "scenario.md") ?? "";
+        const manifestContent = readScenarioFile(scenario, "manifest.yaml") ?? "";
+        const rolesContent = readScenarioFile(scenario, "role-policy-matrix.md") ?? "";
+        const bootstrapContent = readScenarioFile(scenario, "bootstrap-sequence.md") ?? "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `I want to build a ${framework} Tide app using the scenario pattern '${scenario}'.\n\nFollow these adapter instructions first:\n\n${adapterContent}\n\n---\n\nSecurity invariants:\n\n${invariantsContent}\n\n---\n\nScenario summary:\n\n${scenarioContent}\n\n---\n\nScenario manifest:\n\n${manifestContent}\n\n---\n\nRole and policy matrix:\n\n${rolesContent}\n\n---\n\nBootstrap sequence:\n\n${bootstrapContent}\n\nStart by honoring the scenario bootstrap and role/policy requirements before falling back to generic playbook selection.`,
+                    },
+                }],
+        };
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tideorg/mcp",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "MCP server exposing Tide operational guidance — canon, playbooks, skills, prompts, adapters, and scenarios for AI coding agents",
   "type": "module",
   "bin": {