clearspec-mcp 0.1.0

package/.next/trace

@@ -0,0 +1 @@
+[{"name":"generate-buildid","duration":121,"timestamp":813651137740,"id":4,"parentId":1,"tags":{},"startTime":1775774788522,"traceId":"26d8c2e24f9254f6"},{"name":"load-custom-routes","duration":881,"timestamp":813651137915,"id":5,"parentId":1,"tags":{},"startTime":1775774788522,"traceId":"26d8c2e24f9254f6"},{"name":"create-dist-dir","duration":1514,"timestamp":813651138809,"id":6,"parentId":1,"tags":{},"startTime":1775774788523,"traceId":"26d8c2e24f9254f6"},{"name":"clean","duration":694,"timestamp":813651140889,"id":7,"parentId":1,"tags":{},"startTime":1775774788525,"traceId":"26d8c2e24f9254f6"},{"name":"next-build","duration":75245,"timestamp":813651066423,"id":1,"tags":{"buildMode":"default","version":"16.2.2","bundler":"turbopack","failed":true},"startTime":1775774788450,"traceId":"26d8c2e24f9254f6"}]

package/.next/trace-build

@@ -0,0 +1 @@
+[{"name":"next-build","duration":75245,"timestamp":813651066423,"id":1,"tags":{"buildMode":"default","version":"16.2.2","bundler":"turbopack","failed":true},"startTime":1775774788450,"traceId":"26d8c2e24f9254f6"}]

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+import type { Spec } from "./types.js";
+export declare function formatSpecAsMarkdown(spec: Spec): string;

package/dist/format.js

@@ -0,0 +1,102 @@
+function statusLabel(status) {
+    const labels = {
+        ready_to_build: "Ready to build",
+        in_progress: "In progress",
+        draft: "Draft",
+        archived: "Archived",
+        in_review: "In review",
+        approved: "Approved",
+        in_development: "In development",
+        delivered: "Delivered",
+    };
+    return labels[status] ?? status;
+}
+export function formatSpecAsMarkdown(spec) {
+    const { sections } = spec;
+    const lines = [];
+    lines.push(`# ${spec.title}`);
+    lines.push("");
+    lines.push(`**Status:** ${statusLabel(spec.status)} | **Completeness:** ${spec.completenessScore}%`);
+    lines.push(`**Updated:** ${spec.updatedAt}`);
+    lines.push("");
+    // Goal
+    if (sections.goal?.trim()) {
+        lines.push("## Goal");
+        lines.push("");
+        lines.push(sections.goal.trim());
+        lines.push("");
+    }
+    // User Stories
+    if (sections.userStories?.length > 0) {
+        lines.push("## User Stories");
+        lines.push("");
+        for (const story of sections.userStories) {
+            lines.push(`### As a ${story.persona}, I want to ${story.action}, so that ${story.benefit}`);
+            if (story.acceptanceCriteria?.length > 0) {
+                lines.push("");
+                lines.push("**Acceptance Criteria:**");
+                for (const criterion of story.acceptanceCriteria) {
+                    lines.push(`- ${criterion}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    // Global Acceptance Criteria
+    if (sections.acceptanceCriteria?.length > 0) {
+        lines.push("## Acceptance Criteria");
+        lines.push("");
+        for (const criterion of sections.acceptanceCriteria) {
+            lines.push(`- ${criterion}`);
+        }
+        lines.push("");
+    }
+    // Edge Cases
+    if (sections.edgeCases?.length > 0) {
+        lines.push("## Edge Cases");
+        lines.push("");
+        for (const edge of sections.edgeCases) {
+            lines.push(`- **${edge.description}** — ${edge.resolution}`);
+        }
+        lines.push("");
+    }
+    // Failure States
+    if (sections.failureStates?.length > 0) {
+        lines.push("## Failure States");
+        lines.push("");
+        for (const failure of sections.failureStates) {
+            lines.push(`- **Trigger:** ${failure.trigger}`);
+            lines.push(`  - **Behavior:** ${failure.behavior}`);
+            lines.push(`  - **Recovery:** ${failure.recovery}`);
+        }
+        lines.push("");
+    }
+    // Dependencies
+    if (sections.dependencies?.length > 0) {
+        lines.push("## Dependencies");
+        lines.push("");
+        for (const dep of sections.dependencies) {
+            lines.push(`- **${dep.name}** — ${dep.description}`);
+        }
+        lines.push("");
+    }
+    // Out of Scope
+    if (sections.outOfScope?.length > 0) {
+        lines.push("## Out of Scope");
+        lines.push("");
+        for (const item of sections.outOfScope) {
+            lines.push(`- ${item}`);
+        }
+        lines.push("");
+    }
+    // Verification Criteria
+    if (sections.verificationCriteria?.length > 0) {
+        lines.push("## Verification Criteria");
+        lines.push("");
+        for (const vc of sections.verificationCriteria) {
+            lines.push(`- [${vc.type}] ${vc.description}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateAuth } from "./supabase.js";
+import { listSpecs, getSpec, searchSpecs, getSpecAsMarkdown, listSpecsSchema, getSpecSchema, searchSpecsSchema, getSpecMarkdownSchema, } from "./tools.js";
+const server = new McpServer({
+    name: "clearspec",
+    version: "0.1.0",
+});
+// --- Tool registrations ---
+server.tool("list_specs", "List all your specs with title, status, and completeness score. Returns metadata only — use get_spec for full content.", listSpecsSchema.shape, async ({ status, project_id }) => {
+    try {
+        const specs = await listSpecs({ status, project_id });
+        return {
+            content: [{ type: "text", text: JSON.stringify(specs, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+});
+server.tool("get_spec", "Get a full spec with all sections (goal, user stories, edge cases, etc.). Use include_versions to also fetch version history.", getSpecSchema.shape, async ({ spec_id, include_versions }) => {
+    try {
+        const spec = await getSpec({ spec_id, include_versions });
+        if (!spec) {
+            return { content: [{ type: "text", text: `Spec not found: ${spec_id}` }], isError: true };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(spec, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+});
+server.tool("search_specs", "Search specs by title keyword. Returns metadata only — use get_spec for full content.", searchSpecsSchema.shape, async ({ query }) => {
+    try {
+        const specs = await searchSpecs({ query });
+        return {
+            content: [{ type: "text", text: JSON.stringify(specs, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+});
+server.tool("get_spec_as_markdown", "Get a spec formatted as implementation-ready markdown with all sections: goal, user stories (with acceptance criteria), edge cases, failure states, dependencies, out of scope, and verification criteria.", getSpecMarkdownSchema.shape, async ({ spec_id }) => {
+    try {
+        const markdown = await getSpecAsMarkdown({ spec_id });
+        return {
+            content: [{ type: "text", text: markdown }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+});
+// --- Start server ---
+async function main() {
+    // Validate auth before accepting connections
+    await validateAuth();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(`clearspec-mcp: ${message}\n`);
+    process.exit(1);
+});

package/dist/supabase.d.ts

@@ -0,0 +1,5 @@
+import { type SupabaseClient } from "@supabase/supabase-js";
+export declare function createClient(): SupabaseClient;
+/** Validate the token at startup and cache the user ID. */
+export declare function validateAuth(): Promise<string>;
+export declare function getCachedUserId(): string;

package/dist/supabase.js

@@ -0,0 +1,52 @@
+// SYNC: Auth pattern differs from src/lib/supabase/server.ts — uses header injection, not cookies
+import { createClient as createSupabaseClient } from "@supabase/supabase-js";
+// Default Supabase project — these are public values (same as the frontend)
+const DEFAULT_SUPABASE_URL = "https://adyjdccjwnrkzfzctfgo.supabase.co";
+const DEFAULT_SUPABASE_ANON_KEY = "sb_publishable_U1PJ3J1I-pJaSqKm4sBwyA_LUimFh44";
+function getEnvConfig() {
+    const supabaseUrl = process.env.CLEARSPEC_SUPABASE_URL || DEFAULT_SUPABASE_URL;
+    const supabaseAnonKey = process.env.CLEARSPEC_SUPABASE_ANON_KEY || DEFAULT_SUPABASE_ANON_KEY;
+    const accessToken = process.env.CLEARSPEC_ACCESS_TOKEN;
+    if (!accessToken) {
+        throw new Error("Missing CLEARSPEC_ACCESS_TOKEN. Get one from ClearSpec Settings > MCP Integration.");
+    }
+    return { supabaseUrl, supabaseAnonKey, accessToken };
+}
+let cachedClient = null;
+let cachedUserId = null;
+export function createClient() {
+    if (cachedClient)
+        return cachedClient;
+    const { supabaseUrl, supabaseAnonKey, accessToken } = getEnvConfig();
+    cachedClient = createSupabaseClient(supabaseUrl, supabaseAnonKey, {
+        global: {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+        },
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+        },
+    });
+    return cachedClient;
+}
+/** Validate the token at startup and cache the user ID. */
+export async function validateAuth() {
+    if (cachedUserId)
+        return cachedUserId;
+    const supabase = createClient();
+    const { data, error } = await supabase.auth.getUser();
+    if (error || !data.user) {
+        throw new Error("Authentication failed. Your CLEARSPEC_ACCESS_TOKEN may be invalid or expired. " +
+            "Get a fresh token from ClearSpec Settings and restart the MCP server.");
+    }
+    cachedUserId = data.user.id;
+    return cachedUserId;
+}
+export function getCachedUserId() {
+    if (!cachedUserId) {
+        throw new Error("Auth not validated yet. Call validateAuth() first.");
+    }
+    return cachedUserId;
+}

package/dist/tools.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { Spec, SpecMeta } from "./types.js";
+export declare const listSpecsSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodString>;
+    project_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status?: string | undefined;
+    project_id?: string | undefined;
+}, {
+    status?: string | undefined;
+    project_id?: string | undefined;
+}>;
+export declare const getSpecSchema: z.ZodObject<{
+    spec_id: z.ZodString;
+    include_versions: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    spec_id: string;
+    include_versions: boolean;
+}, {
+    spec_id: string;
+    include_versions?: boolean | undefined;
+}>;
+export declare const searchSpecsSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export declare const getSpecMarkdownSchema: z.ZodObject<{
+    spec_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    spec_id: string;
+}, {
+    spec_id: string;
+}>;
+export declare function listSpecs(input: z.infer<typeof listSpecsSchema>): Promise<SpecMeta[]>;
+export declare function getSpec(input: z.infer<typeof getSpecSchema>): Promise<Spec | null>;
+export declare function searchSpecs(input: z.infer<typeof searchSpecsSchema>): Promise<SpecMeta[]>;
+export declare function getSpecAsMarkdown(input: z.infer<typeof getSpecMarkdownSchema>): Promise<string>;

package/dist/tools.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { createClient, getCachedUserId } from "./supabase.js";
+import { rowToSpec, rowToSpecMeta } from "./types.js";
+import { formatSpecAsMarkdown } from "./format.js";
+const AUTH_ERROR_MSG = "Authentication failed. Your token may have expired. " +
+    "Get a fresh token from ClearSpec Settings and restart the MCP server.";
+/** Check if an error is a Supabase auth error (expired/invalid token). */
+function isAuthError(error) {
+    if (error && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        return code === "PGRST301" || code === "401" || code === "403";
+    }
+    return false;
+}
+// --- Tool input schemas ---
+export const listSpecsSchema = z.object({
+    status: z.string().optional().describe("Filter by status (e.g. 'draft', 'ready_to_build', 'in_progress')"),
+    project_id: z.string().optional().describe("Filter by project ID"),
+});
+export const getSpecSchema = z.object({
+    spec_id: z.string().describe("The spec ID to retrieve"),
+    include_versions: z.boolean().optional().default(false).describe("Include version history (default: false)"),
+});
+export const searchSpecsSchema = z.object({
+    query: z.string().describe("Search term to match against spec titles"),
+});
+export const getSpecMarkdownSchema = z.object({
+    spec_id: z.string().describe("The spec ID to format as markdown"),
+});
+// --- Tool handlers ---
+export async function listSpecs(input) {
+    const supabase = createClient();
+    const userId = getCachedUserId();
+    let query = supabase
+        .from("specs")
+        .select("id, title, status, completeness_score, project_id, updated_at")
+        .eq("user_id", userId)
+        .order("updated_at", { ascending: false });
+    if (input.status) {
+        query = query.eq("status", input.status);
+    }
+    if (input.project_id) {
+        query = query.eq("project_id", input.project_id);
+    }
+    const { data, error } = await query;
+    if (error) {
+        if (isAuthError(error))
+            throw new Error(AUTH_ERROR_MSG);
+        throw new Error(`Failed to list specs: ${error.message}`);
+    }
+    return (data || []).map((row) => rowToSpecMeta(row));
+}
+export async function getSpec(input) {
+    const supabase = createClient();
+    const userId = getCachedUserId();
+    const specPromise = supabase
+        .from("specs")
+        .select("*")
+        .eq("id", input.spec_id)
+        .eq("user_id", userId)
+        .single();
+    if (input.include_versions) {
+        const [specResult, versionsResult] = await Promise.all([
+            specPromise,
+            supabase
+                .from("spec_versions")
+                .select("*")
+                .eq("spec_id", input.spec_id)
+                .order("version", { ascending: true }),
+        ]);
+        if (specResult.error) {
+            if (isAuthError(specResult.error))
+                throw new Error(AUTH_ERROR_MSG);
+            return null;
+        }
+        return rowToSpec(specResult.data, (versionsResult.data || []));
+    }
+    const { data, error } = await specPromise;
+    if (error) {
+        if (isAuthError(error))
+            throw new Error(AUTH_ERROR_MSG);
+        return null;
+    }
+    return rowToSpec(data);
+}
+export async function searchSpecs(input) {
+    const supabase = createClient();
+    const userId = getCachedUserId();
+    const { data, error } = await supabase
+        .from("specs")
+        .select("id, title, status, completeness_score, project_id, updated_at")
+        .eq("user_id", userId)
+        .ilike("title", `%${input.query}%`)
+        .order("updated_at", { ascending: false });
+    if (error) {
+        if (isAuthError(error))
+            throw new Error(AUTH_ERROR_MSG);
+        throw new Error(`Failed to search specs: ${error.message}`);
+    }
+    return (data || []).map((row) => rowToSpecMeta(row));
+}
+export async function getSpecAsMarkdown(input) {
+    const spec = await getSpec({ spec_id: input.spec_id, include_versions: false });
+    if (!spec) {
+        throw new Error(`Spec not found: ${input.spec_id}`);
+    }
+    return formatSpecAsMarkdown(spec);
+}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+export interface UserStory {
+    id: string;
+    persona: string;
+    action: string;
+    benefit: string;
+    acceptanceCriteria: string[];
+}
+export interface EdgeCase {
+    id: string;
+    description: string;
+    resolution: string;
+}
+export interface FailureState {
+    id: string;
+    trigger: string;
+    behavior: string;
+    recovery: string;
+}
+export interface Dependency {
+    id: string;
+    name: string;
+    description: string;
+}
+export interface VerificationCriterion {
+    id: string;
+    description: string;
+    type: "automated" | "manual";
+}
+export interface SpecSection {
+    goal: string;
+    userStories: UserStory[];
+    acceptanceCriteria: string[];
+    edgeCases: EdgeCase[];
+    failureStates: FailureState[];
+    dependencies: Dependency[];
+    outOfScope: string[];
+    verificationCriteria: VerificationCriterion[];
+}
+export type SpecStatus = "draft" | "in_review" | "approved" | "in_development" | "delivered" | "in_progress" | "ready_to_build" | "archived";
+export interface Spec {
+    id: string;
+    title: string;
+    status: SpecStatus;
+    completenessScore: number;
+    sections: SpecSection;
+    projectId: string | null;
+    isSample: boolean;
+    shareToken: string | null;
+    sharePermission: "view" | "comment" | "edit";
+    repoFullName: string | null;
+    linearIssueId: string | null;
+    linearIssueUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+    versions: SpecVersion[];
+}
+export interface SpecVersion {
+    id: string;
+    specId: string;
+    version: number;
+    sections: SpecSection;
+    changeNote: string | null;
+    changedById: string | null;
+    createdAt: string;
+}
+/** Metadata-only shape for list_specs (no sections/versions). */
+export interface SpecMeta {
+    id: string;
+    title: string;
+    status: SpecStatus;
+    completenessScore: number;
+    projectId: string | null;
+    updatedAt: string;
+}
+export declare function rowToSpec(row: Record<string, unknown>, versions?: Record<string, unknown>[]): Spec;
+export declare function rowToSpecMeta(row: Record<string, unknown>): SpecMeta;

package/dist/types.js

@@ -0,0 +1,39 @@
+// SYNC: copied from src/types/spec.ts — keep in sync when spec schema changes
+// SYNC: copied from src/lib/store/specs.ts rowToSpec()
+export function rowToSpec(row, versions = []) {
+    return {
+        id: row.id,
+        title: row.title,
+        status: row.status,
+        completenessScore: row.completeness_score,
+        sections: row.sections,
+        projectId: row.project_id || null,
+        isSample: row.is_sample ?? false,
+        shareToken: row.share_token ?? null,
+        sharePermission: row.share_permission ?? "view",
+        repoFullName: row.repo_full_name ?? null,
+        linearIssueId: row.linear_issue_id ?? null,
+        linearIssueUrl: row.linear_issue_url ?? null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        versions: versions.map((v) => ({
+            id: v.id,
+            specId: v.spec_id,
+            version: v.version,
+            sections: v.sections,
+            changeNote: v.change_note ?? null,
+            changedById: v.changed_by_id ?? null,
+            createdAt: v.created_at,
+        })),
+    };
+}
+export function rowToSpecMeta(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        status: row.status,
+        completenessScore: row.completeness_score,
+        projectId: row.project_id || null,
+        updatedAt: row.updated_at,
+    };
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "clearspec-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for reading ClearSpec specs from Claude Code",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "clearspec-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@supabase/supabase-js": "^2.101.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/src/format.ts

@@ -0,0 +1,115 @@
+import type { Spec, SpecSection } from "./types.js";
+
+function statusLabel(status: string): string {
+  const labels: Record<string, string> = {
+    ready_to_build: "Ready to build",
+    in_progress: "In progress",
+    draft: "Draft",
+    archived: "Archived",
+    in_review: "In review",
+    approved: "Approved",
+    in_development: "In development",
+    delivered: "Delivered",
+  };
+  return labels[status] ?? status;
+}
+
+export function formatSpecAsMarkdown(spec: Spec): string {
+  const { sections } = spec;
+  const lines: string[] = [];
+
+  lines.push(`# ${spec.title}`);
+  lines.push("");
+  lines.push(`**Status:** ${statusLabel(spec.status)} | **Completeness:** ${spec.completenessScore}%`);
+  lines.push(`**Updated:** ${spec.updatedAt}`);
+  lines.push("");
+
+  // Goal
+  if (sections.goal?.trim()) {
+    lines.push("## Goal");
+    lines.push("");
+    lines.push(sections.goal.trim());
+    lines.push("");
+  }
+
+  // User Stories
+  if (sections.userStories?.length > 0) {
+    lines.push("## User Stories");
+    lines.push("");
+    for (const story of sections.userStories) {
+      lines.push(`### As a ${story.persona}, I want to ${story.action}, so that ${story.benefit}`);
+      if (story.acceptanceCriteria?.length > 0) {
+        lines.push("");
+        lines.push("**Acceptance Criteria:**");
+        for (const criterion of story.acceptanceCriteria) {
+          lines.push(`- ${criterion}`);
+        }
+      }
+      lines.push("");
+    }
+  }
+
+  // Global Acceptance Criteria
+  if (sections.acceptanceCriteria?.length > 0) {
+    lines.push("## Acceptance Criteria");
+    lines.push("");
+    for (const criterion of sections.acceptanceCriteria) {
+      lines.push(`- ${criterion}`);
+    }
+    lines.push("");
+  }
+
+  // Edge Cases
+  if (sections.edgeCases?.length > 0) {
+    lines.push("## Edge Cases");
+    lines.push("");
+    for (const edge of sections.edgeCases) {
+      lines.push(`- **${edge.description}** — ${edge.resolution}`);
+    }
+    lines.push("");
+  }
+
+  // Failure States
+  if (sections.failureStates?.length > 0) {
+    lines.push("## Failure States");
+    lines.push("");
+    for (const failure of sections.failureStates) {
+      lines.push(`- **Trigger:** ${failure.trigger}`);
+      lines.push(`  - **Behavior:** ${failure.behavior}`);
+      lines.push(`  - **Recovery:** ${failure.recovery}`);
+    }
+    lines.push("");
+  }
+
+  // Dependencies
+  if (sections.dependencies?.length > 0) {
+    lines.push("## Dependencies");
+    lines.push("");
+    for (const dep of sections.dependencies) {
+      lines.push(`- **${dep.name}** — ${dep.description}`);
+    }
+    lines.push("");
+  }
+
+  // Out of Scope
+  if (sections.outOfScope?.length > 0) {
+    lines.push("## Out of Scope");
+    lines.push("");
+    for (const item of sections.outOfScope) {
+      lines.push(`- ${item}`);
+    }
+    lines.push("");
+  }
+
+  // Verification Criteria
+  if (sections.verificationCriteria?.length > 0) {
+    lines.push("## Verification Criteria");
+    lines.push("");
+    for (const vc of sections.verificationCriteria) {
+      lines.push(`- [${vc.type}] ${vc.description}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateAuth } from "./supabase.js";
+import {
+  listSpecs,
+  getSpec,
+  searchSpecs,
+  getSpecAsMarkdown,
+  listSpecsSchema,
+  getSpecSchema,
+  searchSpecsSchema,
+  getSpecMarkdownSchema,
+} from "./tools.js";
+
+const server = new McpServer({
+  name: "clearspec",
+  version: "0.1.0",
+});
+
+// --- Tool registrations ---
+
+server.tool(
+  "list_specs",
+  "List all your specs with title, status, and completeness score. Returns metadata only — use get_spec for full content.",
+  listSpecsSchema.shape,
+  async ({ status, project_id }) => {
+    try {
+      const specs = await listSpecs({ status, project_id });
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(specs, null, 2) }],
+      };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  "get_spec",
+  "Get a full spec with all sections (goal, user stories, edge cases, etc.). Use include_versions to also fetch version history.",
+  getSpecSchema.shape,
+  async ({ spec_id, include_versions }) => {
+    try {
+      const spec = await getSpec({ spec_id, include_versions });
+      if (!spec) {
+        return { content: [{ type: "text" as const, text: `Spec not found: ${spec_id}` }], isError: true };
+      }
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(spec, null, 2) }],
+      };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  "search_specs",
+  "Search specs by title keyword. Returns metadata only — use get_spec for full content.",
+  searchSpecsSchema.shape,
+  async ({ query }) => {
+    try {
+      const specs = await searchSpecs({ query });
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(specs, null, 2) }],
+      };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  "get_spec_as_markdown",
+  "Get a spec formatted as implementation-ready markdown with all sections: goal, user stories (with acceptance criteria), edge cases, failure states, dependencies, out of scope, and verification criteria.",
+  getSpecMarkdownSchema.shape,
+  async ({ spec_id }) => {
+    try {
+      const markdown = await getSpecAsMarkdown({ spec_id });
+      return {
+        content: [{ type: "text" as const, text: markdown }],
+      };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  }
+);
+
+// --- Start server ---
+
+async function main(): Promise<void> {
+  // Validate auth before accepting connections
+  await validateAuth();
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : "Unknown error";
+  process.stderr.write(`clearspec-mcp: ${message}\n`);
+  process.exit(1);
+});

package/src/supabase.ts

@@ -0,0 +1,74 @@
+// SYNC: Auth pattern differs from src/lib/supabase/server.ts — uses header injection, not cookies
+import { createClient as createSupabaseClient, type SupabaseClient } from "@supabase/supabase-js";
+
+// Default Supabase project — these are public values (same as the frontend)
+const DEFAULT_SUPABASE_URL = "https://adyjdccjwnrkzfzctfgo.supabase.co";
+const DEFAULT_SUPABASE_ANON_KEY = "sb_publishable_U1PJ3J1I-pJaSqKm4sBwyA_LUimFh44";
+
+interface EnvConfig {
+  supabaseUrl: string;
+  supabaseAnonKey: string;
+  accessToken: string;
+}
+
+function getEnvConfig(): EnvConfig {
+  const supabaseUrl = process.env.CLEARSPEC_SUPABASE_URL || DEFAULT_SUPABASE_URL;
+  const supabaseAnonKey = process.env.CLEARSPEC_SUPABASE_ANON_KEY || DEFAULT_SUPABASE_ANON_KEY;
+  const accessToken = process.env.CLEARSPEC_ACCESS_TOKEN;
+
+  if (!accessToken) {
+    throw new Error(
+      "Missing CLEARSPEC_ACCESS_TOKEN. Get one from ClearSpec Settings > MCP Integration."
+    );
+  }
+
+  return { supabaseUrl, supabaseAnonKey, accessToken };
+}
+
+let cachedClient: SupabaseClient | null = null;
+let cachedUserId: string | null = null;
+
+export function createClient(): SupabaseClient {
+  if (cachedClient) return cachedClient;
+
+  const { supabaseUrl, supabaseAnonKey, accessToken } = getEnvConfig();
+
+  cachedClient = createSupabaseClient(supabaseUrl, supabaseAnonKey, {
+    global: {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    },
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    },
+  });
+
+  return cachedClient;
+}
+
+/** Validate the token at startup and cache the user ID. */
+export async function validateAuth(): Promise<string> {
+  if (cachedUserId) return cachedUserId;
+
+  const supabase = createClient();
+  const { data, error } = await supabase.auth.getUser();
+
+  if (error || !data.user) {
+    throw new Error(
+      "Authentication failed. Your CLEARSPEC_ACCESS_TOKEN may be invalid or expired. " +
+      "Get a fresh token from ClearSpec Settings and restart the MCP server."
+    );
+  }
+
+  cachedUserId = data.user.id;
+  return cachedUserId;
+}
+
+export function getCachedUserId(): string {
+  if (!cachedUserId) {
+    throw new Error("Auth not validated yet. Call validateAuth() first.");
+  }
+  return cachedUserId;
+}

package/src/tools.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { createClient, getCachedUserId } from "./supabase.js";
+import { rowToSpec, rowToSpecMeta } from "./types.js";
+import type { Spec, SpecMeta } from "./types.js";
+import { formatSpecAsMarkdown } from "./format.js";
+
+const AUTH_ERROR_MSG =
+  "Authentication failed. Your token may have expired. " +
+  "Get a fresh token from ClearSpec Settings and restart the MCP server.";
+
+/** Check if an error is a Supabase auth error (expired/invalid token). */
+function isAuthError(error: unknown): boolean {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = (error as { code: string }).code;
+    return code === "PGRST301" || code === "401" || code === "403";
+  }
+  return false;
+}
+
+// --- Tool input schemas ---
+
+export const listSpecsSchema = z.object({
+  status: z.string().optional().describe("Filter by status (e.g. 'draft', 'ready_to_build', 'in_progress')"),
+  project_id: z.string().optional().describe("Filter by project ID"),
+});
+
+export const getSpecSchema = z.object({
+  spec_id: z.string().describe("The spec ID to retrieve"),
+  include_versions: z.boolean().optional().default(false).describe("Include version history (default: false)"),
+});
+
+export const searchSpecsSchema = z.object({
+  query: z.string().describe("Search term to match against spec titles"),
+});
+
+export const getSpecMarkdownSchema = z.object({
+  spec_id: z.string().describe("The spec ID to format as markdown"),
+});
+
+// --- Tool handlers ---
+
+export async function listSpecs(input: z.infer<typeof listSpecsSchema>): Promise<SpecMeta[]> {
+  const supabase = createClient();
+  const userId = getCachedUserId();
+
+  let query = supabase
+    .from("specs")
+    .select("id, title, status, completeness_score, project_id, updated_at")
+    .eq("user_id", userId)
+    .order("updated_at", { ascending: false });
+
+  if (input.status) {
+    query = query.eq("status", input.status);
+  }
+  if (input.project_id) {
+    query = query.eq("project_id", input.project_id);
+  }
+
+  const { data, error } = await query;
+
+  if (error) {
+    if (isAuthError(error)) throw new Error(AUTH_ERROR_MSG);
+    throw new Error(`Failed to list specs: ${error.message}`);
+  }
+
+  return (data || []).map((row) => rowToSpecMeta(row as Record<string, unknown>));
+}
+
+export async function getSpec(input: z.infer<typeof getSpecSchema>): Promise<Spec | null> {
+  const supabase = createClient();
+  const userId = getCachedUserId();
+
+  const specPromise = supabase
+    .from("specs")
+    .select("*")
+    .eq("id", input.spec_id)
+    .eq("user_id", userId)
+    .single();
+
+  if (input.include_versions) {
+    const [specResult, versionsResult] = await Promise.all([
+      specPromise,
+      supabase
+        .from("spec_versions")
+        .select("*")
+        .eq("spec_id", input.spec_id)
+        .order("version", { ascending: true }),
+    ]);
+
+    if (specResult.error) {
+      if (isAuthError(specResult.error)) throw new Error(AUTH_ERROR_MSG);
+      return null;
+    }
+
+    return rowToSpec(
+      specResult.data as Record<string, unknown>,
+      (versionsResult.data || []) as Record<string, unknown>[]
+    );
+  }
+
+  const { data, error } = await specPromise;
+
+  if (error) {
+    if (isAuthError(error)) throw new Error(AUTH_ERROR_MSG);
+    return null;
+  }
+
+  return rowToSpec(data as Record<string, unknown>);
+}
+
+export async function searchSpecs(input: z.infer<typeof searchSpecsSchema>): Promise<SpecMeta[]> {
+  const supabase = createClient();
+  const userId = getCachedUserId();
+
+  const { data, error } = await supabase
+    .from("specs")
+    .select("id, title, status, completeness_score, project_id, updated_at")
+    .eq("user_id", userId)
+    .ilike("title", `%${input.query}%`)
+    .order("updated_at", { ascending: false });
+
+  if (error) {
+    if (isAuthError(error)) throw new Error(AUTH_ERROR_MSG);
+    throw new Error(`Failed to search specs: ${error.message}`);
+  }
+
+  return (data || []).map((row) => rowToSpecMeta(row as Record<string, unknown>));
+}
+
+export async function getSpecAsMarkdown(input: z.infer<typeof getSpecMarkdownSchema>): Promise<string> {
+  const spec = await getSpec({ spec_id: input.spec_id, include_versions: false });
+
+  if (!spec) {
+    throw new Error(`Spec not found: ${input.spec_id}`);
+  }
+
+  return formatSpecAsMarkdown(spec);
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+// SYNC: copied from src/types/spec.ts — keep in sync when spec schema changes
+
+export interface UserStory {
+  id: string;
+  persona: string;
+  action: string;
+  benefit: string;
+  acceptanceCriteria: string[];
+}
+
+export interface EdgeCase {
+  id: string;
+  description: string;
+  resolution: string;
+}
+
+export interface FailureState {
+  id: string;
+  trigger: string;
+  behavior: string;
+  recovery: string;
+}
+
+export interface Dependency {
+  id: string;
+  name: string;
+  description: string;
+}
+
+export interface VerificationCriterion {
+  id: string;
+  description: string;
+  type: "automated" | "manual";
+}
+
+export interface SpecSection {
+  goal: string;
+  userStories: UserStory[];
+  acceptanceCriteria: string[];
+  edgeCases: EdgeCase[];
+  failureStates: FailureState[];
+  dependencies: Dependency[];
+  outOfScope: string[];
+  verificationCriteria: VerificationCriterion[];
+}
+
+export type SpecStatus =
+  | "draft"
+  | "in_review"
+  | "approved"
+  | "in_development"
+  | "delivered"
+  | "in_progress"
+  | "ready_to_build"
+  | "archived";
+
+export interface Spec {
+  id: string;
+  title: string;
+  status: SpecStatus;
+  completenessScore: number;
+  sections: SpecSection;
+  projectId: string | null;
+  isSample: boolean;
+  shareToken: string | null;
+  sharePermission: "view" | "comment" | "edit";
+  repoFullName: string | null;
+  linearIssueId: string | null;
+  linearIssueUrl: string | null;
+  createdAt: string;
+  updatedAt: string;
+  versions: SpecVersion[];
+}
+
+export interface SpecVersion {
+  id: string;
+  specId: string;
+  version: number;
+  sections: SpecSection;
+  changeNote: string | null;
+  changedById: string | null;
+  createdAt: string;
+}
+
+/** Metadata-only shape for list_specs (no sections/versions). */
+export interface SpecMeta {
+  id: string;
+  title: string;
+  status: SpecStatus;
+  completenessScore: number;
+  projectId: string | null;
+  updatedAt: string;
+}
+
+// SYNC: copied from src/lib/store/specs.ts rowToSpec()
+export function rowToSpec(row: Record<string, unknown>, versions: Record<string, unknown>[] = []): Spec {
+  return {
+    id: row.id as string,
+    title: row.title as string,
+    status: row.status as Spec["status"],
+    completenessScore: row.completeness_score as number,
+    sections: row.sections as SpecSection,
+    projectId: (row.project_id as string) || null,
+    isSample: (row.is_sample as boolean) ?? false,
+    shareToken: (row.share_token as string) ?? null,
+    sharePermission: (row.share_permission as Spec["sharePermission"]) ?? "view",
+    repoFullName: (row.repo_full_name as string) ?? null,
+    linearIssueId: (row.linear_issue_id as string) ?? null,
+    linearIssueUrl: (row.linear_issue_url as string) ?? null,
+    createdAt: row.created_at as string,
+    updatedAt: row.updated_at as string,
+    versions: versions.map((v) => ({
+      id: v.id as string,
+      specId: v.spec_id as string,
+      version: v.version as number,
+      sections: v.sections as SpecSection,
+      changeNote: (v.change_note as string) ?? null,
+      changedById: (v.changed_by_id as string) ?? null,
+      createdAt: v.created_at as string,
+    })),
+  };
+}
+
+export function rowToSpecMeta(row: Record<string, unknown>): SpecMeta {
+  return {
+    id: row.id as string,
+    title: row.title as string,
+    status: row.status as SpecStatus,
+    completenessScore: row.completeness_score as number,
+    projectId: (row.project_id as string) || null,
+    updatedAt: row.updated_at as string,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}