@atoms-tech/atoms-mcp 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2024-2026 Atoms.tech. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this software, via any medium, is strictly prohibited.
+
+This software is provided to end users solely for use with the Atoms.tech platform
+under the terms of the Atoms.tech Terms of Service.
+
+For licensing inquiries, contact: support@atoms.tech

package/README.md

@@ -32,23 +32,35 @@ Every action is logged with AI actor attribution (`mcp_claude`) and enforces you
 
 ## Available Tools
 
-| Tool | Description | Access |
-|------|-------------|--------|
-| `atoms_list_projects` | List all accessible projects | Read |
-| `atoms_list_items` | Browse items with type/domain/level filters | Read |
-| `atoms_get_item` | Get full item details with relationships | Read |
-| `atoms_search` | Full-text search across items | Read |
-| `atoms_get_coverage` | Find requirements without test cases | Read |
-| `atoms_get_history` | Audit trail for an item | Read |
-| `atoms_export_mermaid` | Generate traceability diagram | Read |
-| `atoms_create_item` | Create a requirement, test case, or note | Write |
-| `atoms_update_item` | Update item fields | Write |
-| `atoms_delete_item` | Soft-delete an item | Write |
-| `atoms_link_items` | Add/remove relationships between items | Write |
-| `atoms_bulk_import` | Bulk create up to 100 items at once | Write |
-| `atoms_record_test_result` | Record pass/fail for a test case | Write |
-| `atoms_trace` | Walk traceability graph (upstream/downstream) | Read |
-| `atoms_project_summary` | Project compliance dashboard (counts, coverage, status) | Read |
+| Tool | Description | Access | MCP App UI |
+|------|-------------|--------|------------|
+| `atoms_list_projects` | List all accessible projects | Read | |
+| `atoms_list_items` | Browse items with type/domain/level filters | Read | |
+| `atoms_get_item` | Get full item details with relationships | Read | |
+| `atoms_search` | Full-text search across items | Read | |
+| `atoms_get_coverage` | Find requirements without test cases | Read | Coverage heatmap |
+| `atoms_get_history` | Audit trail for an item | Read | |
+| `atoms_export_mermaid` | Generate traceability diagram | Read | Interactive diagram |
+| `atoms_create_item` | Create a requirement, test case, or note | Write | |
+| `atoms_update_item` | Update item fields | Write | |
+| `atoms_delete_item` | Soft-delete an item | Write | |
+| `atoms_link_items` | Add/remove relationships between items | Write | |
+| `atoms_bulk_import` | Bulk create up to 100 items at once | Write | Results table |
+| `atoms_record_test_result` | Record pass/fail for a test case | Write | |
+| `atoms_trace` | Walk traceability graph (upstream/downstream) | Read | Force-directed graph |
+| `atoms_project_summary` | Project compliance dashboard | Read | Charts + gauges |
+
+## Interactive UIs (MCP Apps)
+
+5 tools include interactive UIs powered by [MCP Apps](https://modelcontextprotocol.io/extensions/apps). In supported hosts (Claude, ChatGPT), these tools render rich visualizations inline in the conversation:
+
+- **Project Summary** — compliance dashboard with coverage gauge, test status bar, and domain charts
+- **Trace Graph** — interactive force-directed graph showing requirement/test traceability
+- **Mermaid Diagram** — pan/zoom diagram of the requirement hierarchy
+- **Coverage Heatmap** — visual coverage report with uncovered requirements list
+- **Bulk Import Results** — color-coded table showing created items and errors
+
+In non-UI clients (Claude Code CLI, Cursor), these tools return standard JSON text — no functionality is lost.
 
 ## Authentication
 
@@ -69,7 +81,7 @@ npx @atoms-tech/atoms-mcp logout
 
 1. `login` opens your browser to the ATOMS consent page
 2. You approve the MCP connection with your ATOMS account
-3. Tokens are stored locally at `~/.atoms-mcp/credentials.json`
+3. Tokens are stored locally at `~/.atoms/credentials.json`
 4. Tokens auto-refresh — you only need to login once
 
 You can also set `ATOMS_ACCESS_TOKEN` as an environment variable for CI/headless use.

package/dist/apps/register.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP App registration helper.
+ * Wraps registerAppTool + registerAppResource with ATOMS conventions.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+interface RegisterAppConfig {
+    /** App directory name (e.g., "mermaid") */
+    appName: string;
+    /** HTML filename (e.g., "mermaid-app.html") */
+    htmlFile: string;
+    /** Tool name (e.g., "atoms_export_mermaid") */
+    toolName: string;
+    /** Tool display title */
+    title: string;
+    /** Tool description */
+    description: string;
+    /** Zod input schema */
+    inputSchema: ZodRawShapeCompat;
+    /** Tool annotations */
+    annotations?: ToolAnnotations;
+    /** Additional CSP resource domains (e.g., CDN for mermaid.js) */
+    extraResourceDomains?: string[];
+    /** Tool handler — receives validated params, returns MCP tool result */
+    handler: (...args: any[]) => any;
+}
+/**
+ * Register a tool as an MCP App with UI resource.
+ * - Creates ui:// resource URI
+ * - Registers tool with _meta.ui pointing to the resource
+ * - Registers resource that serves the single-file bundled HTML
+ * - Configures CSP for Google Fonts + any extras
+ */
+export declare function registerAtomsApp(server: McpServer, config: RegisterAppConfig): void;
+export {};

package/dist/apps/register.js

@@ -0,0 +1,65 @@
+/**
+ * MCP App registration helper.
+ * Wraps registerAppTool + registerAppResource with ATOMS conventions.
+ */
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve path to a built MCP App HTML file.
+ * Build output: dist/apps/src/apps/{name}/{name}-app.html
+ * Runtime __dirname: dist/apps/ (since this file is src/apps/register.ts → dist/apps/register.js)
+ */
+function resolveAppHtml(appName, htmlFile) {
+    return path.resolve(__dirname, "src", "apps", appName, htmlFile);
+}
+/** CSP domains needed by all ATOMS apps (Google Fonts) */
+const SHARED_CSP = {
+    resourceDomains: [
+        "fonts.googleapis.com",
+        "fonts.gstatic.com",
+    ],
+};
+/**
+ * Register a tool as an MCP App with UI resource.
+ * - Creates ui:// resource URI
+ * - Registers tool with _meta.ui pointing to the resource
+ * - Registers resource that serves the single-file bundled HTML
+ * - Configures CSP for Google Fonts + any extras
+ */
+export function registerAtomsApp(server, config) {
+    const resourceUri = `ui://${config.toolName}/${config.htmlFile}`;
+    const htmlPath = resolveAppHtml(config.appName, config.htmlFile);
+    const resourceDomains = [
+        ...SHARED_CSP.resourceDomains,
+        ...(config.extraResourceDomains ?? []),
+    ];
+    // Register the tool with UI metadata
+    registerAppTool(server, config.toolName, {
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        annotations: config.annotations,
+        _meta: { ui: { resourceUri } },
+    }, config.handler);
+    // Register the HTML resource
+    registerAppResource(server, `${config.title} UI`, resourceUri, {
+        mimeType: RESOURCE_MIME_TYPE,
+    }, async () => {
+        const html = await fs.readFile(htmlPath, "utf-8");
+        return {
+            contents: [{
+                    uri: resourceUri,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                    _meta: {
+                        ui: {
+                            csp: { resourceDomains },
+                        },
+                    },
+                }],
+        };
+    });
+}