@atoms-tech/atoms-mcp 0.3.0 → 0.3.1

package/dist/tools/_base.d.ts

@@ -1,57 +0,0 @@
-/**
- * Shared error handling and response formatting for all MCP tools.
- *
- * Every error MUST include `next_steps` — actionable guidance for the LLM.
- * This is the #1 pattern from the Polarion MCP that improves agent reliability.
- */
-import type { ToolError, ToolSuccess, PaginationMeta } from "../types/responses.js";
-/** Maximum response size in characters. Truncate with clear message if exceeded. */
-export declare const CHARACTER_LIMIT = 25000;
-export declare function success<T>(data: T, meta?: PaginationMeta): ToolSuccess<T>;
-export declare function paginationMeta(totalCount: number, limit: number, offset: number): PaginationMeta;
-export declare function errorResponse(message: string, nextSteps: string[]): ToolError;
-export declare function notFoundError(resource: string, id: string): ToolError;
-export declare function accessDeniedError(role: string): ToolError;
-export declare function validationError(message: string): ToolError;
-export declare function authError(): ToolError;
-export declare function rateLimitError(retryAfterSeconds: number): ToolError;
-export declare function dbError(message: string): ToolError;
-/**
- * Format a tool result as JSON string + structuredContent for the MCP SDK.
- * Applies CHARACTER_LIMIT truncation if needed.
- */
-export declare function formatToolResult<T>(result: ToolSuccess<T> | ToolError): {
-    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: ToolError | ToolSuccess<T>;
-};
-/**
- * Format an error result for the MCP SDK.
- */
-export declare function formatErrorResult(error: ToolError): {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: ToolError;
-    isError: boolean;
-};

package/dist/tools/_base.js

@@ -1,108 +0,0 @@
-/**
- * Shared error handling and response formatting for all MCP tools.
- *
- * Every error MUST include `next_steps` — actionable guidance for the LLM.
- * This is the #1 pattern from the Polarion MCP that improves agent reliability.
- */
-/** Maximum response size in characters. Truncate with clear message if exceeded. */
-export const CHARACTER_LIMIT = 25_000;
-// ---------------------------------------------------------------------------
-// Success helpers
-// ---------------------------------------------------------------------------
-export function success(data, meta) {
-    return { status: "success", data, ...(meta ? { meta } : {}) };
-}
-export function paginationMeta(totalCount, limit, offset) {
-    return {
-        total_count: totalCount,
-        limit,
-        offset,
-        has_more: offset + limit < totalCount,
-    };
-}
-// ---------------------------------------------------------------------------
-// Error helpers
-// ---------------------------------------------------------------------------
-export function errorResponse(message, nextSteps) {
-    return { status: "error", message, next_steps: nextSteps };
-}
-export function notFoundError(resource, id) {
-    return errorResponse(`${resource} '${id}' not found`, [
-        `Verify the ${resource.toLowerCase()} ID is correct`,
-        `Use atoms_list_items or atoms_search to find valid IDs`,
-    ]);
-}
-export function accessDeniedError(role) {
-    return errorResponse(`${role} role cannot modify project data`, [
-        "Contact your org admin to upgrade your role to editor",
-        "Use read-only tools (atoms_list_items, atoms_get_item, atoms_search) instead",
-    ]);
-}
-export function validationError(message) {
-    return errorResponse(`Validation error: ${message}`, [
-        "Check the parameter types and constraints in the tool description",
-        "Ensure all required parameters are provided",
-    ]);
-}
-export function authError() {
-    return errorResponse("Not authenticated. Run 'npx @atoms-tech/atoms-mcp login' first.", [
-        "Run: npx @atoms-tech/atoms-mcp login",
-        "Or set ATOMS_ACCESS_TOKEN environment variable",
-    ]);
-}
-export function rateLimitError(retryAfterSeconds) {
-    return errorResponse("Rate limit exceeded", [
-        `Wait ${retryAfterSeconds} seconds before making more requests`,
-        "Reduce the frequency of tool calls",
-    ]);
-}
-export function dbError(message) {
-    return errorResponse(`Database error: ${message}`, [
-        "This may be a temporary issue — try again",
-        "If the error persists, check that the project_id is valid",
-    ]);
-}
-// ---------------------------------------------------------------------------
-// Response formatting
-// ---------------------------------------------------------------------------
-/**
- * Format a tool result as JSON string + structuredContent for the MCP SDK.
- * Applies CHARACTER_LIMIT truncation if needed.
- */
-export function formatToolResult(result) {
-    const json = JSON.stringify(result, null, 2);
-    if (json.length > CHARACTER_LIMIT) {
-        // If it's a success with array data, truncate the data
-        if (result.status === "success" && Array.isArray(result.data)) {
-            const halfLength = Math.max(1, Math.floor(result.data.length / 2));
-            const truncated = {
-                ...result,
-                data: result.data.slice(0, halfLength),
-                meta: {
-                    ...result.meta,
-                    truncated: true,
-                    truncation_message: `Response truncated from ${result.data.length} to ${halfLength} items. ` +
-                        `Use 'offset' parameter or add filters to see more results.`,
-                },
-            };
-            return {
-                content: [{ type: "text", text: JSON.stringify(truncated, null, 2) }],
-                structuredContent: truncated,
-            };
-        }
-    }
-    return {
-        content: [{ type: "text", text: json }],
-        structuredContent: result,
-    };
-}
-/**
- * Format an error result for the MCP SDK.
- */
-export function formatErrorResult(error) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(error, null, 2) }],
-        structuredContent: error,
-        isError: true,
-    };
-}

package/dist/tools/bulk-import.d.ts

@@ -1,69 +0,0 @@
-/**
- * atoms_bulk_import — Bulk create multiple items in a single tool call.
- * Essential for AI agents that generate 20+ requirements at once.
- *
- * Checks write access once, generates sequential IDs, batch inserts,
- * and reports per-item errors without aborting the entire batch.
- */
-interface BulkImportItem {
-    type: "requirement" | "test-case" | "note";
-    title: string;
-    body?: string;
-    summary?: string;
-    domains?: string[];
-    level?: string;
-    parent_id?: string;
-}
-interface CreatedItem {
-    id: string;
-    title: string;
-    type: string;
-}
-interface BulkImportError {
-    index: number;
-    title: string;
-    error: string;
-}
-export declare function bulkImportHandler(params: {
-    project_id: string;
-    items: BulkImportItem[];
-}): 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<{
-        created: number;
-        items: never[];
-        errors: BulkImportError[];
-    }>;
-} | {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-    structuredContent: import("../types/responses.js").ToolError | import("../types/responses.js").ToolSuccess<{
-        created: number;
-        items: CreatedItem[];
-        errors: BulkImportError[];
-        project_id: string;
-    }>;
-}>;
-export {};

package/dist/tools/bulk-import.js

@@ -1,187 +0,0 @@
-/**
- * atoms_bulk_import — Bulk create multiple items in a single tool call.
- * Essential for AI agents that generate 20+ requirements at once.
- *
- * Checks write access once, generates sequential IDs, batch inserts,
- * and reports per-item errors without aborting the entire batch.
- */
-import { getClient, getUserId, requireWriteAccess } from "../db/client.js";
-import { generateItemId } from "../db/queries.js";
-import { getMcpSessionId } from "../server.js";
-import { formatToolResult, formatErrorResult, success, accessDeniedError, validationError, dbError, authError, } from "./_base.js";
-export async function bulkImportHandler(params) {
-    try {
-        // Validate item count
-        if (!params.items || params.items.length === 0) {
-            return formatErrorResult(validationError("items array must contain at least 1 item"));
-        }
-        if (params.items.length > 100) {
-            return formatErrorResult(validationError(`Maximum 100 items per call (received ${params.items.length}). Split into multiple calls.`));
-        }
-        const client = await getClient();
-        const userId = getUserId();
-        // Check write access once for the entire batch
-        try {
-            await requireWriteAccess(client, params.project_id);
-        }
-        catch (err) {
-            if (err instanceof Error && err.message === "VIEWER_ROLE") {
-                return formatErrorResult(accessDeniedError("Viewer"));
-            }
-            throw err;
-        }
-        const now = new Date().toISOString();
-        const sessionId = getMcpSessionId();
-        const created = [];
-        const errors = [];
-        // Generate all IDs sequentially (each call increments the counter)
-        const itemsWithIds = [];
-        for (let i = 0; i < params.items.length; i++) {
-            const input = params.items[i];
-            try {
-                const itemId = await generateItemId(client, params.project_id, input.type);
-                itemsWithIds.push({ itemId, input, index: i });
-            }
-            catch (err) {
-                errors.push({
-                    index: i,
-                    title: input.title,
-                    error: `ID generation failed: ${err instanceof Error ? err.message : String(err)}`,
-                });
-            }
-        }
-        if (itemsWithIds.length === 0) {
-            return formatToolResult(success({
-                created: 0,
-                items: [],
-                errors,
-            }));
-        }
-        // Build insert rows and WorkItem data blobs
-        const insertRows = [];
-        const workItemMap = new Map();
-        for (const { itemId, input } of itemsWithIds) {
-            const workItem = {
-                id: itemId,
-                type: input.type,
-                title: input.title,
-                summary: input.summary,
-                body: input.body,
-                tags: {
-                    domains: input.domains ?? [],
-                    level: input.level,
-                },
-                ownership: {
-                    primary: null,
-                    additional: [],
-                },
-                relationships: {
-                    parents: input.parent_id ? [input.parent_id] : [],
-                    children: [],
-                    related: [],
-                },
-                links: [],
-                metadata: {
-                    created_at: now,
-                    created_by: userId,
-                    updated_at: now,
-                    updated_by: userId,
-                },
-            };
-            workItemMap.set(itemId, workItem);
-            insertRows.push({
-                id: itemId,
-                project_id: params.project_id,
-                type: input.type,
-                title: input.title,
-                data: workItem,
-                created_by: userId,
-                updated_by: userId,
-            });
-        }
-        // Batch insert all items
-        const { error: insertErr } = await client
-            .from("items")
-            .insert(insertRows);
-        if (insertErr) {
-            // If batch insert fails, fall back to individual inserts
-            for (const { itemId, input, index } of itemsWithIds) {
-                const row = insertRows.find((r) => r.id === itemId);
-                if (!row)
-                    continue;
-                const { error: singleErr } = await client
-                    .from("items")
-                    .insert(row);
-                if (singleErr) {
-                    errors.push({
-                        index,
-                        title: input.title,
-                        error: singleErr.message,
-                    });
-                }
-                else {
-                    created.push({ id: itemId, title: input.title, type: input.type });
-                }
-            }
-        }
-        else {
-            // Batch succeeded — all items created
-            for (const { itemId, input } of itemsWithIds) {
-                created.push({ id: itemId, title: input.title, type: input.type });
-            }
-        }
-        // Create relationships for items with parent_id (fire-and-forget)
-        const relRows = itemsWithIds
-            .filter(({ input }) => input.parent_id)
-            .filter(({ itemId }) => created.some((c) => c.id === itemId))
-            .map(({ itemId, input }) => ({
-            from_id: itemId,
-            to_id: input.parent_id,
-            type: "parent",
-            project_id: params.project_id,
-        }));
-        if (relRows.length > 0) {
-            await client
-                .from("item_relationships")
-                .insert(relRows)
-                .then(({ error }) => {
-                if (error) {
-                    process.stderr.write(`[atoms-mcp] Warning: bulk relationship sync failed: ${error.message}\n`);
-                }
-            });
-        }
-        // Audit: log one change_history entry per created item (fire-and-forget)
-        const historyRows = created.map((item) => ({
-            item_id: item.id,
-            project_id: params.project_id,
-            changed_by: userId,
-            event_type: "created",
-            old_data: null,
-            new_data: workItemMap.get(item.id) ?? null,
-            actor: "mcp_claude",
-            session_id: sessionId,
-        }));
-        if (historyRows.length > 0) {
-            await client
-                .from("change_history")
-                .insert(historyRows)
-                .then(({ error }) => {
-                if (error) {
-                    process.stderr.write(`[atoms-mcp] Warning: bulk change_history log failed: ${error.message}\n`);
-                }
-            });
-        }
-        return formatToolResult(success({
-            created: created.length,
-            items: created,
-            errors: errors.length > 0 ? errors : [],
-            project_id: params.project_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)));
-    }
-}

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

@@ -1,42 +0,0 @@
-/**
- * atoms_create_item — Create a new requirement, test case, or note.
- * Requires editor or admin role. Logs with AI actor attribution.
- */
-export declare function createItemHandler(params: {
-    project_id: string;
-    type: "requirement" | "test-case" | "note";
-    title: string;
-    body?: string;
-    summary?: string;
-    domains?: string[];
-    level?: string;
-    parent_ids?: 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<{
-        id: string;
-        type: "requirement" | "test-case" | "note";
-        title: string;
-        project_id: string;
-    }>;
-}>;

package/dist/tools/create-item.js

@@ -1,117 +0,0 @@
-/**
- * atoms_create_item — Create a new requirement, test case, or note.
- * Requires editor or admin role. Logs with AI actor attribution.
- */
-import { getClient, getUserId, requireWriteAccess } from "../db/client.js";
-import { generateItemId } from "../db/queries.js";
-import { getMcpSessionId } from "../server.js";
-import { formatToolResult, formatErrorResult, success, accessDeniedError, dbError, authError, } from "./_base.js";
-export async function createItemHandler(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;
-        }
-        // Generate next ID (uses SECURITY DEFINER function to avoid collisions)
-        const itemId = await generateItemId(client, params.project_id, params.type);
-        // Build WorkItem data blob
-        const workItem = {
-            id: itemId,
-            type: params.type,
-            title: params.title,
-            summary: params.summary,
-            body: params.body,
-            tags: {
-                domains: params.domains ?? [],
-                level: params.level,
-            },
-            ownership: {
-                primary: null,
-                additional: [],
-            },
-            relationships: {
-                parents: params.parent_ids ?? [],
-                children: [],
-                related: [],
-            },
-            links: [],
-            metadata: {
-                created_at: new Date().toISOString(),
-                created_by: userId,
-                updated_at: new Date().toISOString(),
-                updated_by: userId,
-            },
-        };
-        // Insert to items table
-        const { error: insertErr } = await client
-            .from("items")
-            .insert({
-            id: itemId,
-            project_id: params.project_id,
-            type: params.type,
-            title: params.title,
-            data: workItem,
-            created_by: userId,
-            updated_by: userId,
-        })
-            .select()
-            .single();
-        if (insertErr)
-            throw new Error(insertErr.message);
-        // Dual-write: sync relationships to shadow table
-        if (params.parent_ids && params.parent_ids.length > 0) {
-            const relRows = params.parent_ids.map((parentId) => ({
-                from_id: itemId,
-                to_id: parentId,
-                type: "parent",
-                project_id: params.project_id,
-            }));
-            await client
-                .from("item_relationships")
-                .insert(relRows)
-                .then(({ error }) => {
-                if (error) {
-                    process.stderr.write(`[atoms-mcp] Warning: relationship sync failed: ${error.message}\n`);
-                }
-            });
-        }
-        // Audit: log to change_history with MCP actor
-        await client
-            .from("change_history")
-            .insert({
-            item_id: itemId,
-            project_id: params.project_id,
-            changed_by: userId,
-            event_type: "created",
-            old_data: null,
-            new_data: workItem,
-            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: itemId,
-            type: params.type,
-            title: params.title,
-            project_id: params.project_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)));
-    }
-}

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

@@ -1,37 +0,0 @@
-/**
- * atoms_delete_item — Soft-delete an item (sets deleted_at, preserves for audit).
- * Requires editor or admin role.
- */
-export declare function deleteItemHandler(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<{
-        id: string;
-        title: string;
-        type: string;
-        deleted: boolean;
-        message: string;
-    }>;
-}>;

package/dist/tools/delete-item.js

@@ -1,68 +0,0 @@
-/**
- * atoms_delete_item — Soft-delete an item (sets deleted_at, preserves for audit).
- * Requires editor or admin role.
- */
-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 deleteItemHandler(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));
-        }
-        // Soft delete (set deleted_at, never remove the row)
-        const { error: deleteErr } = await client
-            .from("items")
-            .update({ deleted_at: new Date().toISOString() })
-            .eq("id", params.item_id)
-            .eq("project_id", params.project_id);
-        if (deleteErr)
-            throw new Error(deleteErr.message);
-        // Audit: log deletion to change_history
-        await client
-            .from("change_history")
-            .insert({
-            item_id: params.item_id,
-            project_id: params.project_id,
-            changed_by: userId,
-            event_type: "deleted",
-            old_data: existing.data,
-            new_data: null,
-            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: existing.title,
-            type: existing.type,
-            deleted: true,
-            message: `Item ${params.item_id} soft-deleted. It can still be found in audit logs.`,
-        }));
-    }
-    catch (err) {
-        if (err instanceof Error && err.message.includes("Not authenticated")) {
-            return formatErrorResult(authError());
-        }
-        return formatErrorResult(dbError(err instanceof Error ? err.message : String(err)));
-    }
-}