@atlashub/smartstack-mcp 1.2.0 → 1.2.1

package/README.md

@@ -1,198 +1,154 @@
-# @smartstack/mcp-server
+# @atlashub/smartstack-mcp
 
 MCP (Model Context Protocol) server for SmartStack/AtlasHub platform development.
 
-## Features
+## Installation
 
-### Tools
+### Option 1: Claude Code CLI (Recommended)
 
-| Tool | Description |
-|------|-------------|
-| `validate_conventions` | Validate AtlasHub conventions (SQL schemas, domain table prefixes, migration naming, service interfaces) |
-| `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
-| `scaffold_extension` | Generate code for services, entities, controllers, or React components |
-| `api_docs` | Get API endpoint documentation from Swagger or code analysis |
+```bash
+# Add SmartStack MCP (user-level, available in all projects)
+claude mcp add smartstack -s user -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- npx -y @atlashub/smartstack-mcp
 
-### Resources
+# Or project-level (only for current project)
+claude mcp add smartstack -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- npx -y @atlashub/smartstack-mcp
 
-| Resource URI | Description |
-|--------------|-------------|
-| `smartstack://conventions` | AtlasHub naming conventions and best practices |
-| `smartstack://project` | Current project information and structure |
-| `smartstack://api/{endpoint}` | API endpoint documentation |
-| `smartstack://schema/{table}` | Database schema information |
-
-## Installation
+# With global install (faster startup)
+npm install -g @atlashub/smartstack-mcp
+claude mcp add smartstack -s user -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- smartstack-mcp
+```
 
+**Verify installation:**
 ```bash
-# Clone and install dependencies
-cd "D:\01 - projets\SmartStack.mcp\02-Develop"
-npm install
-
-# Build
-npm run build
+claude mcp list
 ```
 
-## Configuration
-
-### Environment Variables
+### Option 2: Visual Studio Code (Extension Claude Code)
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SMARTSTACK_PROJECT_PATH` | Path to SmartStack.app project | `D:/SmartStack.app/features/Rework-to-package` |
-| `SMARTSTACK_API_URL` | SmartStack API URL | `https://localhost:7055` |
-| `SMARTSTACK_API_ENABLED` | Enable API integration | `true` |
-| `LOG_LEVEL` | Logging level (debug, info, warn, error) | `info` |
-
-### Claude Desktop Configuration
-
-Add to your Claude Desktop config file (`claude_desktop_config.json`):
+Create a `.mcp.json` file at the root of your project:
 
 ```json
 {
   "mcpServers": {
     "smartstack": {
-      "command": "node",
-      "args": ["D:/01 - projets/SmartStack.mcp/02-Develop/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@atlashub/smartstack-mcp"],
       "env": {
-        "SMARTSTACK_PROJECT_PATH": "D:/SmartStack.app/features/Rework-to-package",
-        "SMARTSTACK_API_URL": "https://localhost:7055"
+        "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
       }
     }
   }
 }
 ```
 
-### Claude Code Configuration
-
-Add to your `.claude/settings.json`:
+Or with global install (faster startup):
 
 ```json
 {
   "mcpServers": {
     "smartstack": {
-      "command": "node",
-      "args": ["D:/01 - projets/SmartStack.mcp/02-Develop/dist/index.js"],
+      "command": "smartstack-mcp",
       "env": {
-        "SMARTSTACK_PROJECT_PATH": "D:/SmartStack.app/features/Rework-to-package"
+        "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
       }
     }
   }
 }
 ```
 
-## Usage Examples
+**Steps:**
+1. Install the Claude Code extension in VS Code
+2. Create the `.mcp.json` file at project root
+3. Reload VS Code or the extension
+4. The MCP server will be available in Claude Code panel
 
-### Validate Conventions
+### Option 3: Claude Desktop
 
-```
-Use validate_conventions tool with checks: ["tables", "migrations", "services"]
-```
+Add to `claude_desktop_config.json`:
 
-### Check Migrations
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-```
-Use check_migrations tool with compareBranch: "develop"
+```json
+{
+  "mcpServers": {
+    "smartstack": {
+      "command": "npx",
+      "args": ["-y", "@atlashub/smartstack-mcp"],
+      "env": {
+        "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
+      }
+    }
+  }
+}
 ```
 
-### Scaffold a Service
+### Option 4: Manual Execution
 
-```
-Use scaffold_extension tool with:
-- type: "service"
-- name: "UserProfile"
-- options: { methods: ["GetByIdAsync", "UpdateAsync"] }
+```bash
+# Using npx (no install required)
+SMARTSTACK_PROJECT_PATH=/path/to/project npx @atlashub/smartstack-mcp
+
+# Or if installed globally
+npm install -g @atlashub/smartstack-mcp
+SMARTSTACK_PROJECT_PATH=/path/to/project smartstack-mcp
 ```
 
-### Get API Documentation
+## Adding Context7 (Optional)
 
-```
-Use api_docs tool with:
-- endpoint: "/api/users"
-- format: "markdown"
+Context7 provides up-to-date documentation lookups for any library.
+
+**Claude Code CLI:**
+```bash
+claude mcp add context7 -s user -- npx -y @upstash/context7-mcp
 ```
 
-## Development
+**VS Code (.mcp.json):**
+```json
+{
+  "mcpServers": {
+    "smartstack": {
+      "command": "npx",
+      "args": ["-y", "@atlashub/smartstack-mcp"],
+      "env": {
+        "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
+      }
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
 
-```bash
-# Watch mode
-npm run dev
+## Configuration
 
-# Test with MCP Inspector
-npm run inspect
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `SMARTSTACK_PROJECT_PATH` | Path to your SmartStack.app project | Yes |
+| `SMARTSTACK_API_URL` | SmartStack API URL | No |
+| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No |
 
-# Type check
-npm run typecheck
+## Features
 
-# Lint
-npm run lint
-```
+### Tools
 
-## Project Structure
+| Tool | Description |
+|------|-------------|
+| `validate_conventions` | Validate AtlasHub conventions |
+| `check_migrations` | Analyze EF Core migrations |
+| `scaffold_extension` | Generate code scaffolding |
+| `api_docs` | Get API documentation |
 
-```
-src/
-├── index.ts           # Entry point
-├── server.ts          # MCP server configuration
-├── config.ts          # Configuration management
-├── tools/             # MCP tool implementations
-│   ├── validate-conventions.ts
-│   ├── check-migrations.ts
-│   ├── scaffold-extension.ts
-│   └── api-docs.ts
-├── resources/         # MCP resource implementations
-│   ├── conventions.ts
-│   ├── project-info.ts
-│   ├── api-endpoints.ts
-│   └── db-schema.ts
-├── lib/               # Shared libraries
-│   ├── detector.ts    # Project detection
-│   └── logger.ts      # Logging utilities
-├── types/             # TypeScript types
-│   └── index.ts
-└── utils/             # Utility functions
-    ├── fs.ts          # File system operations
-    ├── git.ts         # Git commands
-    └── dotnet.ts      # .NET CLI commands
-```
+### Resources
 
-## AtlasHub Conventions
-
-This MCP server enforces the following conventions:
-
-### SQL Schemas
-- **`core`**: SmartStack platform tables
-- **`extensions`**: Client extension tables
-
-### Table Prefixes (by domain)
-Tables use domain-specific prefixes within schemas:
-- `auth_*` - Authorization (Users, Roles, Permissions)
-- `nav_*` - Navigation (Contexts, Applications, Modules)
-- `usr_*` - User profiles (Profiles, Preferences)
-- `ai_*` - AI features (Providers, Models, Prompts)
-- `cfg_*` - Configuration (Settings)
-- `wkf_*` - Workflows (EmailTemplates, Workflows)
-- `support_*` - Support (Tickets, Comments)
-- `entra_*` - Entra sync (Groups, SyncState)
-- `ref_*` - References (Companies, Departments)
-- `loc_*` - Localization (Languages, Translations)
-- `lic_*` - Licensing (Licenses)
-
-Example: `.ToTable("auth_Users", "core")`
-
-### Migration Naming
-Format: `YYYYMMDD_NNN_Description`
-- Example: `20260115_001_InitialSchema`
-
-### Service Pattern
-- Interface: `I{Name}Service`
-- Implementation: `{Name}Service`
-
-### Namespace Structure
-- Domain: `SmartStack.Domain`
-- Application: `SmartStack.Application`
-- Infrastructure: `SmartStack.Infrastructure`
-- API: `SmartStack.Api`
+| Resource URI | Description |
+|--------------|-------------|
+| `smartstack://conventions` | Naming conventions |
+| `smartstack://project` | Project information |
+| `smartstack://api/{endpoint}` | API documentation |
+| `smartstack://schema/{table}` | Database schema |
 
 ## License
 

package/dist/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -149,7 +148,7 @@ var defaultConfig = {
       "loc_",
       "lic_"
     ],
-    migrationFormat: "YYYYMMDD_NNN_{Description}",
+    migrationFormat: "{context}_v{version}_{sequence}_{Description}",
     namespaces: {
       domain: "SmartStack.Domain",
       application: "SmartStack.Application",
@@ -533,7 +532,7 @@ async function findControllerFiles(apiPath) {
 import path5 from "path";
 var validateConventionsTool = {
   name: "validate_conventions",
-  description: "Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming (YYYYMMDD_NNN_*), service interfaces (I*Service), namespace structure",
+  description: "Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure",
   inputSchema: {
     type: "object",
     properties: {
@@ -675,7 +674,7 @@ async function validateMigrationNaming(structure, _config, result) {
     return;
   }
   const migrationFiles = await findFiles("*.cs", { cwd: structure.migrations });
-  const migrationPattern = /^(\d{8})_(\d{3})_(.+)\.cs$/;
+  const migrationPattern = /^(\w+)_v(\d+\.\d+\.\d+)_(\d{3})_(.+)\.cs$/;
   const designerPattern = /\.Designer\.cs$/;
   for (const file of migrationFiles) {
     const fileName = path5.basename(file);
@@ -688,7 +687,7 @@ async function validateMigrationNaming(structure, _config, result) {
         category: "migrations",
         message: `Migration "${fileName}" does not follow naming convention`,
         file: path5.relative(structure.root, file),
-        suggestion: `Expected format: YYYYMMDD_NNN_Description.cs (e.g., 20260115_001_InitialCreate.cs)`
+        suggestion: `Expected format: {context}_v{version}_{sequence}_{Description}.cs (e.g., core_v1.0.0_001_CreateAuthUsers.cs)`
       });
     }
   }
@@ -696,14 +695,18 @@ async function validateMigrationNaming(structure, _config, result) {
   for (let i = 1; i < orderedMigrations.length; i++) {
     const prev = orderedMigrations[i - 1];
     const curr = orderedMigrations[i];
-    const prevDate = prev.substring(0, 8);
-    const currDate = curr.substring(0, 8);
-    if (currDate < prevDate) {
-      result.warnings.push({
-        type: "warning",
-        category: "migrations",
-        message: `Migration order issue: "${curr}" dated before "${prev}"`
-      });
+    const prevMatch = migrationPattern.exec(prev);
+    const currMatch = migrationPattern.exec(curr);
+    if (prevMatch && currMatch) {
+      const prevVersion = prevMatch[2];
+      const currVersion = currMatch[2];
+      if (currVersion < prevVersion) {
+        result.warnings.push({
+          type: "warning",
+          category: "migrations",
+          message: `Migration order issue: "${curr}" (v${currVersion}) comes before "${prev}" (v${prevVersion})`
+        });
+      }
     }
   }
 }
@@ -871,7 +874,7 @@ async function handleCheckMigrations(args, config) {
 async function parseMigrations(migrationsPath, rootPath) {
   const files = await findFiles("*.cs", { cwd: migrationsPath });
   const migrations = [];
-  const pattern = /^(\d{8})_(\d{3})_(.+)\.cs$/;
+  const pattern = /^(\w+)_v(\d+\.\d+\.\d+)_(\d{3})_(.+)\.cs$/;
   for (const file of files) {
     const fileName = path6.basename(file);
     if (fileName.includes(".Designer.") || fileName.includes("ModelSnapshot")) {
@@ -881,10 +884,13 @@ async function parseMigrations(migrationsPath, rootPath) {
     if (match) {
       migrations.push({
         name: fileName.replace(".cs", ""),
-        timestamp: match[1],
-        prefix: match[2],
-        // Now this is the sequence number (NNN)
-        description: match[3],
+        context: match[1],
+        // DbContext (core, extensions, etc.)
+        version: match[2],
+        // Semver version (1.0.0, 1.2.0, etc.)
+        sequence: match[3],
+        // Sequence number (001, 002, etc.)
+        description: match[4],
         file: path6.relative(rootPath, file),
         applied: true
         // We'd need DB connection to check this
@@ -892,8 +898,9 @@ async function parseMigrations(migrationsPath, rootPath) {
     } else {
       migrations.push({
         name: fileName.replace(".cs", ""),
-        timestamp: "",
-        prefix: "Unknown",
+        context: "Unknown",
+        version: "0.0.0",
+        sequence: "000",
         description: fileName.replace(".cs", ""),
         file: path6.relative(rootPath, file),
         applied: true
@@ -901,51 +908,63 @@ async function parseMigrations(migrationsPath, rootPath) {
     }
   }
   return migrations.sort((a, b) => {
-    const dateCompare = a.timestamp.localeCompare(b.timestamp);
-    if (dateCompare !== 0) return dateCompare;
-    return a.prefix.localeCompare(b.prefix);
+    const versionCompare = compareVersions(a.version, b.version);
+    if (versionCompare !== 0) return versionCompare;
+    return a.sequence.localeCompare(b.sequence);
   });
 }
+function compareVersions(a, b) {
+  const partsA = a.split(".").map(Number);
+  const partsB = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (partsA[i] > partsB[i]) return 1;
+    if (partsA[i] < partsB[i]) return -1;
+  }
+  return 0;
+}
 function checkNamingConventions(result, _config) {
   for (const migration of result.migrations) {
-    if (!migration.timestamp) {
+    if (migration.context === "Unknown") {
       result.conflicts.push({
         type: "naming",
         description: `Migration "${migration.name}" does not follow naming convention`,
         files: [migration.file],
-        resolution: `Rename to format: YYYYMMDD_NNN_Description (e.g., 20260115_001_InitialCreate)`
+        resolution: `Rename to format: {context}_v{version}_{sequence}_{Description} (e.g., core_v1.0.0_001_CreateAuthUsers)`
       });
     }
-    if (migration.prefix === "Unknown") {
+    if (migration.version === "0.0.0") {
       result.conflicts.push({
         type: "naming",
-        description: `Migration "${migration.name}" missing sequence number`,
+        description: `Migration "${migration.name}" missing version number`,
         files: [migration.file],
-        resolution: `Use format: YYYYMMDD_NNN_Description where NNN is a 3-digit sequence (001, 002, etc.)`
+        resolution: `Use format: {context}_v{version}_{sequence}_{Description} where version is semver (1.0.0, 1.2.0, etc.)`
       });
     }
   }
 }
 function checkChronologicalOrder(result) {
-  const migrations = result.migrations.filter((m) => m.timestamp);
+  const migrations = result.migrations.filter((m) => m.context !== "Unknown");
   for (let i = 1; i < migrations.length; i++) {
     const prev = migrations[i - 1];
     const curr = migrations[i];
-    if (curr.timestamp < prev.timestamp) {
-      result.conflicts.push({
-        type: "order",
-        description: `Migration "${curr.name}" (${curr.timestamp}) is dated before "${prev.name}" (${prev.timestamp})`,
-        files: [curr.file, prev.file],
-        resolution: "Reorder migrations or update timestamps"
-      });
-    }
-    if (curr.timestamp === prev.timestamp && curr.prefix === prev.prefix) {
-      result.conflicts.push({
-        type: "order",
-        description: `Migrations "${curr.name}" and "${prev.name}" have same timestamp`,
-        files: [curr.file, prev.file],
-        resolution: "Use different sequence numbers (NNN) or different dates"
-      });
+    if (curr.context === prev.context) {
+      const versionCompare = compareVersions(curr.version, prev.version);
+      if (versionCompare < 0) {
+        result.conflicts.push({
+          type: "order",
+          description: `Migration "${curr.name}" (v${curr.version}) is versioned before "${prev.name}" (v${prev.version})`,
+          files: [curr.file, prev.file],
+          resolution: "Reorder migrations or update version numbers"
+        });
+      }
+      if (curr.version === prev.version && curr.sequence === prev.sequence) {
+        result.conflicts.push({
+          type: "order",
+          description: `Migrations "${curr.name}" and "${prev.name}" have same version and sequence`,
+          files: [curr.file, prev.file],
+          resolution: "Use different sequence numbers (001, 002, etc.) for migrations in the same version"
+        });
+      }
     }
   }
 }
@@ -1000,7 +1019,7 @@ async function checkModelSnapshot(result, structure) {
   }
   const snapshotContent = await readText(snapshotFiles[0]);
   for (const migration of result.migrations) {
-    if (migration.timestamp && !snapshotContent.includes(migration.name)) {
+    if (migration.context !== "Unknown" && !snapshotContent.includes(migration.name)) {
       result.conflicts.push({
         type: "dependency",
         description: `Migration "${migration.name}" not referenced in ModelSnapshot`,
@@ -1018,12 +1037,12 @@ function generateSuggestions(result) {
   }
   if (result.conflicts.some((c) => c.type === "naming")) {
     result.suggestions.push(
-      "Use convention: YYYYMMDD_NNN_Description for migration naming (e.g., 20260115_001_InitialCreate)"
+      "Use convention: {context}_v{version}_{sequence}_{Description} for migration naming (e.g., core_v1.0.0_001_CreateAuthUsers)"
     );
   }
   if (result.conflicts.some((c) => c.type === "order")) {
     result.suggestions.push(
-      "Ensure migrations are created in chronological order to avoid conflicts"
+      "Ensure migrations are created in version order to avoid conflicts"
     );
   }
   if (result.migrations.length > 20) {
@@ -1047,11 +1066,11 @@ function formatResult2(result, currentBranch, compareBranch) {
   lines.push("");
   lines.push("## Migrations");
   lines.push("");
-  lines.push("| Name | Timestamp | Prefix | Description |");
-  lines.push("|------|-----------|--------|-------------|");
+  lines.push("| Name | Context | Version | Sequence | Description |");
+  lines.push("|------|---------|---------|----------|-------------|");
   for (const migration of result.migrations) {
     lines.push(
-      `| ${migration.name} | ${migration.timestamp || "N/A"} | ${migration.prefix} | ${migration.description} |`
+      `| ${migration.name} | ${migration.context} | ${migration.version} | ${migration.sequence} | ${migration.description} |`
     );
   }
   lines.push("");
@@ -1978,28 +1997,37 @@ Migrations MUST follow this naming pattern:
 ${migrationFormat}
 \`\`\`
 
+| Part | Description | Example |
+|------|-------------|---------|
+| \`{context}\` | DbContext name | \`core\`, \`extensions\` |
+| \`{version}\` | Semver version | \`v1.0.0\`, \`v1.2.0\` |
+| \`{sequence}\` | Order in version | \`001\`, \`002\` |
+| \`{Description}\` | Action (PascalCase) | \`CreateAuthUsers\` |
+
 **Examples:**
-- \`20260115_001_InitialSchema.cs\`
-- \`20260120_002_AddUserProfiles.cs\`
-- \`20260125_003_AddSupportTickets.cs\`
+- \`core_v1.0.0_001_InitialSchema.cs\`
+- \`core_v1.0.0_002_CreateAuthUsers.cs\`
+- \`core_v1.2.0_001_AddUserProfiles.cs\`
+- \`extensions_v1.0.0_001_AddClientFeatures.cs\`
 
 ### Creating Migrations
 
 \`\`\`bash
 # Create a new migration
-dotnet ef migrations add 20260115_001_InitialSchema
+dotnet ef migrations add core_v1.0.0_001_InitialSchema
 
 # With context specified
-dotnet ef migrations add 20260115_001_InitialSchema --context ApplicationDbContext
+dotnet ef migrations add core_v1.2.0_001_AddUserProfiles --context ApplicationDbContext
 \`\`\`
 
 ### Migration Rules
 
 1. **One migration per feature** - Group related changes in a single migration
-2. **Timestamps ensure order** - Use YYYYMMDD format for chronological sorting
-3. **Sequence numbers** - Use NNN (001, 002, etc.) for migrations on the same day
-4. **Descriptive names** - Use clear descriptions (InitialSchema, AddUserProfiles, etc.)
-5. **Schema must be specified** - All tables must specify their schema in ToTable()
+2. **Version-based naming** - Use semver (v1.0.0, v1.2.0) to link migrations to releases
+3. **Sequence numbers** - Use NNN (001, 002, etc.) for migrations in the same version
+4. **Context prefix** - Use \`core_\` for platform tables, \`extensions_\` for client extensions
+5. **Descriptive names** - Use clear PascalCase descriptions (CreateAuthUsers, AddUserProfiles, etc.)
+6. **Schema must be specified** - All tables must specify their schema in ToTable()
 
 ---
 
@@ -2166,7 +2194,7 @@ public interface IUserServiceHooks
 | Platform schema | \`${schemas.platform}\` | \`.ToTable("auth_Users", "${schemas.platform}")\` |
 | Extensions schema | \`${schemas.extensions}\` | \`.ToTable("client_Custom", "${schemas.extensions}")\` |
 | Table prefixes | \`${tablePrefixes.slice(0, 5).join(", ")}\`, etc. | \`auth_Users\`, \`nav_Modules\` |
-| Migration | \`YYYYMMDD_NNN_Description\` | \`20260115_001_InitialCreate\` |
+| Migration | \`{context}_v{version}_{seq}_{Desc}\` | \`core_v1.0.0_001_CreateAuthUsers\` |
 | Interface | \`I<Name>Service\` | \`IUserService\` |
 | Implementation | \`<Name>Service\` | \`UserService\` |
 | Domain namespace | \`${namespaces.domain}\` | - |