@atlashub/smartstack-mcp 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +96 -140
  2. package/dist/index.js +117 -79
  3. package/dist/index.js.map +1 -1
  4. package/package.json +65 -65
package/README.md CHANGED
@@ -1,198 +1,154 @@
1
- # @smartstack/mcp-server
1
+ # @atlashub/smartstack-mcp
2
2
 
3
3
  MCP (Model Context Protocol) server for SmartStack/AtlasHub platform development.
4
4
 
5
- ## Features
5
+ ## Installation
6
6
 
7
- ### Tools
7
+ ### Option 1: Claude Code CLI (Recommended)
8
8
 
9
- | Tool | Description |
10
- |------|-------------|
11
- | `validate_conventions` | Validate AtlasHub conventions (SQL schemas, domain table prefixes, migration naming, service interfaces) |
12
- | `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
13
- | `scaffold_extension` | Generate code for services, entities, controllers, or React components |
14
- | `api_docs` | Get API endpoint documentation from Swagger or code analysis |
9
+ ```bash
10
+ # Add SmartStack MCP (user-level, available in all projects)
11
+ claude mcp add smartstack -s user -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- npx -y @atlashub/smartstack-mcp
15
12
 
16
- ### Resources
13
+ # Or project-level (only for current project)
14
+ claude mcp add smartstack -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- npx -y @atlashub/smartstack-mcp
17
15
 
18
- | Resource URI | Description |
19
- |--------------|-------------|
20
- | `smartstack://conventions` | AtlasHub naming conventions and best practices |
21
- | `smartstack://project` | Current project information and structure |
22
- | `smartstack://api/{endpoint}` | API endpoint documentation |
23
- | `smartstack://schema/{table}` | Database schema information |
24
-
25
- ## Installation
16
+ # With global install (faster startup)
17
+ npm install -g @atlashub/smartstack-mcp
18
+ claude mcp add smartstack -s user -e SMARTSTACK_PROJECT_PATH=C:/path/to/your/SmartStack.app -- smartstack-mcp
19
+ ```
26
20
 
21
+ **Verify installation:**
27
22
  ```bash
28
- # Clone and install dependencies
29
- cd "D:\01 - projets\SmartStack.mcp\02-Develop"
30
- npm install
31
-
32
- # Build
33
- npm run build
23
+ claude mcp list
34
24
  ```
35
25
 
36
- ## Configuration
37
-
38
- ### Environment Variables
26
+ ### Option 2: Visual Studio Code (Extension Claude Code)
39
27
 
40
- | Variable | Description | Default |
41
- |----------|-------------|---------|
42
- | `SMARTSTACK_PROJECT_PATH` | Path to SmartStack.app project | `D:/SmartStack.app/features/Rework-to-package` |
43
- | `SMARTSTACK_API_URL` | SmartStack API URL | `https://localhost:7055` |
44
- | `SMARTSTACK_API_ENABLED` | Enable API integration | `true` |
45
- | `LOG_LEVEL` | Logging level (debug, info, warn, error) | `info` |
46
-
47
- ### Claude Desktop Configuration
48
-
49
- Add to your Claude Desktop config file (`claude_desktop_config.json`):
28
+ Create a `.mcp.json` file at the root of your project:
50
29
 
51
30
  ```json
52
31
  {
53
32
  "mcpServers": {
54
33
  "smartstack": {
55
- "command": "node",
56
- "args": ["D:/01 - projets/SmartStack.mcp/02-Develop/dist/index.js"],
34
+ "command": "npx",
35
+ "args": ["-y", "@atlashub/smartstack-mcp"],
57
36
  "env": {
58
- "SMARTSTACK_PROJECT_PATH": "D:/SmartStack.app/features/Rework-to-package",
59
- "SMARTSTACK_API_URL": "https://localhost:7055"
37
+ "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
60
38
  }
61
39
  }
62
40
  }
63
41
  }
64
42
  ```
65
43
 
66
- ### Claude Code Configuration
67
-
68
- Add to your `.claude/settings.json`:
44
+ Or with global install (faster startup):
69
45
 
70
46
  ```json
71
47
  {
72
48
  "mcpServers": {
73
49
  "smartstack": {
74
- "command": "node",
75
- "args": ["D:/01 - projets/SmartStack.mcp/02-Develop/dist/index.js"],
50
+ "command": "smartstack-mcp",
76
51
  "env": {
77
- "SMARTSTACK_PROJECT_PATH": "D:/SmartStack.app/features/Rework-to-package"
52
+ "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
78
53
  }
79
54
  }
80
55
  }
81
56
  }
82
57
  ```
83
58
 
84
- ## Usage Examples
59
+ **Steps:**
60
+ 1. Install the Claude Code extension in VS Code
61
+ 2. Create the `.mcp.json` file at project root
62
+ 3. Reload VS Code or the extension
63
+ 4. The MCP server will be available in Claude Code panel
85
64
 
86
- ### Validate Conventions
65
+ ### Option 3: Claude Desktop
87
66
 
88
- ```
89
- Use validate_conventions tool with checks: ["tables", "migrations", "services"]
90
- ```
67
+ Add to `claude_desktop_config.json`:
91
68
 
92
- ### Check Migrations
69
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
70
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
93
71
 
94
- ```
95
- Use check_migrations tool with compareBranch: "develop"
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "smartstack": {
76
+ "command": "npx",
77
+ "args": ["-y", "@atlashub/smartstack-mcp"],
78
+ "env": {
79
+ "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
80
+ }
81
+ }
82
+ }
83
+ }
96
84
  ```
97
85
 
98
- ### Scaffold a Service
86
+ ### Option 4: Manual Execution
99
87
 
100
- ```
101
- Use scaffold_extension tool with:
102
- - type: "service"
103
- - name: "UserProfile"
104
- - options: { methods: ["GetByIdAsync", "UpdateAsync"] }
88
+ ```bash
89
+ # Using npx (no install required)
90
+ SMARTSTACK_PROJECT_PATH=/path/to/project npx @atlashub/smartstack-mcp
91
+
92
+ # Or if installed globally
93
+ npm install -g @atlashub/smartstack-mcp
94
+ SMARTSTACK_PROJECT_PATH=/path/to/project smartstack-mcp
105
95
  ```
106
96
 
107
- ### Get API Documentation
97
+ ## Adding Context7 (Optional)
108
98
 
109
- ```
110
- Use api_docs tool with:
111
- - endpoint: "/api/users"
112
- - format: "markdown"
99
+ Context7 provides up-to-date documentation lookups for any library.
100
+
101
+ **Claude Code CLI:**
102
+ ```bash
103
+ claude mcp add context7 -s user -- npx -y @upstash/context7-mcp
113
104
  ```
114
105
 
115
- ## Development
106
+ **VS Code (.mcp.json):**
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "smartstack": {
111
+ "command": "npx",
112
+ "args": ["-y", "@atlashub/smartstack-mcp"],
113
+ "env": {
114
+ "SMARTSTACK_PROJECT_PATH": "C:/path/to/your/SmartStack.app"
115
+ }
116
+ },
117
+ "context7": {
118
+ "command": "npx",
119
+ "args": ["-y", "@upstash/context7-mcp"]
120
+ }
121
+ }
122
+ }
123
+ ```
116
124
 
117
- ```bash
118
- # Watch mode
119
- npm run dev
125
+ ## Configuration
120
126
 
121
- # Test with MCP Inspector
122
- npm run inspect
127
+ | Variable | Description | Required |
128
+ |----------|-------------|----------|
129
+ | `SMARTSTACK_PROJECT_PATH` | Path to your SmartStack.app project | Yes |
130
+ | `SMARTSTACK_API_URL` | SmartStack API URL | No |
131
+ | `LOG_LEVEL` | Logging level (debug, info, warn, error) | No |
123
132
 
124
- # Type check
125
- npm run typecheck
133
+ ## Features
126
134
 
127
- # Lint
128
- npm run lint
129
- ```
135
+ ### Tools
130
136
 
131
- ## Project Structure
137
+ | Tool | Description |
138
+ |------|-------------|
139
+ | `validate_conventions` | Validate AtlasHub conventions |
140
+ | `check_migrations` | Analyze EF Core migrations |
141
+ | `scaffold_extension` | Generate code scaffolding |
142
+ | `api_docs` | Get API documentation |
132
143
 
133
- ```
134
- src/
135
- ├── index.ts # Entry point
136
- ├── server.ts # MCP server configuration
137
- ├── config.ts # Configuration management
138
- ├── tools/ # MCP tool implementations
139
- │ ├── validate-conventions.ts
140
- │ ├── check-migrations.ts
141
- │ ├── scaffold-extension.ts
142
- │ └── api-docs.ts
143
- ├── resources/ # MCP resource implementations
144
- │ ├── conventions.ts
145
- │ ├── project-info.ts
146
- │ ├── api-endpoints.ts
147
- │ └── db-schema.ts
148
- ├── lib/ # Shared libraries
149
- │ ├── detector.ts # Project detection
150
- │ └── logger.ts # Logging utilities
151
- ├── types/ # TypeScript types
152
- │ └── index.ts
153
- └── utils/ # Utility functions
154
- ├── fs.ts # File system operations
155
- ├── git.ts # Git commands
156
- └── dotnet.ts # .NET CLI commands
157
- ```
144
+ ### Resources
158
145
 
159
- ## AtlasHub Conventions
160
-
161
- This MCP server enforces the following conventions:
162
-
163
- ### SQL Schemas
164
- - **`core`**: SmartStack platform tables
165
- - **`extensions`**: Client extension tables
166
-
167
- ### Table Prefixes (by domain)
168
- Tables use domain-specific prefixes within schemas:
169
- - `auth_*` - Authorization (Users, Roles, Permissions)
170
- - `nav_*` - Navigation (Contexts, Applications, Modules)
171
- - `usr_*` - User profiles (Profiles, Preferences)
172
- - `ai_*` - AI features (Providers, Models, Prompts)
173
- - `cfg_*` - Configuration (Settings)
174
- - `wkf_*` - Workflows (EmailTemplates, Workflows)
175
- - `support_*` - Support (Tickets, Comments)
176
- - `entra_*` - Entra sync (Groups, SyncState)
177
- - `ref_*` - References (Companies, Departments)
178
- - `loc_*` - Localization (Languages, Translations)
179
- - `lic_*` - Licensing (Licenses)
180
-
181
- Example: `.ToTable("auth_Users", "core")`
182
-
183
- ### Migration Naming
184
- Format: `YYYYMMDD_NNN_Description`
185
- - Example: `20260115_001_InitialSchema`
186
-
187
- ### Service Pattern
188
- - Interface: `I{Name}Service`
189
- - Implementation: `{Name}Service`
190
-
191
- ### Namespace Structure
192
- - Domain: `SmartStack.Domain`
193
- - Application: `SmartStack.Application`
194
- - Infrastructure: `SmartStack.Infrastructure`
195
- - API: `SmartStack.Api`
146
+ | Resource URI | Description |
147
+ |--------------|-------------|
148
+ | `smartstack://conventions` | Naming conventions |
149
+ | `smartstack://project` | Project information |
150
+ | `smartstack://api/{endpoint}` | API documentation |
151
+ | `smartstack://schema/{table}` | Database schema |
196
152
 
197
153
  ## License
198
154