@atomixstudio/mcp 0.1.0

package/data/tenants/default.json

@@ -0,0 +1,73 @@
+{
+  "tenantId": "default",
+  "createdAt": "2025-12-13T12:00:00.000Z",
+  "updatedAt": "2025-12-16T12:00:00.000Z",
+  
+  "governance": {
+    "semanticOnlyConsumption": true,
+    "blockPrimitiveTokens": true,
+    "blockHardcodedValues": true,
+    "requireFoundationsFirst": true,
+    
+    "violationResponse": {
+      "action": "block_and_suggest",
+      "options": [
+        "Add token to Foundations first, then consume it",
+        "Use an existing semantic token from the available options",
+        "Defer this feature until a proper semantic token exists"
+      ]
+    },
+    
+    "allowedTokenCategories": [
+      "SEMANTIC_TEXT_COLOR_OPTIONS",
+      "SEMANTIC_BACKGROUND_COLOR_OPTIONS", 
+      "SEMANTIC_ACTION_COLOR_OPTIONS",
+      "SEMANTIC_BORDER_COLOR_OPTIONS",
+      "SEMANTIC_ON_COLOR_OPTIONS"
+    ],
+    
+    "forbiddenPatterns": [
+      "static-*",
+      "scales.*",
+      "#[0-9A-Fa-f]{3,8}",
+      "rgb\\(",
+      "rgba\\(",
+      "hsl\\(",
+      "\\d+px",
+      "\\d+rem"
+    ]
+  },
+  
+  "componentDefaults": {
+    "button": {
+      "variants": {
+        "inverse": {
+          "_status": "blocked",
+          "_reason": "Uses primitive token 'static-black'. Requires 'action-inverse' in Foundations.",
+          "_suggestedAction": "Add 'action-inverse' to Foundations, then update bgColor to 'action-inverse'",
+          "bgColor": "action-inverse",
+          "textColor": "text-brand",
+          "interaction": "subtle"
+        }
+      }
+    }
+  },
+  
+  "lockedTokens": [
+    "button.variants.primary.bgColor",
+    "card.variants.*.shadow"
+  ],
+  
+  "tokenOverrides": {},
+  
+  "pendingFoundationRequests": [
+    {
+      "tokenId": "action-inverse",
+      "category": "colors.modes.*.actionInverse",
+      "requestedBy": "AI variant creation",
+      "requestedFor": "button.variants.inverse.bgColor",
+      "suggestedValue": "scales.neutral[100] (black)",
+      "status": "pending_human_approval"
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * User Tokens Fetcher
+ * -------------------
+ * Fetches user-specific design system tokens from Atomix API.
+ *
+ * Used when MCP server is run with --ds-id flag to serve a user's
+ * custom design system instead of Atomix's internal tokens.
+ */
+interface UserDesignSystem {
+    id: string;
+    name: string;
+    tokens: Record<string, unknown>;
+    governance?: {
+        rules: string[];
+        categories?: Record<string, string[]>;
+    };
+}
+interface FetchUserDSOptions {
+    /** User's design system ID */
+    dsId: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Base URL for the Atomix API (default: https://atomix.design) */
+    baseUrl?: string;
+}
+interface UserDSMeta {
+    id: string;
+    name: string;
+    publishedAt?: number;
+    updatedAt?: number;
+    version?: number;
+}
+interface UserDSResponse {
+    success: boolean;
+    tokens?: Record<string, unknown>;
+    governance?: UserDesignSystem['governance'];
+    meta?: UserDSMeta;
+    error?: string;
+}
+/**
+ * Fetch user's design system tokens from Atomix API
+ *
+ * @param options - Fetch options including dsId and apiKey
+ * @returns User's tokens and governance rules
+ *
+ * @example
+ * ```ts
+ * const { tokens, governance } = await fetchUserDesignSystem({
+ *   dsId: 'abc123',
+ *   apiKey: 'user-api-key'
+ * });
+ * ```
+ */
+declare function fetchUserDesignSystem(options: FetchUserDSOptions): Promise<UserDSResponse>;
+interface CLIArgs {
+    /** User's design system ID */
+    dsId?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Tenant ID (legacy, mapped to dsId) */
+    tenant?: string;
+    /** Base URL for the Atomix API */
+    baseUrl?: string;
+}
+/**
+ * Parse command line arguments for user DS mode
+ *
+ * Supported args:
+ * - --ds-id <id>: User's design system ID
+ * - --api-key <key>: API key for authentication
+ * - --tenant <id>: Legacy tenant ID (mapped to dsId)
+ * - --base-url <url>: Custom API base URL
+ *
+ * @param argv - Command line arguments (default: process.argv)
+ * @returns Parsed CLI arguments
+ */
+declare function parseCLIArgs(argv?: string[]): CLIArgs;
+/**
+ * Check if CLI args indicate user DS mode
+ */
+declare function isUserDSMode(args: CLIArgs): boolean;
+/**
+ * Transform user DS tokens to match the structure expected by MCP server.
+ *
+ * User DS tokens come in the StoredDesignSystem format from InstantDB.
+ * This transforms them to the flat primitives structure used by MCP tools.
+ *
+ * @param userTokens - User's tokens from InstantDB
+ * @returns Tokens in MCP-compatible format
+ */
+declare function transformUserTokens(userTokens: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * AI Rules Generator
+ *
+ * Generates project-specific rules and MCP configurations for AI coding tools
+ * using the Atomix design system.
+ *
+ * SUPPORTED MCP CLIENTS (from modelcontextprotocol.io/clients):
+ *
+ * IDE/Editors:
+ * - Cursor (.cursorrules)
+ * - VS Code + GitHub Copilot (.github/copilot-instructions.md)
+ * - Windsurf (.windsurfrules)
+ * - Zed (MCP native)
+ * - Continue (.continuerules)
+ * - Cline (.clinerules)
+ * - CodeGPT (MCP native)
+ * - Amazon Q IDE (MCP native)
+ * - Augment Code (MCP native)
+ * - VT Code (MCP native)
+ *
+ * Desktop Apps:
+ * - Claude Desktop (MCP native)
+ * - BoltAI (MCP native)
+ * - Chatbox (MCP native)
+ * - ChatGPT (MCP native)
+ *
+ * CLI/Terminal:
+ * - Warp (.warp/workflows or MCP)
+ * - Amazon Q CLI (MCP native)
+ * - goose (MCP native)
+ *
+ * Frameworks/Libraries:
+ * - Genkit (MCP native)
+ * - LangChain (MCP native)
+ * - fast-agent (MCP native)
+ */
+type AIToolId = "cursor" | "copilot" | "windsurf" | "cline" | "continue" | "zed" | "claude-desktop" | "generic";
+interface AIToolConfig {
+    id: AIToolId;
+    name: string;
+    rulesFilename: string;
+    rulesPath: string;
+    mcpConfigPath?: string;
+    supportsMarkdown: boolean;
+    supportsMCP: boolean;
+    description: string;
+}
+/**
+ * Registry of supported AI coding tools and their rules file conventions
+ */
+declare const AI_TOOLS: Record<AIToolId, AIToolConfig>;
+type MCPConfigToolId = "cursor" | "claude-desktop" | "windsurf" | "continue" | "vscode";
+interface MCPConfigOptions {
+    /** Path to the MCP server (default: npx @atomixstudio/mcp) */
+    serverPath?: string;
+    /** Use npx to run the server */
+    useNpx?: boolean;
+    /** Design system ID for per-user MCP mode */
+    dsId?: string;
+    /** API key for authentication (required for per-user mode) */
+    apiKey?: string;
+    /** @deprecated Use dsId instead. Tenant ID for backwards compatibility */
+    tenantId?: string;
+    /** Project name for identification */
+    projectName?: string;
+}
+interface MCPConfig {
+    tool: MCPConfigToolId;
+    filename: string;
+    path: string;
+    content: string;
+    instructions: string;
+}
+/**
+ * Generate MCP configuration file for a specific AI tool
+ */
+declare function generateMCPConfig(tool: MCPConfigToolId, options?: MCPConfigOptions): MCPConfig;
+/**
+ * Generate MCP configs for all supported tools
+ */
+declare function generateAllMCPConfigs(options?: MCPConfigOptions): MCPConfig[];
+/**
+ * Get detailed setup instructions for a specific AI tool
+ */
+declare function getSetupInstructions(toolId: AIToolId): string;
+declare function generateCursorRules(projectName: string, strict: boolean): string;
+interface GeneratedRulesFile {
+    tool: AIToolConfig;
+    filename: string;
+    path: string;
+    content: string;
+}
+/**
+ * Generate rules for a specific AI tool
+ */
+declare function generateRulesForTool(toolId: AIToolId, projectName: string, strict: boolean): GeneratedRulesFile;
+/**
+ * Generate rules for ALL supported AI tools at once
+ */
+declare function generateRulesForAllTools(projectName: string, strict: boolean): GeneratedRulesFile[];
+/**
+ * Get list of all supported AI tools
+ */
+declare function getSupportedAITools(): AIToolConfig[];
+/**
+ * Generate a summary of which files to create for full AI tool support
+ */
+declare function generateToolSetupGuide(projectName: string): string;
+
+export { type AIToolId, AI_TOOLS, type MCPConfigToolId, fetchUserDesignSystem, generateAllMCPConfigs, generateCursorRules, generateMCPConfig, generateRulesForAllTools, generateRulesForTool, generateToolSetupGuide, getSetupInstructions, getSupportedAITools, isUserDSMode, parseCLIArgs, transformUserTokens };