@atoms-tech/atoms-mcp 0.1.0 → 0.2.0

package/dist/tools/trace.js

@@ -0,0 +1,166 @@
+/**
+ * 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)));
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/tools/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/tools/trace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atoms-tech/atoms-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for ATOMS.tech — AI agent integration for requirements management",
   "type": "module",
   "main": "dist/index.js",