@atoms-tech/atoms-mcp 0.3.0 → 0.3.1

package/dist/tools/trace.js

@@ -1,165 +0,0 @@
-/**
- * atoms_trace — Graph traversal for traceability queries.
- *
- * Answers questions like "which requirements does TC-00003 verify?"
- * or "what's affected if I change REQ-00001?"
- */
-import { getClient } from "../db/client.js";
-import { getItemById } from "../db/queries.js";
-import { formatToolResult, formatErrorResult, success, notFoundError, dbError, authError, } from "./_base.js";
-/** Maximum items returned to prevent huge responses. */
-const MAX_ITEMS = 200;
-/** Relationship types that point "upstream" (toward parents / dependencies). */
-const UPSTREAM_TYPES = ["parent", "verifies"];
-/** Relationship types that point "downstream" (toward dependents). */
-const DOWNSTREAM_TYPES = ["child", "verified_by"];
-/**
- * Inverse mapping: when traversing an incoming edge we need
- * to know what the outgoing type means for the other side.
- */
-const INVERSE_TYPE = {
-    parent: "child",
-    child: "parent",
-    verifies: "verified_by",
-    verified_by: "verifies",
-    related: "related",
-};
-export async function traceHandler(params) {
-    try {
-        const maxDepth = Math.min(Math.max(params.depth ?? 5, 1), 10);
-        const client = await getClient();
-        // Verify root item exists
-        const rootItem = await getItemById(client, params.project_id, params.item_id);
-        if (!rootItem) {
-            return formatErrorResult(notFoundError("Item", params.item_id));
-        }
-        // Fetch all relationships in the project once (same pattern as export-mermaid)
-        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);
-        // Fetch all non-deleted items for title/type lookup
-        const { data: items, error: itemsErr } = await client
-            .from("items")
-            .select("id, title, type")
-            .eq("project_id", params.project_id)
-            .is("deleted_at", null);
-        if (itemsErr)
-            throw new Error(itemsErr.message);
-        const itemMap = new Map();
-        for (const item of items ?? []) {
-            itemMap.set(item.id, { title: item.title, type: item.type });
-        }
-        // Build adjacency lists based on direction
-        // For each item, we store { neighbor, relType, direction }
-        const adjacency = new Map();
-        const addEdge = (from, to, relType) => {
-            if (!adjacency.has(from))
-                adjacency.set(from, []);
-            adjacency.get(from).push({ neighbor: to, relType });
-        };
-        const allowedTypes = params.relationship_types
-            ? new Set(params.relationship_types)
-            : null;
-        for (const rel of rels ?? []) {
-            const relType = rel.type;
-            // Upstream: follow edges where the item is the source and the rel points upstream
-            // i.e., from_id -> to_id with type "parent" or "verifies"
-            if (params.direction === "upstream" || params.direction === "both") {
-                if (UPSTREAM_TYPES.includes(relType)) {
-                    if (!allowedTypes || allowedTypes.has(relType)) {
-                        addEdge(rel.from_id, rel.to_id, relType);
-                    }
-                }
-                // Also follow inverse: if from_id has a "child" pointing to to_id,
-                // then to_id is upstream of from_id — but we model it as:
-                // from_id's downstream is to_id via "child". For upstream from to_id,
-                // we'd follow to_id -> from_id via inverse of "child" = "parent".
-                if (DOWNSTREAM_TYPES.includes(relType)) {
-                    const inverseType = INVERSE_TYPE[relType] ?? relType;
-                    if (!allowedTypes || allowedTypes.has(inverseType)) {
-                        addEdge(rel.to_id, rel.from_id, inverseType);
-                    }
-                }
-            }
-            if (params.direction === "downstream" || params.direction === "both") {
-                if (DOWNSTREAM_TYPES.includes(relType)) {
-                    if (!allowedTypes || allowedTypes.has(relType)) {
-                        addEdge(rel.from_id, rel.to_id, relType);
-                    }
-                }
-                // Inverse: upstream type from the other side means downstream for us
-                if (UPSTREAM_TYPES.includes(relType)) {
-                    const inverseType = INVERSE_TYPE[relType] ?? relType;
-                    if (!allowedTypes || allowedTypes.has(inverseType)) {
-                        addEdge(rel.to_id, rel.from_id, inverseType);
-                    }
-                }
-            }
-            // "related" is bidirectional — add both directions if allowed
-            if (relType === "related") {
-                if (!allowedTypes || allowedTypes.has("related")) {
-                    addEdge(rel.from_id, rel.to_id, "related");
-                    addEdge(rel.to_id, rel.from_id, "related");
-                }
-            }
-        }
-        // BFS traversal from root
-        const visited = new Set();
-        visited.add(params.item_id);
-        const result = [];
-        const queue = [];
-        // Seed queue with direct neighbors of the root
-        const rootNeighbors = adjacency.get(params.item_id) ?? [];
-        for (const edge of rootNeighbors) {
-            queue.push({ id: edge.neighbor, depth: 1, relType: edge.relType });
-        }
-        while (queue.length > 0 && result.length < MAX_ITEMS) {
-            const { id, depth, relType } = queue.shift();
-            if (visited.has(id) || depth > maxDepth)
-                continue;
-            visited.add(id);
-            const info = itemMap.get(id);
-            if (!info)
-                continue; // skip deleted items
-            result.push({
-                id,
-                title: info.title,
-                type: info.type,
-                relationship: relType,
-                depth,
-            });
-            // Enqueue neighbors at next depth
-            if (depth < maxDepth) {
-                const neighbors = adjacency.get(id) ?? [];
-                for (const edge of neighbors) {
-                    if (!visited.has(edge.neighbor)) {
-                        queue.push({
-                            id: edge.neighbor,
-                            depth: depth + 1,
-                            relType: edge.relType,
-                        });
-                    }
-                }
-            }
-        }
-        return formatToolResult(success({
-            root: params.item_id,
-            direction: params.direction,
-            depth_limit: maxDepth,
-            items: result,
-            total_count: result.length,
-            ...(result.length >= MAX_ITEMS
-                ? { truncated: true, truncation_message: `Results capped at ${MAX_ITEMS} items. Use a smaller depth or filter by relationship_types.` }
-                : {}),
-        }));
-    }
-    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/update-item.d.ts

@@ -1,42 +0,0 @@
-/**
- * atoms_update_item — Update an existing item's fields.
- * Requires editor or admin role. Logs old/new diff to change_history.
- */
-export declare function updateItemHandler(params: {
-    project_id: string;
-    item_id: string;
-    title?: string;
-    body?: string;
-    summary?: string;
-    domains?: string[];
-    level?: string;
-    status?: "passed" | "failed" | "blocked" | "not-run";
-}): 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<{
-        id: string;
-        title: string;
-        type: string;
-        updated_fields: string[];
-    }>;
-}>;

package/dist/tools/update-item.js

@@ -1,97 +0,0 @@
-/**
- * atoms_update_item — Update an existing item's fields.
- * Requires editor or admin role. Logs old/new diff to change_history.
- */
-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, dbError, authError, } from "./_base.js";
-export async function updateItemHandler(params) {
-    try {
-        const client = await getClient();
-        const userId = getUserId();
-        // 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;
-        }
-        // Get existing item
-        const existing = await getItemById(client, params.project_id, params.item_id);
-        if (!existing) {
-            return formatErrorResult(notFoundError("Item", params.item_id));
-        }
-        // Build updated data blob
-        const oldData = { ...existing.data };
-        const updatedData = { ...existing.data };
-        if (params.title !== undefined) {
-            updatedData.title = params.title;
-        }
-        if (params.body !== undefined) {
-            updatedData.body = params.body;
-        }
-        if (params.summary !== undefined) {
-            updatedData.summary = params.summary;
-        }
-        if (params.domains !== undefined) {
-            updatedData.tags = { ...updatedData.tags, domains: params.domains };
-        }
-        if (params.level !== undefined) {
-            updatedData.tags = { ...updatedData.tags, level: params.level };
-        }
-        if (params.status !== undefined) {
-            updatedData.status = params.status;
-        }
-        updatedData.metadata = {
-            ...updatedData.metadata,
-            updated_at: new Date().toISOString(),
-            updated_by: userId,
-        };
-        // Update in database
-        const { error: updateErr } = await client
-            .from("items")
-            .update({
-            title: params.title ?? existing.title,
-            data: updatedData,
-            updated_by: userId,
-        })
-            .eq("id", params.item_id)
-            .eq("project_id", params.project_id);
-        if (updateErr)
-            throw new Error(updateErr.message);
-        // Audit: log diff to change_history
-        await client
-            .from("change_history")
-            .insert({
-            item_id: params.item_id,
-            project_id: params.project_id,
-            changed_by: userId,
-            event_type: "updated",
-            old_data: oldData,
-            new_data: updatedData,
-            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({
-            id: params.item_id,
-            title: updatedData.title,
-            type: existing.type,
-            updated_fields: Object.keys(params).filter((k) => k !== "project_id" && k !== "item_id" && params[k] !== undefined),
-        }));
-    }
-    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/types/responses.d.ts

@@ -1,57 +0,0 @@
-/**
- * Standard response envelopes for all MCP tool responses.
- * Every tool returns JSON matching one of these shapes.
- */
-export interface ToolSuccess<T = unknown> {
-    [key: string]: unknown;
-    status: "success";
-    data: T;
-    meta?: PaginationMeta;
-}
-export interface ToolError {
-    [key: string]: unknown;
-    status: "error";
-    message: string;
-    next_steps: string[];
-}
-export interface PaginationMeta {
-    [key: string]: unknown;
-    total_count: number;
-    limit: number;
-    offset: number;
-    has_more: boolean;
-}
-export type ToolResponse<T = unknown> = ToolSuccess<T> | ToolError;
-/**
- * Item summary returned by list/search tools (@basic fields).
- */
-export interface ItemSummary {
-    id: string;
-    title: string;
-    type: string;
-    status?: string;
-    domains: string[];
-    level?: string;
-}
-/**
- * Coverage report returned by atoms_get_coverage.
- */
-export interface CoverageReport {
-    covered: number;
-    uncovered: number;
-    total: number;
-    coverage_percent: number;
-    uncovered_items: ItemSummary[];
-}
-/**
- * Change history entry returned by atoms_get_history.
- */
-export interface HistoryEntry {
-    id: string;
-    event_type: string;
-    changed_by: string | null;
-    changed_at: string;
-    actor: string;
-    session_id: string | null;
-    fields_changed: string[];
-}

package/dist/types/responses.js

@@ -1,5 +0,0 @@
-/**
- * Standard response envelopes for all MCP tool responses.
- * Every tool returns JSON matching one of these shapes.
- */
-export {};

package/dist/types/work-item.d.ts

@@ -1,68 +0,0 @@
-/**
- * WorkItem type definition — shared with the ATOMS frontend.
- * Source of truth: src/app/types.ts in the main app.
- *
- * This is a subset focused on what the MCP server needs.
- */
-export interface WorkItemRelationships {
-    parents: string[];
-    children: string[];
-    related: string[];
-    verified_by?: string[];
-    verifies?: string[];
-}
-export interface WorkItemOwnership {
-    primary: string | null;
-    additional: string[];
-}
-export interface WorkItemTags {
-    domains: string[];
-    level?: string;
-}
-export interface TestRun {
-    date: string;
-    result: "passed" | "failed" | "blocked" | "not-run";
-    by: string;
-    note?: string;
-}
-export interface WorkItemLink {
-    url: string;
-    label: string;
-}
-export interface WorkItemMetadata {
-    created_at: string;
-    created_by: string;
-    updated_at: string;
-    updated_by: string;
-    source_id?: string;
-    imported_at?: string;
-}
-export interface WorkItem {
-    id: string;
-    type: "requirement" | "test-case" | "note" | "table";
-    title: string;
-    summary?: string;
-    body?: string;
-    tags: WorkItemTags;
-    ownership: WorkItemOwnership;
-    relationships: WorkItemRelationships;
-    links: WorkItemLink[];
-    status?: "passed" | "failed" | "blocked" | "not-run";
-    runs?: TestRun[];
-    metadata: WorkItemMetadata;
-}
-/**
- * Database row shape from Supabase items table.
- */
-export interface ItemRow {
-    id: string;
-    project_id: string;
-    type: string;
-    title: string;
-    data: WorkItem;
-    created_by: string | null;
-    updated_by: string | null;
-    created_at: string;
-    updated_at: string;
-    deleted_at: string | null;
-}

package/dist/types/work-item.js

@@ -1,7 +0,0 @@
-/**
- * WorkItem type definition — shared with the ATOMS frontend.
- * Source of truth: src/app/types.ts in the main app.
- *
- * This is a subset focused on what the MCP server needs.
- */
-export {};