@spec-r/mcp-server 0.3.0

package/dist/index.js

@@ -0,0 +1,1637 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api-client.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function assertId(value, label) {
+  if (!UUID_RE.test(value)) {
+    throw new Error(`Invalid ${label}: must be a UUID`);
+  }
+}
+
+class SpecRApiClient {
+  apiKey;
+  baseUrl;
+  defaultProjectId;
+  constructor(config) {
+    const parsed = new URL(config.baseUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("SPECR_BASE_URL must use http or https");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.defaultProjectId = config.defaultProjectId;
+  }
+  async request(path, init) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const controller = new AbortController;
+    const timeout = setTimeout(() => controller.abort(), 30000);
+    const res = await fetch(url, {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...init?.headers
+      }
+    }).finally(() => clearTimeout(timeout));
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`spec-r API error (${res.status}): ${body}`);
+    }
+    const contentType = res.headers.get("content-type") || "";
+    if (contentType.includes("text/markdown")) {
+      return await res.text();
+    }
+    return res.json();
+  }
+  async listProjects() {
+    return this.request("/projects");
+  }
+  async createProject(data) {
+    return this.request("/projects", {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async updateProject(projectId, data) {
+    assertId(projectId, "projectId");
+    return this.request(`/projects/${projectId}`, {
+      method: "PUT",
+      body: JSON.stringify(data)
+    });
+  }
+  async listSpecs(projectId) {
+    assertId(projectId, "projectId");
+    return this.request(`/projects/${projectId}/specs`);
+  }
+  async getSpec(specId, format = "json") {
+    assertId(specId, "specId");
+    if (format === "json") {
+      return this.request(`/specs/${specId}?format=json`);
+    }
+    return this.request(`/specs/${specId}?format=${format}`);
+  }
+  async searchSpecs(query, projectId) {
+    const params = new URLSearchParams({ q: query });
+    if (projectId)
+      params.set("projectId", projectId);
+    return this.request(`/search?${params}`);
+  }
+  async getImplementationStatus(specId) {
+    assertId(specId, "specId");
+    return this.request(`/specs/${specId}/implementation`);
+  }
+  async updateImplementationStatus(specId, stepIndex, status, extra) {
+    assertId(specId, "specId");
+    return this.request(`/specs/${specId}/implementation`, {
+      method: "PUT",
+      body: JSON.stringify({ stepIndex, status, ...extra })
+    });
+  }
+  async publish(projectId, spec, blocks) {
+    assertId(projectId, "projectId");
+    return this.request("/publish", {
+      method: "POST",
+      body: JSON.stringify({ projectId, spec, blocks })
+    });
+  }
+  async createSpec(projectId, data) {
+    assertId(projectId, "projectId");
+    return this.request(`/projects/${projectId}/specs`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async addBlock(specId, block) {
+    assertId(specId, "specId");
+    return this.request(`/specs/${specId}/blocks`, {
+      method: "POST",
+      body: JSON.stringify(block)
+    });
+  }
+  async updateBlock(specId, blockId, content) {
+    assertId(specId, "specId");
+    assertId(blockId, "blockId");
+    return this.request(`/specs/${specId}/blocks/${blockId}`, {
+      method: "PUT",
+      body: JSON.stringify({ content })
+    });
+  }
+  async updateSpec(specId, data) {
+    assertId(specId, "specId");
+    return this.request(`/specs/${specId}`, {
+      method: "PUT",
+      body: JSON.stringify(data)
+    });
+  }
+  async deleteBlock(specId, blockId) {
+    assertId(specId, "specId");
+    assertId(blockId, "blockId");
+    return this.request(`/specs/${specId}/blocks/${blockId}`, {
+      method: "DELETE"
+    });
+  }
+  async analyzeScreenshot(projectId, image, options) {
+    assertId(projectId, "projectId");
+    return this.request("/analyze-screenshot", {
+      method: "POST",
+      body: JSON.stringify({
+        projectId,
+        image,
+        additionalContext: options?.additionalContext,
+        enableGrouping: options?.enableGrouping ?? false
+      })
+    });
+  }
+  async analyzeFeedback(projectId, feedback) {
+    assertId(projectId, "projectId");
+    return this.request("/analyze-feedback", {
+      method: "POST",
+      body: JSON.stringify({ projectId, feedback })
+    });
+  }
+  async listResources(projectId, type) {
+    assertId(projectId, "projectId");
+    const params = type ? `?type=${encodeURIComponent(type)}` : "";
+    return this.request(`/projects/${projectId}/resources${params}`);
+  }
+  async getResource(projectId, resourceId) {
+    assertId(projectId, "projectId");
+    assertId(resourceId, "resourceId");
+    return this.request(`/projects/${projectId}/resources/${resourceId}`);
+  }
+  async createResource(projectId, data) {
+    assertId(projectId, "projectId");
+    return this.request(`/projects/${projectId}/resources`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async updateResource(projectId, resourceId, data) {
+    assertId(projectId, "projectId");
+    assertId(resourceId, "resourceId");
+    return this.request(`/projects/${projectId}/resources/${resourceId}`, {
+      method: "PUT",
+      body: JSON.stringify(data)
+    });
+  }
+  async deleteResource(projectId, resourceId) {
+    assertId(projectId, "projectId");
+    assertId(resourceId, "resourceId");
+    return this.request(`/projects/${projectId}/resources/${resourceId}`, {
+      method: "DELETE"
+    });
+  }
+}
+
+// src/tools/read-tools.ts
+import { z } from "zod";
+
+// src/constants.ts
+var CHARACTER_LIMIT = 25000;
+function handleApiError(error) {
+  if (error instanceof Error) {
+    const msg = error.message;
+    if (msg.includes("(404)") || msg.includes("error (404)"))
+      return "Error: Resource not found. Check the ID is correct.";
+    if (msg.includes("(403)") || msg.includes("error (403)"))
+      return "Error: Permission denied.";
+    if (msg.includes("(429)") || msg.includes("error (429)"))
+      return "Error: Rate limit exceeded. Please wait before retrying.";
+    if (msg.includes("abort") || msg.includes("timeout"))
+      return "Error: Request timed out. Please try again.";
+    return `Error: ${msg}`;
+  }
+  return `Error: ${String(error)}`;
+}
+
+// src/tools/read-tools.ts
+function registerReadTools(server, client) {
+  server.registerTool("list_specs", {
+    title: "List Specs",
+    description: [
+      "List all specifications in a project.",
+      "",
+      "Args:",
+      "  projectId (optional) — Project UUID. Falls back to the default project configured via SPECR_PROJECT_ID.",
+      "",
+      "Returns:",
+      "  A bullet list of specs with title, type, status, and ID.",
+      "",
+      "Examples:",
+      "  list_specs()  — lists specs in the default project",
+      '  list_specs({ projectId: "uuid" })  — lists specs in a specific project'
+    ].join(`
+`),
+    inputSchema: z.object({
+      projectId: z.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ projectId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return {
+        content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }]
+      };
+    }
+    try {
+      const specs = await client.listSpecs(pid);
+      const text = specs.length === 0 ? "No specs found in this project." : specs.map((s) => `- **${s.title}** (${s.type}) [${s.status}] — ID: ${s.id}`).join(`
+`);
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("get_spec", {
+    title: "Get Spec",
+    description: [
+      "Get a full specification in agent-optimized format.",
+      "Returns implementation-ready markdown with data models, API endpoints, components, and implementation plan.",
+      "",
+      "Args:",
+      "  specId — UUID of the spec to retrieve.",
+      '  format (optional, default "agent") — Output format:',
+      '    "agent"    — optimized markdown for AI implementation (default)',
+      '    "markdown" — standard markdown',
+      '    "json"     — raw JSON with spec metadata and blocks array',
+      "",
+      "Returns:",
+      "  The spec content in the requested format.",
+      '  When format is "json", also returns structuredContent with the parsed data.',
+      "",
+      "Examples:",
+      '  get_spec({ specId: "uuid" })  — fetch in agent format',
+      '  get_spec({ specId: "uuid", format: "json" })  — fetch raw JSON'
+    ].join(`
+`),
+    inputSchema: z.object({
+      specId: z.string().describe("The spec ID to retrieve"),
+      format: z.enum(["agent", "markdown", "json"]).optional().default("agent").describe('Output format. "agent" is optimized for AI implementation.')
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ specId, format }) => {
+    try {
+      if (format === "json") {
+        const data = await client.getSpec(specId, "json");
+        const text = JSON.stringify(data, null, 2);
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: data
+        };
+      }
+      const markdown = await client.getSpec(specId, format ?? "agent");
+      return { content: [{ type: "text", text: markdown }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("search_specs", {
+    title: "Search Specs",
+    description: [
+      "Search across all specifications and blocks. Finds specs by title or block content.",
+      "",
+      "Args:",
+      "  query     — Search string.",
+      "  projectId (optional) — Limit search to a specific project UUID.",
+      "",
+      "Returns:",
+      "  Matching specs (title, type, status, ID, project) and matching blocks (type, spec title, spec ID).",
+      `  Output is capped at ${CHARACTER_LIMIT} characters.`,
+      "",
+      "Examples:",
+      '  search_specs({ query: "authentication" })',
+      '  search_specs({ query: "user", projectId: "uuid" })'
+    ].join(`
+`),
+    inputSchema: z.object({
+      query: z.string().describe("Search query"),
+      projectId: z.string().optional().describe("Limit search to a specific project")
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ query, projectId }) => {
+    try {
+      const pid = projectId || client.defaultProjectId;
+      const { results } = await client.searchSpecs(query, pid);
+      const lines = [];
+      if (results.specs.length > 0) {
+        lines.push("**Matching Specs:**");
+        results.specs.forEach((s) => {
+          lines.push(`- ${s.specTitle} (${s.specType}) [${s.specStatus}] — ID: ${s.specId} — Project: ${s.projectName}`);
+        });
+      }
+      if (results.blocks.length > 0) {
+        lines.push("");
+        lines.push("**Matching Blocks:**");
+        results.blocks.forEach((b) => {
+          lines.push(`- [${b.blockType}] in "${b.specTitle}" — Spec ID: ${b.specId}`);
+        });
+      }
+      if (lines.length === 0) {
+        lines.push(`No results found for "${query}"`);
+      }
+      const text = lines.join(`
+`);
+      if (text.length > CHARACTER_LIMIT) {
+        return {
+          content: [{ type: "text", text: text.slice(0, CHARACTER_LIMIT) + `
+
+[Output truncated at character limit]` }]
+        };
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("list_projects", {
+    title: "List Projects",
+    description: [
+      "List all projects accessible with the current API key.",
+      "Use this to discover project IDs when SPECR_PROJECT_ID is not configured.",
+      "",
+      "Args:",
+      "  (none)",
+      "",
+      "Returns:",
+      "  A bullet list of projects with name, ID, industry, and business model.",
+      "",
+      "Examples:",
+      "  list_projects()  — discover available projects and their UUIDs"
+    ].join(`
+`),
+    inputSchema: z.object({}).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async () => {
+    try {
+      const projects = await client.listProjects();
+      if (projects.length === 0) {
+        return { content: [{ type: "text", text: "No projects found." }] };
+      }
+      const text = projects.map((p) => {
+        const meta = [p.industry, p.businessModel].filter(Boolean).join(", ");
+        return `- **${p.name}** — ID: ${p.id}${meta ? ` (${meta})` : ""}`;
+      }).join(`
+`);
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("get_project_context", {
+    title: "Get Project Context",
+    description: [
+      "Get project context including tech stack, industry, and conventions.",
+      "Useful for understanding the technical environment before implementing specs.",
+      "",
+      "Args:",
+      "  projectId (optional) — Project UUID. Falls back to the default project, or the first project.",
+      "",
+      "Returns:",
+      "  Project name, description, industry, business model, and tech stack (frontend, backend, database, infra).",
+      "",
+      "Examples:",
+      "  get_project_context()  — context for the default project",
+      '  get_project_context({ projectId: "uuid" })'
+    ].join(`
+`),
+    inputSchema: z.object({
+      projectId: z.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ projectId }) => {
+    try {
+      const projects = await client.listProjects();
+      const pid = projectId || client.defaultProjectId;
+      const project = pid ? projects.find((p) => p.id === pid) : projects[0];
+      if (!project) {
+        return { content: [{ type: "text", text: "Project not found" }] };
+      }
+      const lines = [
+        `# ${project.name}`,
+        "",
+        project.description || "",
+        ""
+      ];
+      if (project.industry)
+        lines.push(`- **Industry:** ${project.industry}`);
+      if (project.businessModel)
+        lines.push(`- **Business Model:** ${project.businessModel}`);
+      if (project.techStack) {
+        const ts = project.techStack;
+        lines.push("");
+        lines.push("**Tech Stack:**");
+        if (ts.frontend?.length)
+          lines.push(`- Frontend: ${ts.frontend.join(", ")}`);
+        if (ts.backend?.length)
+          lines.push(`- Backend: ${ts.backend.join(", ")}`);
+        if (ts.database?.length)
+          lines.push(`- Database: ${ts.database.join(", ")}`);
+        if (ts.infra?.length)
+          lines.push(`- Infra: ${ts.infra.join(", ")}`);
+      }
+      return { content: [{ type: "text", text: lines.join(`
+`) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("get_data_models", {
+    title: "Get Data Models",
+    description: [
+      "Get all data models defined across specs in a project.",
+      "Returns entity names, fields (name, type, required), and relations.",
+      "",
+      "Args:",
+      "  projectId (optional) — Project UUID. Falls back to the default project.",
+      "",
+      "Returns:",
+      "  Markdown tables for each data_model block found across all specs.",
+      `  Output is capped at ${CHARACTER_LIMIT} characters.`,
+      "",
+      "Examples:",
+      "  get_data_models()  — all models in the default project",
+      '  get_data_models({ projectId: "uuid" })'
+    ].join(`
+`),
+    inputSchema: z.object({
+      projectId: z.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ projectId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return {
+        content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }]
+      };
+    }
+    try {
+      const specs = await client.listSpecs(pid);
+      const specData = await Promise.all(specs.map((spec) => client.getSpec(spec.id, "json").then((data) => ({ spec, data }))));
+      const models = ["# Data Models", ""];
+      for (const { spec, data } of specData) {
+        const dataModelBlocks = data.blocks.filter((b) => b.type === "data_model");
+        for (const block of dataModelBlocks) {
+          const c = block.content;
+          const fields = c.fields || [];
+          const relations = c.relations || [];
+          models.push(`## ${c.entityName} (from "${spec.title}")`);
+          if (c.description)
+            models.push(c.description);
+          models.push("");
+          if (fields.length > 0) {
+            models.push("| Field | Type | Required |");
+            models.push("|-------|------|----------|");
+            fields.forEach((f) => {
+              models.push(`| ${f.name} | ${f.type} | ${f.required ? "Yes" : "No"} |`);
+            });
+            models.push("");
+          }
+          if (relations.length > 0) {
+            models.push("**Relations:**");
+            relations.forEach((r) => models.push(`- ${r.type} → ${r.target}`));
+            models.push("");
+          }
+        }
+      }
+      if (models.length === 2) {
+        return { content: [{ type: "text", text: "No data models found in this project." }] };
+      }
+      const text = models.join(`
+`);
+      if (text.length > CHARACTER_LIMIT) {
+        return {
+          content: [{ type: "text", text: text.slice(0, CHARACTER_LIMIT) + `
+
+[Output truncated at character limit]` }]
+        };
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+}
+
+// src/tools/write-tools.ts
+import { z as z2 } from "zod";
+function registerWriteTools(server, client) {
+  const techStackSchema = z2.object({
+    frontend: z2.array(z2.string()).optional().describe('e.g. ["Next.js", "React"]'),
+    mobile: z2.array(z2.string()).optional().describe('e.g. ["React Native", "Expo"]'),
+    backend: z2.array(z2.string()).optional().describe('e.g. ["Node.js", "Go"]'),
+    database: z2.array(z2.string()).optional().describe('e.g. ["PostgreSQL", "Redis"]'),
+    infra: z2.array(z2.string()).optional().describe('e.g. ["Vercel", "AWS"]'),
+    auth: z2.array(z2.string()).optional().describe('e.g. ["Email/Password", "OAuth / Social"]'),
+    deployment: z2.array(z2.string()).optional(),
+    integrations: z2.array(z2.string()).optional().describe('e.g. ["Stripe", "Resend", "PostHog"]')
+  });
+  const conventionsSchema = z2.object({
+    keyFeatures: z2.string().optional().describe("Main features the product needs"),
+    targetAudience: z2.string().optional().describe("Who the product is for"),
+    competitors: z2.array(z2.string()).optional().describe('Reference products (e.g. ["Notion", "Linear"])'),
+    projectPhase: z2.enum(["ideation", "mvp", "scaling", "maintenance"]).optional(),
+    teamSize: z2.enum(["solo", "small", "medium", "large"]).optional(),
+    timeline: z2.string().optional(),
+    constraints: z2.array(z2.string()).optional(),
+    codingStyle: z2.string().optional(),
+    designSystem: z2.string().optional()
+  });
+  server.registerTool("create_project", {
+    title: "Create Project",
+    description: [
+      "Create a new spec-r project — equivalent to the web wizard.",
+      "Provide as much context as possible: tech stack and conventions help AI generate more relevant specs.",
+      "",
+      "Args:",
+      "  name         — Project name (required).",
+      "  description  — What it does, who it is for, what problem it solves.",
+      '  industry     — e.g. "SaaS", "Fintech", "EdTech".',
+      "  businessModel — B2B | B2C | B2B2C.",
+      "  techStack    — Object with frontend/mobile/backend/database/infra/auth/integrations arrays.",
+      "  conventions  — Object with keyFeatures, targetAudience, competitors, projectPhase, teamSize, etc.",
+      "",
+      "Returns:",
+      "  Project ID — save it as SPECR_PROJECT_ID for subsequent spec operations.",
+      "",
+      "Example:",
+      '  create_project({ name: "Lumo", description: "Gamified fragrance tracker",',
+      '    industry: "SaaS", businessModel: "B2C",',
+      '    techStack: { frontend: ["Next.js"], database: ["PostgreSQL", "Supabase"] },',
+      '    conventions: { projectPhase: "mvp", targetAudience: "Fragrance collectors 18-45" } })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      name: z2.string().max(100).describe("Project name"),
+      description: z2.string().max(2000).optional().describe("What it does, who it is for"),
+      industry: z2.string().max(100).optional().describe("e.g. SaaS, Fintech, EdTech"),
+      businessModel: z2.enum(["B2B", "B2C", "B2B2C"]).optional(),
+      techStack: techStackSchema.optional(),
+      conventions: conventionsSchema.optional()
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ name, description, industry, businessModel, techStack, conventions }) => {
+    try {
+      const project = await client.createProject({ name, description, industry, businessModel, techStack, conventions });
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Project "${project.name}" created.`,
+            `- Project ID: ${project.id}`,
+            `- Set SPECR_PROJECT_ID=${project.id} or pass projectId to spec tools.`
+          ].join(`
+`)
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("update_project", {
+    title: "Update Project",
+    description: [
+      "Update an existing project's metadata: name, description, industry, tech stack, or conventions.",
+      "Use this to enrich project context after creation, or to update the tech stack as it evolves.",
+      "",
+      "Args:",
+      "  projectId    — Project UUID (required).",
+      "  name         — New project name.",
+      "  description  — Updated description.",
+      "  industry     — Updated industry.",
+      "  businessModel — B2B | B2C | B2B2C.",
+      "  techStack    — Updated tech stack (replaces existing).",
+      "  conventions  — Updated conventions (replaces existing).",
+      "",
+      "Returns:",
+      "  Confirmation with project ID."
+    ].join(`
+`),
+    inputSchema: z2.object({
+      projectId: z2.string().describe("Project UUID to update"),
+      name: z2.string().max(100).optional(),
+      description: z2.string().max(2000).optional(),
+      industry: z2.string().max(100).optional(),
+      businessModel: z2.enum(["B2B", "B2C", "B2B2C"]).optional(),
+      techStack: techStackSchema.optional(),
+      conventions: conventionsSchema.optional()
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ projectId, name, description, industry, businessModel, techStack, conventions }) => {
+    try {
+      const project = await client.updateProject(projectId, { name, description, industry, businessModel, techStack, conventions });
+      return {
+        content: [{ type: "text", text: `Project "${project.name}" (${project.id}) updated.` }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("publish_spec", {
+    title: "Publish Spec",
+    description: [
+      "Publish a complete spec (create or update by title). This is the primary tool for creating specs — provide all blocks at once.",
+      "If a spec with the same title already exists in the project, it will be updated (blocks replaced).",
+      "",
+      "Read the resource spec-r://block-types first to get the exact content schema for each block type.",
+      "",
+      "Args:",
+      "  title     — Spec title (used to detect duplicates).",
+      "  type      — Spec type: prd | full | feature | epic | bug-fix.",
+      '  status    (optional, default "draft") — draft | review | approved.',
+      "  blocks    — Array of block objects, each with { type, content, position }.",
+      "  projectId (optional) — Project UUID. Falls back to the default project.",
+      "",
+      "Returns:",
+      "  Spec ID, action (created/updated), and block count.",
+      "",
+      "Examples:",
+      '  publish_spec({ title: "Auth flow", type: "feature", blocks: [...] })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      title: z2.string().describe("Spec title"),
+      type: z2.enum(["prd", "full", "feature", "epic", "bug-fix"]).describe("Spec type"),
+      status: z2.enum(["draft", "review", "approved"]).optional().default("draft").describe("Spec status"),
+      blocks: z2.array(z2.object({
+        type: z2.string().describe("Block type (heading, text, user_story, api_endpoint, data_model, etc.)"),
+        content: z2.record(z2.string(), z2.any()).describe("Block content object matching the block type schema"),
+        position: z2.number().describe("Block position (0-based)")
+      })).describe("Array of blocks that make up the spec"),
+      projectId: z2.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ title, type, status, blocks, projectId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    }
+    try {
+      const result = await client.publish(pid, { title, type, status }, blocks);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Spec "${title}" ${result.action} successfully.
+- Spec ID: ${result.specId}
+- Blocks: ${result.blocksCount}`
+          }
+        ]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("create_spec", {
+    title: "Create Spec",
+    description: [
+      "Create a new empty spec (without blocks).",
+      "Use add_block to add blocks afterwards, or use publish_spec to create a spec with blocks in one step.",
+      "",
+      "Args:",
+      "  title     — Spec title.",
+      "  type      — Spec type: prd | full | feature | epic | bug-fix.",
+      '  status    (optional, default "draft") — draft | review | approved.',
+      "  projectId (optional) — Project UUID. Falls back to the default project.",
+      "",
+      "Returns:",
+      "  Spec ID, type, and status.",
+      "",
+      "Examples:",
+      '  create_spec({ title: "Payments", type: "feature" })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      title: z2.string().describe("Spec title"),
+      type: z2.enum(["prd", "full", "feature", "epic", "bug-fix"]).describe("Spec type"),
+      status: z2.enum(["draft", "review", "approved"]).optional().default("draft"),
+      projectId: z2.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ title, type, status, projectId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    }
+    try {
+      const spec = await client.createSpec(pid, { title, type, status });
+      return {
+        content: [{ type: "text", text: `Spec "${title}" created.
+- Spec ID: ${spec.id}
+- Type: ${spec.type}
+- Status: ${spec.status}` }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("add_block", {
+    title: "Add Block",
+    description: [
+      "Add a single block to an existing spec.",
+      "If position is omitted, the block is appended at the end.",
+      "",
+      "Read the resource spec-r://block-types first to get the exact content schema for each block type.",
+      "",
+      "Args:",
+      "  specId   — UUID of the spec to add the block to.",
+      "  type     — Block type: heading | text | user_story | api_endpoint | data_model | component_spec | etc.",
+      "  content  — Block content object matching the block type schema.",
+      "  position (optional) — 0-based position. Appends at end if omitted.",
+      "",
+      "Returns:",
+      "  Block ID, type, and final position.",
+      "",
+      "Examples:",
+      '  add_block({ specId: "uuid", type: "text", content: { text: "..." } })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      specId: z2.string().describe("The spec ID to add the block to"),
+      type: z2.string().describe("Block type (heading, text, user_story, api_endpoint, data_model, component_spec, etc.)"),
+      content: z2.record(z2.string(), z2.any()).describe("Block content object matching the block type schema"),
+      position: z2.number().optional().describe("Position in the spec (0-based). Appends at end if omitted.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ specId, type: blockType, content, position }) => {
+    try {
+      const block = await client.addBlock(specId, { type: blockType, content, position });
+      return {
+        content: [{ type: "text", text: `Block added.
+- Block ID: ${block.id}
+- Type: ${block.type}
+- Position: ${block.position}` }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("update_block", {
+    title: "Update Block",
+    description: [
+      "Update the content of an existing block. Provide the full content object (not a partial patch).",
+      "",
+      "Args:",
+      "  specId  — UUID of the spec containing the block.",
+      "  blockId — UUID of the block to update.",
+      "  content — New block content (full replacement, not a diff).",
+      "",
+      "Returns:",
+      "  Confirmation with the updated block ID.",
+      "",
+      "Examples:",
+      '  update_block({ specId: "uuid", blockId: "uuid", content: { text: "updated..." } })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      specId: z2.string().describe("The spec ID containing the block"),
+      blockId: z2.string().describe("The block ID to update"),
+      content: z2.record(z2.string(), z2.any()).describe("New block content (full replacement)")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ specId, blockId, content }) => {
+    try {
+      const block = await client.updateBlock(specId, blockId, content);
+      return {
+        content: [{ type: "text", text: `Block ${block.id} updated successfully.` }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("delete_block", {
+    title: "Delete Block",
+    description: [
+      "Delete a block from a spec. This is irreversible.",
+      "Prefer update_block if you want to modify content rather than remove the block entirely.",
+      "",
+      "Args:",
+      "  specId  — UUID of the spec containing the block.",
+      "  blockId — UUID of the block to delete.",
+      "",
+      "Returns:",
+      "  Confirmation of deletion.",
+      "",
+      "Examples:",
+      '  delete_block({ specId: "uuid", blockId: "uuid" })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      specId: z2.string().describe("The spec ID containing the block"),
+      blockId: z2.string().describe("The block ID to delete")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ specId, blockId }) => {
+    try {
+      await client.deleteBlock(specId, blockId);
+      return { content: [{ type: "text", text: `Block ${blockId} deleted.` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("update_spec", {
+    title: "Update Spec",
+    description: [
+      "Update spec metadata: title, type, or status. At least one field must be provided.",
+      "",
+      "Args:",
+      "  specId  — UUID of the spec to update.",
+      "  title   (optional) — New title.",
+      "  type    (optional) — New type: prd | full | feature | epic | bug-fix.",
+      "  status  (optional) — New status: draft | review | approved | locked.",
+      "",
+      "Returns:",
+      "  Confirmation with updated fields.",
+      "",
+      "Examples:",
+      '  update_spec({ specId: "uuid", status: "approved" })',
+      '  update_spec({ specId: "uuid", title: "New title", type: "prd" })'
+    ].join(`
+`),
+    inputSchema: z2.object({
+      specId: z2.string().describe("The spec ID to update"),
+      title: z2.string().optional().describe("New title"),
+      type: z2.enum(["prd", "full", "feature", "epic", "bug-fix"]).optional().describe("New type"),
+      status: z2.enum(["draft", "review", "approved", "locked"]).optional().describe("New status")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ specId, title, type: specType, status }) => {
+    try {
+      const data = {};
+      if (title)
+        data.title = title;
+      if (specType)
+        data.type = specType;
+      if (status)
+        data.status = status;
+      await client.updateSpec(specId, data);
+      return {
+        content: [{ type: "text", text: `Spec ${specId} updated.${title ? ` Title: "${title}"` : ""}${status ? ` Status: ${status}` : ""}` }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+}
+
+// src/tools/status-tools.ts
+import { z as z3 } from "zod";
+function registerStatusTools(server, client) {
+  server.registerTool("get_implementation_status", {
+    title: "Get Implementation Status",
+    description: [
+      "Get the implementation tracking status for a spec.",
+      "Shows progress percentage and per-step status (pending / in_progress / done / blocked).",
+      "Call this before starting work on a spec to know what is already done.",
+      "",
+      "Args:",
+      "  specId — UUID of the spec.",
+      "",
+      "Returns:",
+      "  Overall progress (0–100%), list of steps with status, commit SHA, PR URL, and notes.",
+      "",
+      "Examples:",
+      '  get_implementation_status({ specId: "uuid" })'
+    ].join(`
+`),
+    inputSchema: z3.object({
+      specId: z3.string().describe("The spec ID")
+    }).strict(),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ specId }) => {
+    try {
+      const { progress, steps } = await client.getImplementationStatus(specId);
+      if (steps.length === 0) {
+        return { content: [{ type: "text", text: "No implementation steps tracked yet for this spec." }] };
+      }
+      const lines = [`**Progress: ${progress}%**`, ""];
+      steps.forEach((step, i) => {
+        const statusIcon = {
+          done: "✓",
+          in_progress: "▶",
+          blocked: "✗",
+          pending: "○"
+        };
+        const icon = statusIcon[step.status] ?? "○";
+        lines.push(`${icon} Step ${i + 1}: ${step.stepTitle} [${step.status}]`);
+        if (step.commitSha)
+          lines.push(`  commit: ${step.commitSha}`);
+        if (step.prUrl)
+          lines.push(`  PR: ${step.prUrl}`);
+        if (step.notes)
+          lines.push(`  notes: ${step.notes}`);
+      });
+      return { content: [{ type: "text", text: lines.join(`
+`) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("update_implementation_status", {
+    title: "Update Implementation Status",
+    description: [
+      "Update the implementation status of a spec step. Use this to track progress as you implement features.",
+      "",
+      "Args:",
+      "  specId    — UUID of the spec.",
+      "  stepIndex — 0-based index of the step to update.",
+      "  status    — New status: pending | in_progress | done | blocked.",
+      "  commitSha (optional) — Git commit SHA associated with this step.",
+      "  prUrl     (optional) — Pull request URL.",
+      "  notes     (optional) — Implementation notes.",
+      "",
+      "Returns:",
+      "  Confirmation with the step number and new status.",
+      "",
+      "Examples:",
+      '  update_implementation_status({ specId: "uuid", stepIndex: 0, status: "done", commitSha: "abc123" })',
+      '  update_implementation_status({ specId: "uuid", stepIndex: 2, status: "blocked", notes: "Waiting on design" })'
+    ].join(`
+`),
+    inputSchema: z3.object({
+      specId: z3.string().describe("The spec ID"),
+      stepIndex: z3.number().describe("The step index (0-based)"),
+      status: z3.enum(["pending", "in_progress", "done", "blocked"]).describe("New status for this step"),
+      commitSha: z3.string().optional().describe("Git commit SHA (if applicable)"),
+      prUrl: z3.string().optional().describe("Pull request URL (if applicable)"),
+      notes: z3.string().optional().describe("Implementation notes")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async ({ specId, stepIndex, status, commitSha, prUrl, notes }) => {
+    try {
+      await client.updateImplementationStatus(specId, stepIndex, status, {
+        commitSha,
+        prUrl,
+        notes
+      });
+      const statusLabel = {
+        pending: "pending",
+        in_progress: "in progress",
+        done: "done",
+        blocked: "blocked"
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Step ${stepIndex + 1} marked as ${statusLabel[status] ?? status}${commitSha ? ` (commit: ${commitSha})` : ""}`
+          }
+        ]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+}
+
+// src/tools/ai-tools.ts
+import { z as z4 } from "zod";
+function registerAiTools(server, client) {
+  server.registerTool("analyze_screenshot", {
+    title: "Analyze Screenshot",
+    description: [
+      "Analyze a wireframe or mockup screenshot and extract structured specs: screens, user stories, data models, and API endpoints.",
+      "Use publish_spec to save the results.",
+      "Pass enableGrouping=true to get suggested spec splits for complex UIs.",
+      "",
+      "Args:",
+      "  image            — Base64-encoded image of the wireframe or mockup.",
+      "  projectId        (optional) — Project UUID. Falls back to the default project.",
+      '  additionalContext (optional) — Extra context to guide the analysis (e.g. "mobile app", "admin dashboard").',
+      "  enableGrouping   (optional, default false) — If true, also suggests how to split the analysis into multiple focused specs.",
+      "",
+      "Returns:",
+      "  JSON with screens, userStories, dataModels, apiEndpoints.",
+      "  When enableGrouping=true, also includes suggestedSpecs and suggestedRelations.",
+      "",
+      "Examples:",
+      '  analyze_screenshot({ image: "<base64>", additionalContext: "mobile checkout flow" })',
+      '  analyze_screenshot({ image: "<base64>", enableGrouping: true })'
+    ].join(`
+`),
+    inputSchema: z4.object({
+      image: z4.string().max(1e7).describe("Base64-encoded image of the wireframe or mockup (max ~7.5 MB)"),
+      projectId: z4.string().optional().describe("Project ID. Uses default project if not specified."),
+      additionalContext: z4.string().max(2000).optional().describe('Extra context to guide the analysis (e.g. "mobile app", "admin dashboard")'),
+      enableGrouping: z4.boolean().optional().default(false).describe("If true, also suggests how to split the analysis into multiple focused specs")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ image, projectId, additionalContext, enableGrouping }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    }
+    try {
+      const analysis = await client.analyzeScreenshot(pid, image, { additionalContext, enableGrouping });
+      return { content: [{ type: "text", text: JSON.stringify(analysis, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("analyze_feedback", {
+    title: "Analyze Feedback",
+    description: [
+      "Analyze client feedback text and extract structured feature requests, bug reports, and improvements with priorities.",
+      "Returns suggested spec blocks ready to use with publish_spec.",
+      "",
+      "Args:",
+      "  feedback  — Raw client feedback text to analyze.",
+      "  projectId (optional) — Project UUID. Falls back to the default project.",
+      "",
+      "Returns:",
+      "  Summary, list of requests (type, priority, title, description, suggestedBlocks), and full JSON.",
+      "",
+      "Examples:",
+      '  analyze_feedback({ feedback: "The login page is confusing and we need 2FA..." })'
+    ].join(`
+`),
+    inputSchema: z4.object({
+      feedback: z4.string().max(50000).describe("Raw client feedback text to analyze (max 50 000 chars)"),
+      projectId: z4.string().optional().describe("Project ID. Uses default project if not specified.")
+    }).strict(),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  }, async ({ feedback, projectId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid) {
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    }
+    try {
+      const analysis = await client.analyzeFeedback(pid, feedback);
+      const lines = [
+        `**Summary:** ${analysis.summary}`,
+        "",
+        `**${analysis.requests.length} request(s) identified:**`,
+        ""
+      ];
+      analysis.requests.forEach((req, i) => {
+        lines.push(`### ${i + 1}. [${req.type.toUpperCase()}] ${req.title} — Priority: ${req.priority}`);
+        lines.push(req.description);
+        lines.push(`_${req.suggestedBlocks.length} suggested block(s) ready for publish_spec_`);
+        lines.push("");
+      });
+      lines.push("---");
+      lines.push("Full JSON:");
+      lines.push("```json");
+      lines.push(JSON.stringify(analysis, null, 2));
+      lines.push("```");
+      return { content: [{ type: "text", text: lines.join(`
+`) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+}
+
+// src/resources/index.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+var BLOCK_TYPE_DOCS = {
+  heading: {
+    description: "Section heading.",
+    required: ["level (1|2|3|4)", "text"],
+    optional: [],
+    example: { level: 2, text: "Overview" }
+  },
+  text: {
+    description: "Free-form markdown text.",
+    required: ["text"],
+    optional: [],
+    example: { text: "This spec covers..." }
+  },
+  user_story: {
+    description: "User story: actor / action / goal + acceptance criteria.",
+    required: ["id (e.g. US-001)", "actor", "action", "goal", "priority (HIGH|MEDIUM|LOW)", "acceptanceCriteria (string[])"],
+    optional: ["storyPoints", "status (todo|in_progress|done)"],
+    example: { id: "US-001", actor: "En tant qu'utilisateur", action: "Je veux me connecter", goal: "Afin d'accéder à mon compte", priority: "HIGH", acceptanceCriteria: ["Token JWT retourné", "Session persistée 30j"] }
+  },
+  acceptance_criteria: {
+    description: "Checklist of acceptance criteria.",
+    required: ["criteria (Array<{id, description, verified}>)"],
+    optional: ["title"],
+    example: { title: "Login", criteria: [{ id: "AC-1", description: "Token valide retourné", verified: false }] }
+  },
+  business_rule: {
+    description: "Business rule with trigger, conditions, and actions.",
+    required: ["id (e.g. BR-001)", "name", "description", "trigger", "conditions (string[])", "actions (string[])"],
+    optional: ["exceptions (string[])", "priority (HIGH|MEDIUM|LOW)"],
+    example: { id: "BR-001", name: "Free tier limit", description: "Max 20 items for free users", trigger: "User adds item", conditions: ["plan === free", "count >= 20"], actions: ["Block action", "Show upgrade modal"] }
+  },
+  persona: {
+    description: "User persona with goals and frustrations.",
+    required: ["name", "role", "description", "goals (string[])", "frustrations (string[])"],
+    optional: ["context"],
+    example: { name: "Marie", role: "Beginner", description: "22 ans, découvre les parfums", goals: ["Apprendre les familles olfactives"], frustrations: ["Jargon trop technique"] }
+  },
+  screen_spec: {
+    description: "UI screen specification with states and components.",
+    required: ["name", "description", "states (Array<{name,description}>)", "components (string[])"],
+    optional: ["route", "interactions (string[])", "screenshot (URL)"],
+    example: { name: "Home", route: "/home", description: "Main screen", states: [{ name: "empty", description: "Nothing logged today" }], components: ["SOTDCard", "StreakBadge"] }
+  },
+  component_spec: {
+    description: "Reusable UI component with props and states.",
+    required: ["name", "filePath", "description", "props (Array<{name,type,required,description?,defaultValue?}>)", "states (string[])", "behavior"],
+    optional: ["events (string[])"],
+    example: { name: "StreakBadge", filePath: "components/StreakBadge.tsx", description: "Shows streak count", props: [{ name: "count", type: "number", required: true }], states: ["active", "broken"], behavior: "Pulses on increment" }
+  },
+  api_endpoint: {
+    description: "API endpoint specification.",
+    required: ["method (GET|POST|PUT|DELETE|PATCH)", "path", "description", "authRequired (boolean)"],
+    optional: ["request ({body?,params?,query?})", "response"],
+    example: { method: "POST", path: "/api/sotd", description: "Log today's fragrance", authRequired: true, request: { body: { fragranceId: "uuid" } }, response: { xpEarned: 10, streakCount: 5 } }
+  },
+  data_model: {
+    description: "Data entity with fields and relations.",
+    required: ["entityName", "description", "fields (Array<{name,type,required,description?}>)", "relations (Array<{type:one_to_one|one_to_many|many_to_many, target}>)"],
+    optional: [],
+    example: { entityName: "DailyLog", description: "Fragrance worn on a given day", fields: [{ name: "id", type: "uuid", required: true }, { name: "date", type: "date", required: true }], relations: [{ type: "many_to_many", target: "Fragrance" }] }
+  },
+  dto: {
+    description: "Data Transfer Object for API validation.",
+    required: ["name", "type (request|response|query|params|event)", "fields (Array<{name,type,required,description?,validation?}>)"],
+    optional: ["description", 'endpointRef (e.g. "POST /api/sotd")', "example (JSON string)"],
+    example: { name: "CreateSOTDRequest", type: "request", endpointRef: "POST /api/sotd", fields: [{ name: "fragranceId", type: "string", required: true, validation: "uuid" }] }
+  },
+  enum_definition: {
+    description: "Enumeration of possible values.",
+    required: ["name", "values (Array<{key,label,description?,color?}>)"],
+    optional: ["description"],
+    example: { name: "FragranceFamily", values: [{ key: "FLORAL", label: "Floral", color: "#FFB3C6" }, { key: "WOODY", label: "Woody", color: "#8B6914" }] }
+  },
+  external_dependency: {
+    description: "External API, service, or SDK dependency.",
+    required: ["name", "type (api|webhook|database|service|sdk)", "description"],
+    optional: ["baseUrl", "endpoints (Array<{method,path,description}>)", "auth", "rateLimit", "dataFormat"],
+    example: { name: "Stripe", type: "api", baseUrl: "https://api.stripe.com", description: "Payment processing", auth: "Bearer secret key" }
+  },
+  problem_statement: {
+    description: "The problem being solved, its impact, and target audience.",
+    required: ["problem", "impact", "audience"],
+    optional: [],
+    example: { problem: "No dedicated app for fragrance tracking", impact: "Behavior exists on Reddit but is fragmented", audience: "Fragrance collectors 18-45" }
+  },
+  solution_overview: {
+    description: "Proposed solution with positioning and success metrics.",
+    required: ["solution", "positioning", "successMetrics (string[])"],
+    optional: [],
+    example: { solution: "Gamified fragrance tracking app", positioning: "Duolingo for perfume", successMetrics: ["DAU/MAU > 40%", "Pro conversion > 5%"] }
+  },
+  scope_boundary: {
+    description: "What is in scope, out of scope, and deferred.",
+    required: ["inScope (string[])", "outOfScope (string[])", "deferredItems (string[])"],
+    optional: [],
+    example: { inScope: ["SOTD logging", "Collection"], outOfScope: ["Social network"], deferredItems: ["AI recognition"] }
+  },
+  diagram: {
+    description: "Mermaid diagram (flowchart, sequence, ERD, class).",
+    required: ["diagramType (flowchart|sequence|erd|class)", "mermaidCode"],
+    optional: [],
+    example: { diagramType: "sequence", mermaidCode: `sequenceDiagram
+  User->>API: POST /api/sotd
+  API-->>User: {xpEarned}` }
+  },
+  code: {
+    description: "Code snippet with syntax highlighting.",
+    required: ["language (e.g. typescript, sql)", "code"],
+    optional: [],
+    example: { language: "typescript", code: "const streak = await getStreak(userId)" }
+  },
+  image: {
+    description: "Image with optional caption.",
+    required: ["url (https)"],
+    optional: ["alt", "caption"],
+    example: { url: "https://example.com/wireframe.png", caption: "Home screen wireframe" }
+  },
+  spec_link: {
+    description: "Link to another spec with a relation type.",
+    required: ["targetSpecId (UUID)", "relationType (depends_on|related_to|parent_of|blocks)"],
+    optional: ["targetSpecTitle", "description"],
+    example: { targetSpecId: "uuid", relationType: "depends_on", description: "Requires gamification XP system" }
+  },
+  file_structure: {
+    description: "Files to create, modify, or delete.",
+    required: ["description", "entries (Array<{path, action:create|modify|delete, description}>)"],
+    optional: [],
+    example: { description: "SOTD feature files", entries: [{ path: "app/api/sotd/route.ts", action: "create", description: "SOTD API endpoint" }] }
+  },
+  architecture_decision: {
+    description: "Architecture Decision Record (ADR).",
+    required: ["title", "status (proposed|accepted|deprecated|superseded)", "context", "decision", "consequences (string[])"],
+    optional: ["alternatives (Array<{option, reason}>)"],
+    example: { title: "Edge caching with Cloudflare", status: "accepted", context: "Read-heavy catalog", decision: "Cache at edge via KV", consequences: ["<50ms globally", "Cache invalidation complexity"] }
+  },
+  test_spec: {
+    description: "Test scenarios in Given/When/Then format.",
+    required: ["testType (unit|integration|e2e|api)", "description", "scenarios (Array<{given,when,then,priority?}>)"],
+    optional: [],
+    example: { testType: "api", description: "SOTD endpoint", scenarios: [{ given: "User authenticated", when: "POST /api/sotd", then: "Returns 201 + xpEarned", priority: "HIGH" }] }
+  },
+  implementation_plan: {
+    description: "Ordered implementation steps with files and complexity.",
+    required: ["steps (Array<{order,title,description,files:string[],complexity:low|medium|high,dependencies?}>)"],
+    optional: [],
+    example: { steps: [{ order: 1, title: "DB schema", description: "Create table", files: ["schema/daily-logs.ts"], complexity: "low" }, { order: 2, title: "API endpoint", description: "POST handler", files: ["app/api/sotd/route.ts"], complexity: "medium", dependencies: ["Step 1"] }] }
+  },
+  environment_config: {
+    description: "Environment variables and services required.",
+    required: ["description", "variables (Array<{name,description,required,example?,secret}>)"],
+    optional: ["services (Array<{name,description,required}>)"],
+    example: { description: "Affiliate config", variables: [{ name: "FRAGRANCENET_API_KEY", description: "Affiliate API key", required: true, secret: true, example: "fn_xxx" }] }
+  }
+};
+function registerResources(server, client) {
+  server.registerResource("block-types", "spec-r://block-types", {
+    description: "Complete schema reference for all spec-r block types. Read this before calling add_block or publish_spec to know what fields each block type requires.",
+    mimeType: "application/json"
+  }, async (uri) => ({
+    contents: [{
+      uri: uri.toString(),
+      mimeType: "application/json",
+      text: JSON.stringify(BLOCK_TYPE_DOCS, null, 2)
+    }]
+  }));
+  server.registerResource("project-specs", new ResourceTemplate("spec-r://projects/{projectId}/specs", { list: undefined }), {
+    description: "List of all specs in a project. Use to browse specs without calling list_specs.",
+    mimeType: "application/json"
+  }, async (uri, { projectId }) => {
+    try {
+      const specs = await client.listSpecs(projectId);
+      return {
+        contents: [{
+          uri: uri.toString(),
+          mimeType: "application/json",
+          text: JSON.stringify(specs, null, 2)
+        }]
+      };
+    } catch (error) {
+      return {
+        contents: [{
+          uri: uri.toString(),
+          mimeType: "text/plain",
+          text: handleApiError(error)
+        }]
+      };
+    }
+  });
+  server.registerResource("project-resources", new ResourceTemplate("spec-r://projects/{projectId}/resources", { list: undefined }), {
+    description: "Shared resources (data_model, persona, enum_definition, external_dependency) defined at project level. Read before creating specs to avoid duplicating definitions.",
+    mimeType: "application/json"
+  }, async (uri, { projectId }) => {
+    try {
+      const { resources } = await client.listResources(projectId);
+      return {
+        contents: [{
+          uri: uri.toString(),
+          mimeType: "application/json",
+          text: JSON.stringify(resources, null, 2)
+        }]
+      };
+    } catch (error) {
+      return {
+        contents: [{ uri: uri.toString(), mimeType: "text/plain", text: handleApiError(error) }]
+      };
+    }
+  });
+  server.registerResource("spec", new ResourceTemplate("spec-r://specs/{specId}", { list: undefined }), {
+    description: "Full content of a spec including all blocks. Alternative to get_spec tool for passive reading.",
+    mimeType: "application/json"
+  }, async (uri, { specId }) => {
+    try {
+      const data = await client.getSpec(specId, "json");
+      return {
+        contents: [{
+          uri: uri.toString(),
+          mimeType: "application/json",
+          text: JSON.stringify(data, null, 2)
+        }]
+      };
+    } catch (error) {
+      return {
+        contents: [{
+          uri: uri.toString(),
+          mimeType: "text/plain",
+          text: handleApiError(error)
+        }]
+      };
+    }
+  });
+}
+
+// src/tools/resource-tools.ts
+import { z as z5 } from "zod";
+var RESOURCE_TYPES = ["data_model", "persona", "enum_definition", "external_dependency"];
+function registerResourceTools(server, client) {
+  server.registerTool("list_resources", {
+    title: "List Shared Resources",
+    description: [
+      "List shared resources defined at the project level.",
+      "Shared resources (data_model, persona, enum_definition, external_dependency) are reusable",
+      "entities that can be referenced from any spec block via linkedResourceId.",
+      "Always check shared resources before defining new data models or personas in a spec —",
+      "the project may already have a canonical definition to link to.",
+      "",
+      "Args:",
+      "  projectId (optional) — Project UUID. Falls back to default project.",
+      "  type (optional) — Filter by type: data_model | persona | enum_definition | external_dependency",
+      "",
+      "Returns:",
+      "  List of resources with id, type, name, description."
+    ].join(`
+`),
+    inputSchema: z5.object({
+      projectId: z5.string().optional().describe("Project ID. Uses default project if not specified."),
+      type: z5.enum(RESOURCE_TYPES).optional().describe("Filter by resource type")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, async ({ projectId, type }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid)
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    try {
+      const { resources } = await client.listResources(pid, type);
+      if (resources.length === 0) {
+        return { content: [{ type: "text", text: `No shared resources found${type ? ` of type "${type}"` : ""}.` }] };
+      }
+      const text = resources.map((r) => `- [${r.type}] **${r.name}** — ID: ${r.id}${r.description ? ` — ${r.description}` : ""}`).join(`
+`);
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("get_resource", {
+    title: "Get Shared Resource",
+    description: [
+      "Get a shared resource by ID, including its full content and which specs reference it.",
+      "",
+      "Args:",
+      "  projectId (optional) — Project UUID.",
+      "  resourceId — UUID of the resource.",
+      "",
+      "Returns:",
+      "  Resource content + usedIn list of {specId, blockId} where it is referenced."
+    ].join(`
+`),
+    inputSchema: z5.object({
+      projectId: z5.string().optional().describe("Project ID. Uses default project if not specified."),
+      resourceId: z5.string().describe("Resource UUID")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, async ({ projectId, resourceId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid)
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    try {
+      const { resource, usedIn } = await client.getResource(pid, resourceId);
+      const lines = [
+        `# [${resource.type}] ${resource.name}`,
+        resource.description ? `> ${resource.description}` : "",
+        "",
+        "**Content:**",
+        "```json",
+        JSON.stringify(resource.content, null, 2),
+        "```",
+        "",
+        `**Used in ${usedIn.length} spec block(s):**`,
+        ...usedIn.map((u) => `- Spec: ${u.specId} / Block: ${u.blockId}`)
+      ].filter((l) => l !== undefined);
+      const text = lines.join(`
+`);
+      return {
+        content: [{ type: "text", text: text.length > CHARACTER_LIMIT ? text.slice(0, CHARACTER_LIMIT) + `
+…(truncated)` : text }],
+        structuredContent: { resource, usedIn }
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("create_resource", {
+    title: "Create Shared Resource",
+    description: [
+      "Create a shared resource at the project level.",
+      "Use this instead of repeating the same data_model or persona definition in every spec.",
+      "Once created, reference it from spec blocks via linkedResourceId in the block content.",
+      "",
+      "Types and their content schema (see spec-r://block-types for full field details):",
+      "  data_model        — entityName, description, fields[], relations[]",
+      "  persona           — name, role, description, goals[], frustrations[]",
+      "  enum_definition   — name, values[{key,label,description?,color?}]",
+      "  external_dependency — name, type, description, baseUrl?, endpoints?[]",
+      "",
+      "Args:",
+      "  type        — data_model | persona | enum_definition | external_dependency",
+      "  name        — Human-readable name for the resource",
+      "  content     — Type-specific content object (same schema as the matching block type)",
+      "  description (optional) — Short description",
+      "  projectId   (optional) — Falls back to default project",
+      "",
+      "Returns:",
+      "  Created resource with its UUID to use as linkedResourceId."
+    ].join(`
+`),
+    inputSchema: z5.object({
+      projectId: z5.string().optional().describe("Project ID. Uses default project if not specified."),
+      type: z5.enum(RESOURCE_TYPES).describe("Resource type"),
+      name: z5.string().min(1).max(200).describe("Resource name"),
+      description: z5.string().max(500).optional().describe("Short description"),
+      content: z5.record(z5.string(), z5.any()).describe("Type-specific content (same schema as the matching block type)")
+    }).strict(),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+  }, async ({ projectId, type, name, description, content }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid)
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    try {
+      const resource = await client.createResource(pid, { type, name, description, content });
+      return {
+        content: [{ type: "text", text: `Shared resource created.
+- ID: ${resource.id}
+- Type: ${resource.type}
+- Name: ${resource.name}
+
+Reference it from spec blocks with: { linkedResourceId: "${resource.id}" }` }],
+        structuredContent: resource
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("update_resource", {
+    title: "Update Shared Resource",
+    description: [
+      "Update a shared resource. All specs referencing it via linkedResourceId will reflect the change.",
+      "",
+      "Args:",
+      "  projectId   (optional)",
+      "  resourceId  — UUID of the resource to update",
+      "  name        (optional) — New name",
+      "  description (optional) — New description",
+      "  content     (optional) — Full content replacement"
+    ].join(`
+`),
+    inputSchema: z5.object({
+      projectId: z5.string().optional().describe("Project ID. Uses default project if not specified."),
+      resourceId: z5.string().describe("Resource UUID"),
+      name: z5.string().min(1).max(200).optional().describe("New name"),
+      description: z5.string().max(500).optional().describe("New description"),
+      content: z5.record(z5.string(), z5.any()).optional().describe("New content (full replacement)")
+    }).strict(),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  }, async ({ projectId, resourceId, name, description, content }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid)
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    try {
+      const resource = await client.updateResource(pid, resourceId, { name, description, content });
+      return { content: [{ type: "text", text: `Resource ${resource.id} updated.` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+  server.registerTool("delete_resource", {
+    title: "Delete Shared Resource",
+    description: [
+      "Delete a shared resource. Call get_resource first to check usedIn — deleting a resource",
+      "referenced by spec blocks will leave those blocks with a dangling linkedResourceId.",
+      "",
+      "Args:",
+      "  projectId  (optional)",
+      "  resourceId — UUID of the resource to delete"
+    ].join(`
+`),
+    inputSchema: z5.object({
+      projectId: z5.string().optional().describe("Project ID. Uses default project if not specified."),
+      resourceId: z5.string().describe("Resource UUID")
+    }).strict(),
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+  }, async ({ projectId, resourceId }) => {
+    const pid = projectId || client.defaultProjectId;
+    if (!pid)
+      return { content: [{ type: "text", text: "Error: projectId is required (no default project configured)" }] };
+    try {
+      await client.deleteResource(pid, resourceId);
+      return { content: [{ type: "text", text: `Resource ${resourceId} deleted.` }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: handleApiError(error) }] };
+    }
+  });
+}
+
+// src/index.ts
+var apiKey = process.env.SPECR_API_KEY;
+var baseUrl = process.env.SPECR_BASE_URL || "https://spec-r.app";
+var defaultProjectId = process.env.SPECR_PROJECT_ID;
+if (!apiKey) {
+  console.error("Error: SPECR_API_KEY environment variable is required");
+  process.exit(1);
+}
+var client = new SpecRApiClient({ apiKey, baseUrl, defaultProjectId });
+var server = new McpServer2({ name: "spec-r", version: "0.1.0" });
+registerReadTools(server, client);
+registerWriteTools(server, client);
+registerStatusTools(server, client);
+registerAiTools(server, client);
+registerResources(server, client);
+registerResourceTools(server, client);
+async function main() {
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error("MCP server error:", error);
+  process.exit(1);
+});