@atoms-tech/atoms-mcp 0.3.0 → 0.3.1

package/dist/tools/export-mermaid.d.ts

@@ -1,35 +0,0 @@
-/**
- * atoms_export_mermaid — Generate Mermaid diagram of requirement/test hierarchy.
- * Output is paste-ready for markdown documentation.
- */
-export declare function exportMermaidHandler(params: {
-    project_id: string;
-    root_item_id?: string;
-    depth: number;
-    include_tests: boolean;
-}): Promise<{
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: {
-        data: any[];
-        meta: {
-            truncated: boolean;
-            truncation_message: string;
-            total_count?: number | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-            has_more?: boolean | undefined;
-        };
-        status: "success";
-    };
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<{
-        mermaid: string;
-    }>;
-}>;

package/dist/tools/export-mermaid.js

@@ -1,124 +0,0 @@
-/**
- * atoms_export_mermaid — Generate Mermaid diagram of requirement/test hierarchy.
- * Output is paste-ready for markdown documentation.
- */
-import { getClient } from "../db/client.js";
-import { formatToolResult, formatErrorResult, success, dbError, authError, } from "./_base.js";
-export async function exportMermaidHandler(params) {
-    try {
-        const client = await getClient();
-        // Get all items in the project
-        const { data: items, error: itemsErr } = await client
-            .from("items")
-            .select("id, title, type, data")
-            .eq("project_id", params.project_id)
-            .is("deleted_at", null);
-        if (itemsErr)
-            throw new Error(itemsErr.message);
-        if (!items || items.length === 0) {
-            return formatToolResult(success({ mermaid: "graph TD\n  empty[No items in project]" }));
-        }
-        // Get all relationships
-        const { data: rels, error: relsErr } = await client
-            .from("item_relationships")
-            .select("from_id, to_id, type")
-            .eq("project_id", params.project_id);
-        if (relsErr)
-            throw new Error(relsErr.message);
-        const itemMap = new Map();
-        for (const item of items) {
-            itemMap.set(item.id, item);
-        }
-        // Build Mermaid graph
-        const lines = ["graph TD"];
-        const visited = new Set();
-        const edges = new Set();
-        // Find root nodes (items with no parents)
-        const childIds = new Set((rels ?? []).filter((r) => r.type === "child").map((r) => r.to_id));
-        const parentIds = new Set((rels ?? []).filter((r) => r.type === "parent").map((r) => r.from_id));
-        let roots;
-        if (params.root_item_id) {
-            roots = [params.root_item_id];
-        }
-        else {
-            // Items that are not children of anything
-            roots = items
-                .filter((item) => !parentIds.has(item.id))
-                .filter((item) => {
-                if (!params.include_tests && item.type === "test-case")
-                    return false;
-                return true;
-            })
-                .map((item) => item.id);
-        }
-        // BFS to build graph up to depth
-        const queue = roots.map((id) => ({
-            id,
-            depth: 0,
-        }));
-        while (queue.length > 0) {
-            const { id, depth } = queue.shift();
-            if (visited.has(id) || depth > params.depth)
-                continue;
-            visited.add(id);
-            const item = itemMap.get(id);
-            if (!item)
-                continue;
-            // Skip test cases if not included
-            if (!params.include_tests && item.type === "test-case")
-                continue;
-            // Add node
-            const label = sanitizeLabel(item.title);
-            const shape = item.type === "requirement"
-                ? `["${label}"]`
-                : item.type === "test-case"
-                    ? `(["${label}"])`
-                    : `("${label}")`;
-            lines.push(`  ${id}${shape}`);
-            // Add edges from relationships
-            for (const rel of rels ?? []) {
-                if (rel.from_id !== id)
-                    continue;
-                const targetItem = itemMap.get(rel.to_id);
-                if (!targetItem)
-                    continue;
-                if (!params.include_tests && targetItem.type === "test-case")
-                    continue;
-                const edgeKey = `${rel.from_id}-${rel.type}-${rel.to_id}`;
-                if (edges.has(edgeKey))
-                    continue;
-                edges.add(edgeKey);
-                if (rel.type === "child") {
-                    lines.push(`  ${id} --> ${rel.to_id}`);
-                }
-                else if (rel.type === "verified_by") {
-                    lines.push(`  ${id} -.->|verified_by| ${rel.to_id}`);
-                }
-                else if (rel.type === "related") {
-                    lines.push(`  ${id} -.- ${rel.to_id}`);
-                }
-                if (!visited.has(rel.to_id) && depth + 1 <= params.depth) {
-                    queue.push({ id: rel.to_id, depth: depth + 1 });
-                }
-            }
-        }
-        const mermaid = lines.join("\n");
-        return formatToolResult(success({
-            mermaid,
-            node_count: visited.size,
-            edge_count: edges.size,
-        }));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}
-function sanitizeLabel(title) {
-    return title
-        .replace(/"/g, "'")
-        .replace(/[[\]{}()]/g, "")
-        .substring(0, 50);
-}

package/dist/tools/get-coverage.d.ts

@@ -1,33 +0,0 @@
-/**
- * atoms_get_coverage — Find requirements without linked test cases.
- * Essential for compliance reporting in safety-critical industries.
- */
-import type { CoverageReport } from "../types/responses.js";
-export declare function getCoverageHandler(params: {
-    project_id: string;
-    domain?: string;
-    level?: string;
-}): Promise<{
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: {
-        data: any[];
-        meta: {
-            truncated: boolean;
-            truncation_message: string;
-            total_count?: number | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-            has_more?: boolean | undefined;
-        };
-        status: "success";
-    };
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<CoverageReport>;
-}>;

package/dist/tools/get-coverage.js

@@ -1,35 +0,0 @@
-/**
- * atoms_get_coverage — Find requirements without linked test cases.
- * Essential for compliance reporting in safety-critical industries.
- */
-import { getClient } from "../db/client.js";
-import { getCoverageReport } from "../db/queries.js";
-import { formatToolResult, formatErrorResult, success, dbError, authError, } from "./_base.js";
-export async function getCoverageHandler(params) {
-    try {
-        const client = await getClient();
-        const { covered, uncovered, total } = await getCoverageReport(client, params.project_id, { domain: params.domain, level: params.level });
-        const uncoveredItems = uncovered.map((item) => ({
-            id: item.id,
-            title: item.title,
-            type: item.type,
-            status: item.data?.status,
-            domains: item.data?.tags?.domains ?? [],
-            level: item.data?.tags?.level,
-        }));
-        const report = {
-            covered: covered.length,
-            uncovered: uncovered.length,
-            total,
-            coverage_percent: total > 0 ? Math.round((covered.length / total) * 1000) / 10 : 100,
-            uncovered_items: uncoveredItems,
-        };
-        return formatToolResult(success(report));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}

package/dist/tools/get-history.d.ts

@@ -1,33 +0,0 @@
-/**
- * atoms_get_history — Audit trail for an item.
- * Shows who changed what, when, and whether it was human or AI.
- */
-import type { HistoryEntry } from "../types/responses.js";
-export declare function getHistoryHandler(params: {
-    project_id: string;
-    item_id: string;
-    limit: number;
-}): Promise<{
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: {
-        data: any[];
-        meta: {
-            truncated: boolean;
-            truncation_message: string;
-            total_count?: number | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-            has_more?: boolean | undefined;
-        };
-        status: "success";
-    };
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<HistoryEntry[]>;
-}>;

package/dist/tools/get-history.js

@@ -1,52 +0,0 @@
-/**
- * atoms_get_history — Audit trail for an item.
- * Shows who changed what, when, and whether it was human or AI.
- */
-import { getClient } from "../db/client.js";
-import { getChangeHistory } from "../db/queries.js";
-import { formatToolResult, formatErrorResult, success, paginationMeta, dbError, authError, } from "./_base.js";
-export async function getHistoryHandler(params) {
-    try {
-        const client = await getClient();
-        const history = await getChangeHistory(client, params.project_id, params.item_id, params.limit);
-        const entries = history.map((entry) => {
-            // Compute which fields changed by comparing old_data and new_data
-            const fieldsChanged = [];
-            const oldData = entry.old_data;
-            const newData = entry.new_data;
-            if (oldData && newData) {
-                const allKeys = new Set([
-                    ...Object.keys(oldData),
-                    ...Object.keys(newData),
-                ]);
-                for (const key of allKeys) {
-                    if (JSON.stringify(oldData[key]) !== JSON.stringify(newData[key])) {
-                        fieldsChanged.push(key);
-                    }
-                }
-            }
-            else if (newData) {
-                fieldsChanged.push("(created)");
-            }
-            else if (oldData) {
-                fieldsChanged.push("(deleted)");
-            }
-            return {
-                id: entry.id,
-                event_type: entry.event_type,
-                changed_by: entry.changed_by ?? null,
-                changed_at: entry.changed_at,
-                actor: entry.actor ?? "user",
-                session_id: entry.session_id ?? null,
-                fields_changed: fieldsChanged,
-            };
-        });
-        return formatToolResult(success(entries, paginationMeta(entries.length, params.limit, 0)));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}

package/dist/tools/get-item.d.ts

@@ -1,61 +0,0 @@
-/**
- * atoms_get_item — Get full item details including relationships and test history.
- */
-export declare function getItemHandler(params: {
-    project_id: string;
-    item_id: string;
-}): Promise<{
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: {
-        data: any[];
-        meta: {
-            truncated: boolean;
-            truncation_message: string;
-            total_count?: number | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-            has_more?: boolean | undefined;
-        };
-        status: "success";
-    };
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<{
-        metadata: {
-            created_at: string;
-            created_by: string | null;
-            updated_at: string;
-            updated_by: string | null;
-            source_id: string | undefined;
-        };
-        latest_result?: string | undefined;
-        test_results?: {
-            result: string;
-            run_by: string | null;
-            run_at: string;
-            note: string | null;
-        }[] | undefined;
-        id: string;
-        type: string;
-        title: string;
-        summary: string | undefined;
-        body: string | undefined;
-        tags: import("../types/work-item.js").WorkItemTags;
-        ownership: import("../types/work-item.js").WorkItemOwnership;
-        relationships: {
-            parents: string[];
-            children: string[];
-            related: string[];
-            verified_by: string[];
-            verifies: string[];
-        };
-        links: import("../types/work-item.js").WorkItemLink[];
-        status: "passed" | "failed" | "blocked" | "not-run" | undefined;
-    }>;
-}>;

package/dist/tools/get-item.js

@@ -1,92 +0,0 @@
-/**
- * atoms_get_item — Get full item details including relationships and test history.
- */
-import { getClient } from "../db/client.js";
-import { getItemById, getItemRelationships } from "../db/queries.js";
-import { formatToolResult, formatErrorResult, success, notFoundError, dbError, authError, } from "./_base.js";
-export async function getItemHandler(params) {
-    try {
-        const client = await getClient();
-        const item = await getItemById(client, params.project_id, params.item_id);
-        if (!item) {
-            return formatErrorResult(notFoundError("Item", params.item_id));
-        }
-        // Enrich with relationship data from shadow table
-        const relationships = await getItemRelationships(client, params.project_id, params.item_id);
-        // Build structured relationship map
-        const relMap = {
-            parents: [],
-            children: [],
-            related: [],
-            verified_by: [],
-            verifies: [],
-        };
-        for (const rel of relationships) {
-            if (rel.from_id === params.item_id) {
-                // Outgoing relationship
-                if (rel.type in relMap) {
-                    relMap[rel.type].push(rel.to_id);
-                }
-            }
-            else {
-                // Incoming relationship — invert the type
-                const inverse = {
-                    parent: "children",
-                    child: "parents",
-                    verified_by: "verifies",
-                    verifies: "verified_by",
-                    related: "related",
-                };
-                const key = inverse[rel.type] ?? rel.type;
-                if (key in relMap) {
-                    relMap[key].push(rel.from_id);
-                }
-            }
-        }
-        // For test cases, fetch test results from shadow table
-        let testResults = [];
-        if (item.type === "test-case") {
-            const { data: results, error: resultsErr } = await client
-                .from("test_results")
-                .select("result, run_by, run_at, note")
-                .eq("item_id", params.item_id)
-                .eq("project_id", params.project_id)
-                .order("run_at", { ascending: false })
-                .limit(20);
-            if (!resultsErr && results) {
-                testResults = results;
-            }
-        }
-        const data = {
-            id: item.id,
-            type: item.type,
-            title: item.title,
-            summary: item.data?.summary,
-            body: item.data?.body,
-            tags: item.data?.tags ?? { domains: [] },
-            ownership: item.data?.ownership ?? { primary: null, additional: [] },
-            relationships: relMap,
-            links: item.data?.links ?? [],
-            status: item.data?.status,
-            // Test results from shadow table (for test cases)
-            ...(item.type === "test-case" ? {
-                latest_result: testResults[0]?.result ?? "not-run",
-                test_results: testResults,
-            } : {}),
-            metadata: {
-                created_at: item.created_at,
-                created_by: item.created_by,
-                updated_at: item.updated_at,
-                updated_by: item.updated_by,
-                source_id: item.data?.metadata?.source_id,
-            },
-        };
-        return formatToolResult(success(data));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}

package/dist/tools/link-items.d.ts

@@ -1,40 +0,0 @@
-/**
- * atoms_link_items — Add or remove relationships between items.
- * Updates both items' JSONB data and the shadow table.
- */
-export declare function linkItemsHandler(params: {
-    project_id: string;
-    from_id: string;
-    to_id: string;
-    type: "parent" | "child" | "related" | "verifies" | "verified_by";
-    action: "add" | "remove";
-}): Promise<{
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: {
-        data: any[];
-        meta: {
-            truncated: boolean;
-            truncation_message: string;
-            total_count?: number | undefined;
-            limit?: number | undefined;
-            offset?: number | undefined;
-            has_more?: boolean | undefined;
-        };
-        status: "success";
-    };
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<{
-        action: "add" | "remove";
-        type: "parent" | "verified_by" | "child" | "verifies" | "related";
-        from_id: string;
-        to_id: string;
-        message: string;
-    }>;
-}>;

package/dist/tools/link-items.js

@@ -1,149 +0,0 @@
-/**
- * atoms_link_items — Add or remove relationships between items.
- * Updates both items' JSONB data and the shadow table.
- */
-import { getClient, getUserId, requireWriteAccess } from "../db/client.js";
-import { getItemById } from "../db/queries.js";
-import { getMcpSessionId } from "../server.js";
-import { formatToolResult, formatErrorResult, success, notFoundError, accessDeniedError, validationError, dbError, authError, } from "./_base.js";
-export async function linkItemsHandler(params) {
-    try {
-        const client = await getClient();
-        const userId = getUserId();
-        // Validate: no self-referencing
-        if (params.from_id === params.to_id) {
-            return formatErrorResult(validationError("Cannot create a relationship between an item and itself"));
-        }
-        // Check write access
-        try {
-            await requireWriteAccess(client, params.project_id);
-        }
-        catch (err) {
-            if (err instanceof Error && err.message === "VIEWER_ROLE") {
-                return formatErrorResult(accessDeniedError("Viewer"));
-            }
-            throw err;
-        }
-        // Verify both items exist
-        const fromItem = await getItemById(client, params.project_id, params.from_id);
-        if (!fromItem) {
-            return formatErrorResult(notFoundError("Item", params.from_id));
-        }
-        const toItem = await getItemById(client, params.project_id, params.to_id);
-        if (!toItem) {
-            return formatErrorResult(notFoundError("Item", params.to_id));
-        }
-        if (params.action === "add") {
-            // Check if relationship already exists
-            const { data: existing } = await client
-                .from("item_relationships")
-                .select("from_id")
-                .eq("from_id", params.from_id)
-                .eq("to_id", params.to_id)
-                .eq("type", params.type)
-                .eq("project_id", params.project_id)
-                .maybeSingle();
-            if (!existing) {
-                const { error: relErr } = await client
-                    .from("item_relationships")
-                    .insert({
-                    from_id: params.from_id,
-                    to_id: params.to_id,
-                    type: params.type,
-                    project_id: params.project_id,
-                });
-                if (relErr)
-                    throw new Error(relErr.message);
-            }
-            // Update JSONB data on the from item
-            const fromData = { ...fromItem.data };
-            const relKey = params.type === "verified_by" || params.type === "verifies"
-                ? params.type
-                : params.type + "s" === "parents" ? "parents"
-                    : params.type === "parent" ? "parents"
-                        : params.type === "child" ? "children"
-                            : "related";
-            const relField = relKey;
-            if (fromData.relationships) {
-                const existing = fromData.relationships[relField] ?? [];
-                if (!existing.includes(params.to_id)) {
-                    fromData.relationships[relField] = [
-                        ...existing,
-                        params.to_id,
-                    ];
-                }
-            }
-            await client
-                .from("items")
-                .update({ data: fromData, updated_by: userId })
-                .eq("id", params.from_id)
-                .eq("project_id", params.project_id);
-        }
-        else {
-            // Remove from shadow table
-            const { error: delErr } = await client
-                .from("item_relationships")
-                .delete()
-                .eq("from_id", params.from_id)
-                .eq("to_id", params.to_id)
-                .eq("type", params.type)
-                .eq("project_id", params.project_id);
-            if (delErr)
-                throw new Error(delErr.message);
-            // Update JSONB data on the from item
-            const fromData = { ...fromItem.data };
-            const relKey = params.type === "parent" ? "parents"
-                : params.type === "child" ? "children"
-                    : params.type;
-            const relField = relKey;
-            if (fromData.relationships) {
-                const existing = fromData.relationships[relField] ?? [];
-                fromData.relationships[relField] =
-                    existing.filter((id) => id !== params.to_id);
-            }
-            await client
-                .from("items")
-                .update({ data: fromData, updated_by: userId })
-                .eq("id", params.from_id)
-                .eq("project_id", params.project_id);
-        }
-        // Audit log
-        await client
-            .from("change_history")
-            .insert({
-            item_id: params.from_id,
-            project_id: params.project_id,
-            changed_by: userId,
-            event_type: "updated",
-            old_data: null,
-            new_data: {
-                relationship_change: {
-                    action: params.action,
-                    type: params.type,
-                    from: params.from_id,
-                    to: params.to_id,
-                },
-            },
-            actor: "mcp_claude",
-            session_id: getMcpSessionId(),
-        })
-            .then(({ error }) => {
-            if (error) {
-                process.stderr.write(`[atoms-mcp] Warning: change_history log failed: ${error.message}\n`);
-            }
-        });
-        return formatToolResult(success({
-            action: params.action,
-            type: params.type,
-            from_id: params.from_id,
-            to_id: params.to_id,
-            message: `Relationship ${params.action === "add" ? "added" : "removed"}: ${params.from_id} --[${params.type}]--> ${params.to_id}`,
-        }));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}