@veloxts/mcp 0.6.51 → 0.6.54

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @veloxts/mcp
 
+## 0.6.54
+
+### Patch Changes
+
+- feat(cli): add velox mcp init command for Claude Desktop setup
+- Updated dependencies
+  - @veloxts/cli@0.6.54
+  - @veloxts/router@0.6.54
+  - @veloxts/validation@0.6.54
+
+## 0.6.53
+
+### Patch Changes
+
+- feat(cli): add duplicate file detection to resource generator
+- Updated dependencies
+  - @veloxts/cli@0.6.53
+  - @veloxts/router@0.6.53
+  - @veloxts/validation@0.6.53
+
+## 0.6.52
+
+### Patch Changes
+
+- feat(mcp): smart CLI resolution with fallbacks
+- Updated dependencies
+  - @veloxts/cli@0.6.52
+  - @veloxts/router@0.6.52
+  - @veloxts/validation@0.6.52
+
 ## 0.6.51
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,109 @@
 
 > **Early Preview (v0.6.x)** - APIs are stabilizing but may still change.
 
-Model Context Protocol server for VeloxTS - exposes project context (procedures, schemas, routes, errors) to AI assistants like Claude for intelligent code assistance. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
+Model Context Protocol server for VeloxTS - exposes project context (procedures, schemas, routes, errors) to AI assistants like Claude Desktop and other tools that support the Model Context Protocol.
+
+## Quick Start
+
+### Automatic Setup (Recommended)
+
+The easiest way to set up the MCP server is using the VeloxTS CLI:
+
+```bash
+velox mcp init
+```
+
+This command will:
+- Detect your operating system
+- Locate your Claude Desktop configuration
+- Add the VeloxTS MCP server configuration
+- Guide you through the setup process
+
+After running the command, **restart Claude Desktop** to activate the integration.
+
+### Manual Setup
+
+If you prefer to configure manually, add this to your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "veloxts": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"]
+    }
+  }
+}
+```
+
+## What It Does
+
+The MCP server provides Claude Desktop with deep context about your VeloxTS project:
+
+- **Procedures**: All API procedures with their inputs, outputs, and business logic
+- **Schemas**: Zod validation schemas and type definitions
+- **Routes**: REST endpoints and tRPC procedure mappings
+- **Errors**: Custom error types and error handling patterns
+- **Project Structure**: File organization and module boundaries
+
+This enables Claude to:
+- Suggest code that matches your existing patterns
+- Understand your API surface and data models
+- Generate procedures that fit seamlessly with your codebase
+- Help debug issues with full context of your project
+
+## CLI Commands
+
+### velox mcp init
+
+Set up Claude Desktop configuration automatically:
+
+```bash
+velox mcp init             # Interactive setup
+velox mcp init --dry-run   # Preview changes without writing
+velox mcp init --force     # Overwrite existing configuration
+velox mcp init --json      # Output as JSON for scripting
+```
+
+Options:
+- `--dry-run, -d`: Preview configuration changes without writing files
+- `--force, -f`: Overwrite existing VeloxTS MCP configuration
+- `--json`: Output results as JSON for automated workflows
+
+## Troubleshooting
+
+### Claude Desktop doesn't show VeloxTS context
+
+1. Ensure you've restarted Claude Desktop after running `velox mcp init`
+2. Check that the configuration file exists and is valid JSON
+3. Verify `@veloxts/mcp` is installed in your project or globally accessible
+4. Try running `npx @veloxts/mcp` manually to test the server
+
+### Configuration file not found
+
+Run `velox mcp init --dry-run` to see the expected configuration path for your platform. If Claude Desktop is not installed, the command will warn you.
+
+### Permission errors
+
+On macOS/Linux, ensure you have write access to the configuration directory:
+
+```bash
+# Check permissions
+ls -la ~/Library/Application\ Support/Claude  # macOS
+ls -la ~/.config/Claude                        # Linux
+```
+
+## Learn More
+
+- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
+- [@veloxts/cli](https://www.npmjs.com/package/@veloxts/cli) - VeloxTS CLI tools
+- [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox) - Complete VeloxTS framework
 
 ## License
 

package/dist/tools/generate.js

@@ -5,6 +5,7 @@
  */
 import { spawn } from 'node:child_process';
 import { z } from 'zod';
+import { resolveVeloxCLI } from '../utils/cli.js';
 import { findProjectRoot } from '../utils/project.js';
 // ============================================================================
 // Output Validation Schemas
@@ -55,10 +56,11 @@ export async function generate(options) {
         };
     }
     const args = buildArgs(options);
+    const resolved = resolveVeloxCLI(projectRoot, args);
     return new Promise((resolve) => {
-        const child = spawn('npx', ['velox', ...args], {
+        const child = spawn(resolved.command, resolved.args, {
             cwd: projectRoot,
-            shell: true,
+            shell: resolved.isNpx, // Only use shell for npx fallback
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         let stdout = '';

package/dist/tools/migrate.js

@@ -5,6 +5,7 @@
  */
 import { spawn } from 'node:child_process';
 import { z } from 'zod';
+import { resolveVeloxCLI } from '../utils/cli.js';
 import { findProjectRoot } from '../utils/project.js';
 // ============================================================================
 // Output Validation Schemas
@@ -54,10 +55,11 @@ export async function migrate(options) {
         };
     }
     const args = buildArgs(options);
+    const resolved = resolveVeloxCLI(projectRoot, args);
     return new Promise((resolve) => {
-        const child = spawn('npx', ['velox', ...args], {
+        const child = spawn(resolved.command, resolved.args, {
             cwd: projectRoot,
-            shell: true,
+            shell: resolved.isNpx, // Only use shell for npx fallback
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         let stdout = '';

package/dist/utils/cli.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI Resolution Utilities
+ *
+ * Utilities for finding and executing the VeloxTS CLI binary.
+ */
+/**
+ * Resolved CLI command information
+ */
+export interface ResolvedCLI {
+    /** Command to execute (binary path, 'node', or 'npx') */
+    command: string;
+    /** Arguments to pass (includes binary path if using node, or '@veloxts/cli' if using npx) */
+    args: string[];
+    /** Whether we're using npx fallback */
+    isNpx: boolean;
+}
+/**
+ * Resolve the VeloxTS CLI binary path with smart fallbacks
+ *
+ * Resolution order:
+ * 1. Local node_modules/.bin/velox (fastest, respects local version)
+ * 2. Windows .cmd wrapper (node_modules/.bin/velox.cmd)
+ * 3. Resolve @veloxts/cli package and find bin entry
+ * 4. Fallback to npx @veloxts/cli (slowest, downloads if needed)
+ */
+export declare function resolveVeloxCLI(projectRoot: string, args: string[]): ResolvedCLI;

package/dist/utils/cli.js

@@ -0,0 +1,68 @@
+/**
+ * CLI Resolution Utilities
+ *
+ * Utilities for finding and executing the VeloxTS CLI binary.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Resolve the VeloxTS CLI binary path with smart fallbacks
+ *
+ * Resolution order:
+ * 1. Local node_modules/.bin/velox (fastest, respects local version)
+ * 2. Windows .cmd wrapper (node_modules/.bin/velox.cmd)
+ * 3. Resolve @veloxts/cli package and find bin entry
+ * 4. Fallback to npx @veloxts/cli (slowest, downloads if needed)
+ */
+export function resolveVeloxCLI(projectRoot, args) {
+    const isWindows = process.platform === 'win32';
+    // 1. Try local .bin/velox (Unix)
+    if (!isWindows) {
+        const localBin = join(projectRoot, 'node_modules', '.bin', 'velox');
+        if (existsSync(localBin)) {
+            return {
+                command: localBin,
+                args,
+                isNpx: false,
+            };
+        }
+    }
+    // 2. Try Windows .cmd wrapper
+    if (isWindows) {
+        const localBinCmd = join(projectRoot, 'node_modules', '.bin', 'velox.cmd');
+        if (existsSync(localBinCmd)) {
+            return {
+                command: localBinCmd,
+                args,
+                isNpx: false,
+            };
+        }
+    }
+    // 3. Try resolving @veloxts/cli package directly
+    try {
+        const cliPackageJson = join(projectRoot, 'node_modules', '@veloxts', 'cli', 'package.json');
+        if (existsSync(cliPackageJson)) {
+            const pkg = JSON.parse(readFileSync(cliPackageJson, 'utf-8'));
+            const binRelative = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.velox;
+            if (binRelative) {
+                const binPath = join(projectRoot, 'node_modules', '@veloxts', 'cli', binRelative);
+                if (existsSync(binPath)) {
+                    return {
+                        command: 'node',
+                        args: [binPath, ...args],
+                        isNpx: false,
+                    };
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore resolution errors, fall through to npx
+    }
+    // 4. Fallback to npx (works even if not installed locally)
+    return {
+        command: 'npx',
+        args: ['@veloxts/cli', ...args],
+        isNpx: true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/mcp",
-  "version": "0.6.51",
+  "version": "0.6.54",
   "description": "Model Context Protocol server for VeloxTS - expose project context to AI tools",
   "type": "module",
   "main": "dist/index.js",
@@ -23,9 +23,9 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.25.1",
-    "@veloxts/router": "0.6.51",
-    "@veloxts/validation": "0.6.51",
-    "@veloxts/cli": "0.6.51"
+    "@veloxts/cli": "0.6.54",
+    "@veloxts/router": "0.6.54",
+    "@veloxts/validation": "0.6.54"
   },
   "peerDependencies": {
     "zod": ">=3.25.0"