@atoms-tech/atoms-mcp 0.3.0 → 0.3.1

package/dist/db/client.js

@@ -1,109 +0,0 @@
-/**
- * Supabase client factory for the MCP server.
- *
- * Creates a user-scoped client with JWT — RLS enforced automatically.
- * Never uses service role key (all queries respect user permissions).
- */
-import { createClient } from "@supabase/supabase-js";
-import { getValidToken } from "../auth/refresh.js";
-import { ATOMS_SUPABASE_URL, ATOMS_SUPABASE_ANON_KEY } from "../config.js";
-let cachedClient = null;
-let cachedUserId = null;
-let cachedEmail = null;
-let tokenExpiresAt = 0;
-/**
- * Get or create an authenticated Supabase client.
- * Auto-refreshes JWT when expired. All queries run with user's RLS permissions.
- */
-export async function getClient() {
-    // If token is within 60s of expiry, force refresh
-    if (cachedClient && tokenExpiresAt > Date.now() + 60_000) {
-        return cachedClient;
-    }
-    // Token expired or no client — get a fresh token
-    if (cachedClient) {
-        process.stderr.write("[atoms-mcp] Token expiring, refreshing client...\n");
-    }
-    const { access_token, user_id, email } = await getValidToken();
-    // Decode expiry from JWT
-    const parts = access_token.split(".");
-    if (parts.length === 3) {
-        try {
-            const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString());
-            tokenExpiresAt = (payload.exp ?? 0) * 1000; // convert to ms
-        }
-        catch {
-            // Fallback: assume 1hr from now
-            tokenExpiresAt = Date.now() + 3600_000;
-        }
-    }
-    // Use global Authorization header — works with all Supabase key formats
-    const client = createClient(ATOMS_SUPABASE_URL, ATOMS_SUPABASE_ANON_KEY, {
-        global: {
-            headers: { Authorization: `Bearer ${access_token}` },
-        },
-    });
-    cachedClient = client;
-    cachedUserId = user_id;
-    cachedEmail = email;
-    return cachedClient;
-}
-/**
- * Get the authenticated user's ID. Must call getClient() first.
- */
-export function getUserId() {
-    if (!cachedUserId) {
-        throw new Error("Not authenticated. Call getClient() first.");
-    }
-    return cachedUserId;
-}
-/**
- * Get the authenticated user's email.
- */
-export function getUserEmail() {
-    return cachedEmail ?? "";
-}
-/**
- * Reset the cached client (for token refresh).
- */
-export function resetClient() {
-    cachedClient = null;
-    cachedUserId = null;
-    cachedEmail = null;
-    tokenExpiresAt = 0;
-}
-/**
- * Check if the user has write access to a project.
- * Returns the user's org role, or throws a descriptive error.
- */
-export async function requireWriteAccess(client, projectId) {
-    const userId = getUserId();
-    // Get the project's org
-    const { data: project, error: projErr } = await client
-        .from("projects")
-        .select("org_id")
-        .eq("id", projectId)
-        .maybeSingle();
-    if (projErr || !project) {
-        throw new Error(`Project '${projectId}' not found`);
-    }
-    // Get user's role in that org
-    const { data: membership, error: memErr } = await client
-        .from("org_members")
-        .select("role")
-        .eq("user_id", userId)
-        .eq("org_id", project.org_id)
-        .maybeSingle();
-    if (memErr || !membership) {
-        // Check if user is a platform admin (can access all orgs)
-        const { data: adminCheck } = await client.rpc("is_platform_admin");
-        if (adminCheck === true) {
-            return "admin";
-        }
-        throw new Error("Not a member of this project's organization");
-    }
-    if (membership.role === "viewer") {
-        throw new Error("VIEWER_ROLE");
-    }
-    return membership.role;
-}

package/dist/db/graph.d.ts

@@ -1,7 +0,0 @@
-export {};
-/**
- * Graph traversal helpers for traceability links.
- * Used by get-coverage and export-mermaid tools.
- *
- * TODO: Implement graph traversal in Phase 2.
- */

package/dist/db/graph.js

@@ -1,7 +0,0 @@
-export {};
-/**
- * Graph traversal helpers for traceability links.
- * Used by get-coverage and export-mermaid tools.
- *
- * TODO: Implement graph traversal in Phase 2.
- */

package/dist/db/queries.d.ts

@@ -1,76 +0,0 @@
-/**
- * Shared Supabase query helpers for MCP tools.
- *
- * All queries use the user's JWT via RLS — no service role key.
- * Query patterns adapted from supabase/functions/.../db.ts.
- */
-import type { SupabaseClient } from "@supabase/supabase-js";
-import type { ItemRow } from "../types/work-item.js";
-/**
- * List projects the authenticated user has access to (via org membership).
- */
-export declare function listProjects(client: SupabaseClient): Promise<Array<{
-    id: string;
-    name: string;
-    description: string | null;
-    org_id: string;
-    org_name: string;
-    created_at: string;
-}>>;
-/**
- * List items in a project with optional filters.
- * Returns rows ordered by created_at, respects soft deletes.
- */
-export declare function listItems(client: SupabaseClient, projectId: string, opts: {
-    type?: string;
-    domain?: string;
-    level?: string;
-    limit: number;
-    offset: number;
-}): Promise<{
-    items: ItemRow[];
-    totalCount: number;
-}>;
-/**
- * Get a single item by ID (excludes soft-deleted).
- */
-export declare function getItemById(client: SupabaseClient, projectId: string, itemId: string): Promise<ItemRow | null>;
-/**
- * Full-text search across items in a project.
- * Uses ilike on title, body, and summary for broad matching.
- */
-export declare function searchItems(client: SupabaseClient, projectId: string, query: string, opts: {
-    type?: string;
-    limit: number;
-}): Promise<{
-    items: ItemRow[];
-    totalCount: number;
-}>;
-/**
- * Get all relationships for an item (both directions).
- */
-export declare function getItemRelationships(client: SupabaseClient, projectId: string, itemId: string): Promise<Array<{
-    from_id: string;
-    to_id: string;
-    type: string;
-}>>;
-/**
- * Get test coverage report: requirements with/without linked test cases.
- */
-export declare function getCoverageReport(client: SupabaseClient, projectId: string, opts: {
-    domain?: string;
-    level?: string;
-}): Promise<{
-    covered: ItemRow[];
-    uncovered: ItemRow[];
-    total: number;
-}>;
-/**
- * Get change history for an item, newest first.
- */
-export declare function getChangeHistory(client: SupabaseClient, projectId: string, itemId: string, limit: number): Promise<Array<Record<string, unknown>>>;
-/**
- * Generate the next item ID for a given type in a project.
- * Format: PREFIX-NNNNN (e.g., REQ-00058)
- */
-export declare function generateItemId(client: SupabaseClient, projectId: string, type: string): Promise<string>;

package/dist/db/queries.js

@@ -1,209 +0,0 @@
-/**
- * Shared Supabase query helpers for MCP tools.
- *
- * All queries use the user's JWT via RLS — no service role key.
- * Query patterns adapted from supabase/functions/.../db.ts.
- */
-// ---------------------------------------------------------------------------
-// Project queries
-// ---------------------------------------------------------------------------
-/**
- * List projects the authenticated user has access to (via org membership).
- */
-export async function listProjects(client) {
-    const { data, error } = await client
-        .from("projects")
-        .select("id, name, description, org_id, created_at, organizations(name)")
-        .is("deleted_at", null)
-        .order("created_at", { ascending: false });
-    if (error)
-        throw new Error(error.message);
-    return (data ?? []).map((p) => ({
-        id: p.id,
-        name: p.name,
-        description: p.description,
-        org_id: p.org_id,
-        org_name: p.organizations?.name ?? "Unknown",
-        created_at: p.created_at,
-    }));
-}
-// ---------------------------------------------------------------------------
-// Item queries
-// ---------------------------------------------------------------------------
-/**
- * List items in a project with optional filters.
- * Returns rows ordered by created_at, respects soft deletes.
- */
-export async function listItems(client, projectId, opts) {
-    let query = client
-        .from("items")
-        .select("*", { count: "exact" })
-        .eq("project_id", projectId)
-        .is("deleted_at", null)
-        .order("created_at", { ascending: true })
-        .range(opts.offset, opts.offset + opts.limit - 1);
-    if (opts.type) {
-        query = query.eq("type", opts.type);
-    }
-    const { data, error, count } = await query;
-    if (error)
-        throw new Error(error.message);
-    // Apply domain/level filters in JS (JSONB nested field filtering)
-    let filtered = (data ?? []);
-    if (opts.domain) {
-        filtered = filtered.filter((item) => {
-            const domains = item.data?.tags?.domains ?? [];
-            return domains.includes(opts.domain);
-        });
-    }
-    if (opts.level) {
-        filtered = filtered.filter((item) => {
-            return item.data?.tags?.level === opts.level;
-        });
-    }
-    return {
-        items: filtered,
-        totalCount: opts.domain || opts.level ? filtered.length : (count ?? 0),
-    };
-}
-/**
- * Get a single item by ID (excludes soft-deleted).
- */
-export async function getItemById(client, projectId, itemId) {
-    const { data, error } = await client
-        .from("items")
-        .select("*")
-        .eq("id", itemId)
-        .eq("project_id", projectId)
-        .is("deleted_at", null)
-        .maybeSingle();
-    if (error)
-        throw new Error(error.message);
-    return data;
-}
-/**
- * Full-text search across items in a project.
- * Uses ilike on title, body, and summary for broad matching.
- */
-export async function searchItems(client, projectId, query, opts) {
-    const searchTerm = query.trim();
-    if (!searchTerm) {
-        return { items: [], totalCount: 0 };
-    }
-    // Use ilike for broad matching across title and JSONB fields
-    let queryBuilder = client
-        .from("items")
-        .select("*", { count: "exact" })
-        .eq("project_id", projectId)
-        .is("deleted_at", null)
-        .or(`title.ilike.%${searchTerm}%,` +
-        `data->>body.ilike.%${searchTerm}%,` +
-        `data->>summary.ilike.%${searchTerm}%`)
-        .limit(opts.limit);
-    if (opts.type) {
-        queryBuilder = queryBuilder.eq("type", opts.type);
-    }
-    const { data, error, count } = await queryBuilder;
-    if (error)
-        throw new Error(error.message);
-    return { items: (data ?? []), totalCount: count ?? 0 };
-}
-// ---------------------------------------------------------------------------
-// Relationship queries
-// ---------------------------------------------------------------------------
-/**
- * Get all relationships for an item (both directions).
- */
-export async function getItemRelationships(client, projectId, itemId) {
-    const { data, error } = await client
-        .from("item_relationships")
-        .select("from_id, to_id, type")
-        .eq("project_id", projectId)
-        .or(`from_id.eq.${itemId},to_id.eq.${itemId}`);
-    if (error)
-        throw new Error(error.message);
-    return data ?? [];
-}
-// ---------------------------------------------------------------------------
-// Coverage queries
-// ---------------------------------------------------------------------------
-/**
- * Get test coverage report: requirements with/without linked test cases.
- */
-export async function getCoverageReport(client, projectId, opts) {
-    // Get all requirements in the project
-    const { data: requirements, error: reqErr } = await client
-        .from("items")
-        .select("*")
-        .eq("project_id", projectId)
-        .eq("type", "requirement")
-        .is("deleted_at", null);
-    if (reqErr)
-        throw new Error(reqErr.message);
-    const allReqs = (requirements ?? []);
-    // Filter by domain/level on the JSONB data
-    const filteredReqs = allReqs.filter((req) => {
-        if (opts.domain) {
-            const domains = req.data?.tags?.domains ?? [];
-            if (!domains.includes(opts.domain))
-                return false;
-        }
-        if (opts.level) {
-            if (req.data?.tags?.level !== opts.level)
-                return false;
-        }
-        return true;
-    });
-    // Get all verified_by relationships for this project
-    const { data: verifiedRels, error: relErr } = await client
-        .from("item_relationships")
-        .select("from_id")
-        .eq("project_id", projectId)
-        .eq("type", "verified_by");
-    if (relErr)
-        throw new Error(relErr.message);
-    const coveredIds = new Set((verifiedRels ?? []).map((r) => r.from_id));
-    const covered = filteredReqs.filter((r) => coveredIds.has(r.id));
-    const uncovered = filteredReqs.filter((r) => !coveredIds.has(r.id));
-    return { covered, uncovered, total: filteredReqs.length };
-}
-// ---------------------------------------------------------------------------
-// History queries
-// ---------------------------------------------------------------------------
-/**
- * Get change history for an item, newest first.
- */
-export async function getChangeHistory(client, projectId, itemId, limit) {
-    const { data, error } = await client
-        .from("change_history")
-        .select("*")
-        .eq("item_id", itemId)
-        .eq("project_id", projectId)
-        .order("changed_at", { ascending: false })
-        .limit(limit);
-    if (error)
-        throw new Error(error.message);
-    return data ?? [];
-}
-// ---------------------------------------------------------------------------
-// Item mutations (for write tools — Phase 3)
-// ---------------------------------------------------------------------------
-/**
- * Generate the next item ID for a given type in a project.
- * Format: PREFIX-NNNNN (e.g., REQ-00058)
- */
-export async function generateItemId(client, projectId, type) {
-    const prefix = type === "requirement" ? "REQ"
-        : type === "test-case" ? "TC"
-            : type === "note" ? "NOTE"
-                : "TABLE";
-    // Use Postgres SECURITY DEFINER function that sees ALL items (including soft-deleted)
-    // to avoid ID collisions. Only returns the next ID string, never exposes item data.
-    const { data, error } = await client.rpc("next_item_id", {
-        p_project_id: projectId,
-        p_prefix: prefix,
-    });
-    if (error)
-        throw new Error(`ID generation failed: ${error.message}`);
-    return data;
-}

package/dist/index.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-/**
- * ATOMS MCP Server — CLI Entry Point
- *
- * Commands:
- *   npx @atoms-tech/atoms-mcp           → Start MCP server (stdio transport)
- *   npx @atoms-tech/atoms-mcp login     → Authenticate with ATOMS.tech
- *   npx @atoms-tech/atoms-mcp whoami    → Show current user
- *   npx @atoms-tech/atoms-mcp --version → Show version
- */
-export {};

package/dist/middleware/audit.d.ts

@@ -1,25 +0,0 @@
-/**
- * Fire-and-forget MCP audit logging.
- *
- * Every tool call is logged to mcp_audit_log for enterprise compliance.
- * Logging NEVER blocks or delays the tool response.
- */
-import type { SupabaseClient } from "@supabase/supabase-js";
-export interface AuditEntry {
-    tool_name: string;
-    params: Record<string, unknown>;
-    status: "success" | "error";
-    duration_ms: number;
-    error_msg?: string;
-    project_id?: string;
-    session_id?: string;
-    client_name?: string;
-}
-/**
- * Log a tool call to mcp_audit_log. Fire-and-forget — errors are swallowed.
- */
-export declare function logAudit(client: SupabaseClient, userId: string, entry: AuditEntry): void;
-/**
- * Timer utility for measuring tool duration.
- */
-export declare function startTimer(): () => number;

package/dist/middleware/audit.js

@@ -1,43 +0,0 @@
-/**
- * Fire-and-forget MCP audit logging.
- *
- * Every tool call is logged to mcp_audit_log for enterprise compliance.
- * Logging NEVER blocks or delays the tool response.
- */
-/**
- * Log a tool call to mcp_audit_log. Fire-and-forget — errors are swallowed.
- */
-export function logAudit(client, userId, entry) {
-    // Sanitize params — strip any secrets
-    const sanitizedParams = { ...entry.params };
-    delete sanitizedParams.access_token;
-    delete sanitizedParams.refresh_token;
-    delete sanitizedParams.password;
-    // Fire and forget — don't await
-    client
-        .from("mcp_audit_log")
-        .insert({
-        user_id: userId,
-        tool_name: entry.tool_name,
-        params: sanitizedParams,
-        status: entry.status,
-        duration_ms: entry.duration_ms,
-        error_msg: entry.error_msg ?? null,
-        project_id: entry.project_id ?? null,
-        session_id: entry.session_id ?? null,
-        client_name: entry.client_name ?? null,
-    })
-        .then(({ error }) => {
-        if (error) {
-            // Log to stderr, never throw
-            process.stderr.write(`[audit] Failed to log: ${error.message}\n`);
-        }
-    });
-}
-/**
- * Timer utility for measuring tool duration.
- */
-export function startTimer() {
-    const start = performance.now();
-    return () => Math.round(performance.now() - start);
-}

package/dist/middleware/rate-limiter.d.ts

@@ -1,20 +0,0 @@
-/**
- * In-memory per-user rate limiting for MCP tool calls.
- *
- * Default: 60 requests/minute. Configurable via ATOMS_RATE_LIMIT_RPM env var.
- * Uses sliding window algorithm.
- */
-/**
- * Check if a user has exceeded their rate limit.
- * Returns { allowed: true } or { allowed: false, retryAfterSeconds }.
- */
-export declare function checkRateLimit(userId: string): {
-    allowed: true;
-} | {
-    allowed: false;
-    retryAfterSeconds: number;
-};
-/**
- * Clear rate limit state. Useful for testing.
- */
-export declare function clearRateLimits(): void;

package/dist/middleware/rate-limiter.js

@@ -1,42 +0,0 @@
-/**
- * In-memory per-user rate limiting for MCP tool calls.
- *
- * Default: 60 requests/minute. Configurable via ATOMS_RATE_LIMIT_RPM env var.
- * Uses sliding window algorithm.
- */
-const DEFAULT_RPM = 60;
-const WINDOW_MS = 60_000; // 1 minute
-const windows = new Map();
-/**
- * Check if a user has exceeded their rate limit.
- * Returns { allowed: true } or { allowed: false, retryAfterSeconds }.
- */
-export function checkRateLimit(userId) {
-    const rpm = parseInt(process.env.ATOMS_RATE_LIMIT_RPM ?? "", 10) || DEFAULT_RPM;
-    const now = Date.now();
-    const cutoff = now - WINDOW_MS;
-    let window = windows.get(userId);
-    if (!window) {
-        window = { timestamps: [] };
-        windows.set(userId, window);
-    }
-    // Prune old timestamps
-    window.timestamps = window.timestamps.filter((t) => t > cutoff);
-    if (window.timestamps.length >= rpm) {
-        // Calculate when the oldest request in the window expires
-        const oldestInWindow = window.timestamps[0];
-        const retryAfterMs = oldestInWindow + WINDOW_MS - now;
-        return {
-            allowed: false,
-            retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
-        };
-    }
-    window.timestamps.push(now);
-    return { allowed: true };
-}
-/**
- * Clear rate limit state. Useful for testing.
- */
-export function clearRateLimits() {
-    windows.clear();
-}

package/dist/middleware/validator.d.ts

@@ -1,21 +0,0 @@
-/**
- * Input validation for MCP tool parameters.
- *
- * All LLM-generated inputs are untrusted. Validate everything.
- * Pattern ported from Polarion MCP middleware/input_validator.py.
- */
-export declare function validateProjectId(id: string): string;
-export declare function validateItemId(id: string): string;
-export declare function validateQuery(query: string): string;
-export declare function validateLimit(limit: number, max: number): number;
-export declare function validateOffset(offset: number): number;
-export declare function validateTitle(title: string): string;
-export declare function validateItemType(type: string): string;
-export declare function validateRelationshipType(type: string): string;
-export declare function sanitizeText(text: string): string;
-/**
- * Custom validation error with a clean message for LLM consumption.
- */
-export declare class ValidationError extends Error {
-    constructor(message: string);
-}

package/dist/middleware/validator.js

@@ -1,90 +0,0 @@
-/**
- * Input validation for MCP tool parameters.
- *
- * All LLM-generated inputs are untrusted. Validate everything.
- * Pattern ported from Polarion MCP middleware/input_validator.py.
- */
-const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const ITEM_ID_REGEX = /^[A-Z]+-\d{5}$/;
-const SAFE_TEXT_REGEX = /^[^<>&;'"\\]+$/;
-export function validateProjectId(id) {
-    if (!id || typeof id !== "string") {
-        throw new ValidationError("project_id is required");
-    }
-    if (!UUID_REGEX.test(id)) {
-        throw new ValidationError("project_id must be a valid UUID");
-    }
-    return id;
-}
-export function validateItemId(id) {
-    if (!id || typeof id !== "string") {
-        throw new ValidationError("item_id is required");
-    }
-    if (id.length > 20) {
-        throw new ValidationError("item_id exceeds maximum length");
-    }
-    if (!ITEM_ID_REGEX.test(id)) {
-        throw new ValidationError("item_id must match format: PREFIX-NNNNN (e.g., REQ-00001, TC-00050)");
-    }
-    return id;
-}
-export function validateQuery(query) {
-    if (!query || typeof query !== "string") {
-        throw new ValidationError("query is required");
-    }
-    if (query.length > 1000) {
-        throw new ValidationError("query exceeds maximum length of 1000 characters");
-    }
-    return query.trim();
-}
-export function validateLimit(limit, max) {
-    if (typeof limit !== "number" || !Number.isInteger(limit)) {
-        throw new ValidationError("limit must be an integer");
-    }
-    return Math.max(1, Math.min(limit, max));
-}
-export function validateOffset(offset) {
-    if (typeof offset !== "number" || !Number.isInteger(offset)) {
-        throw new ValidationError("offset must be an integer");
-    }
-    return Math.max(0, offset);
-}
-export function validateTitle(title) {
-    if (!title || typeof title !== "string") {
-        throw new ValidationError("title is required");
-    }
-    if (title.length > 500) {
-        throw new ValidationError("title exceeds maximum length of 500 characters");
-    }
-    return title.trim();
-}
-export function validateItemType(type) {
-    const validTypes = ["requirement", "test-case", "note", "table"];
-    if (!validTypes.includes(type)) {
-        throw new ValidationError(`type must be one of: ${validTypes.join(", ")}. Got: '${type}'`);
-    }
-    return type;
-}
-export function validateRelationshipType(type) {
-    const validTypes = ["parent", "child", "related", "verifies", "verified_by"];
-    if (!validTypes.includes(type)) {
-        throw new ValidationError(`relationship type must be one of: ${validTypes.join(", ")}. Got: '${type}'`);
-    }
-    return type;
-}
-export function sanitizeText(text) {
-    // Strip potential XSS/injection characters from free-text fields
-    return text
-        .replace(/[<>&]/g, "")
-        .replace(/\\/g, "")
-        .trim();
-}
-/**
- * Custom validation error with a clean message for LLM consumption.
- */
-export class ValidationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "ValidationError";
-    }
-}

package/dist/server.d.ts

@@ -1,14 +0,0 @@
-/**
- * ATOMS MCP Server — Tool registration and initialization.
- *
- * Registers 15 tools: 10 via server.registerTool(), 5 as MCP Apps via registerAtomsApp().
- * MCP App tools (mermaid, summary, trace) render interactive UIs in capable hosts
- * while falling back to text for non-UI clients.
- *
- * Naming: atoms_{action}_{resource} (snake_case with service prefix)
- * Server name: atoms-mcp-server (follows {service}-mcp-server convention)
- */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const server: McpServer;
-/** Expose session ID for change_history writes */
-export declare function getMcpSessionId(): string;