@veloxts/mcp 0.6.52 → 0.6.55

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @veloxts/mcp
 
+## 0.6.55
+
+### Patch Changes
+
+- feat(mcp): add static TypeScript analyzer for procedure discovery
+- Updated dependencies
+  - @veloxts/cli@0.6.55
+  - @veloxts/router@0.6.55
+  - @veloxts/validation@0.6.55
+
+## 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

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/resources/procedures.d.ts

@@ -2,6 +2,7 @@
  * Procedures Resource
  *
  * Exposes VeloxTS procedure information to AI tools.
+ * Uses dynamic discovery when possible, falls back to static analysis for TypeScript files.
  */
 /**
  * Information about a single procedure
@@ -44,6 +45,9 @@ export interface ProceduresResourceResponse {
 }
 /**
  * Discover and return procedure information for a project
+ *
+ * Uses static TypeScript analysis as primary method (works with uncompiled TS),
+ * falls back to dynamic discovery for compiled projects.
  */
 export declare function getProcedures(projectRoot: string): Promise<ProceduresResourceResponse>;
 /**

package/dist/resources/procedures.js

@@ -2,9 +2,11 @@
  * Procedures Resource
  *
  * Exposes VeloxTS procedure information to AI tools.
+ * Uses dynamic discovery when possible, falls back to static analysis for TypeScript files.
  */
 import { discoverProceduresVerbose, getRouteSummary } from '@veloxts/router';
 import { getProceduresPath } from '../utils/project.js';
+import { analyzeDirectory } from './static-analyzer.js';
 // ============================================================================
 // Resource Handler
 // ============================================================================
@@ -48,47 +50,85 @@ function extractProcedureInfo(collections) {
 }
 /**
  * Discover and return procedure information for a project
+ *
+ * Uses static TypeScript analysis as primary method (works with uncompiled TS),
+ * falls back to dynamic discovery for compiled projects.
  */
 export async function getProcedures(projectRoot) {
     const proceduresPath = getProceduresPath(projectRoot);
     if (!proceduresPath) {
-        return {
-            procedures: [],
-            namespaces: [],
-            totalCount: 0,
-            queries: 0,
-            mutations: 0,
-        };
+        return emptyResponse();
+    }
+    // Primary: Static TypeScript analysis (works with uncompiled .ts files)
+    const staticResult = analyzeDirectory(proceduresPath);
+    if (staticResult.procedures.length > 0) {
+        return formatStaticResult(staticResult);
     }
-    let result;
+    // Fallback: Dynamic discovery (works with compiled .js files or ts-node)
     try {
-        result = await discoverProceduresVerbose(proceduresPath, {
+        const dynamicResult = await discoverProceduresVerbose(proceduresPath, {
             recursive: true,
-            onInvalidExport: 'warn',
+            onInvalidExport: 'silent',
         });
-    }
-    catch {
+        const { procedures, namespaces } = extractProcedureInfo(dynamicResult.collections);
+        const queries = procedures.filter((p) => p.type === 'query').length;
+        const mutations = procedures.filter((p) => p.type === 'mutation').length;
         return {
-            procedures: [],
-            namespaces: [],
-            totalCount: 0,
-            queries: 0,
-            mutations: 0,
+            procedures,
+            namespaces,
+            totalCount: procedures.length,
+            queries,
+            mutations,
+            discoveryInfo: {
+                scannedFiles: dynamicResult.scannedFiles.length,
+                loadedFiles: dynamicResult.loadedFiles.length,
+                warnings: dynamicResult.warnings.length,
+            },
         };
     }
-    const { procedures, namespaces } = extractProcedureInfo(result.collections);
+    catch {
+        // Dynamic discovery failed (expected for uncompiled TS projects)
+    }
+    return emptyResponse();
+}
+/**
+ * Create empty response
+ */
+function emptyResponse() {
+    return {
+        procedures: [],
+        namespaces: [],
+        totalCount: 0,
+        queries: 0,
+        mutations: 0,
+    };
+}
+/**
+ * Format static analysis result as ProceduresResourceResponse
+ */
+function formatStaticResult(staticResult) {
+    const procedures = staticResult.procedures.map((p) => ({
+        name: p.name,
+        namespace: p.namespace,
+        type: p.type === 'unknown' ? 'query' : p.type, // Default unknown to query
+        hasInputSchema: p.hasInputSchema,
+        hasOutputSchema: p.hasOutputSchema,
+        guardCount: p.hasGuards ? 1 : 0,
+        middlewareCount: p.hasMiddleware ? 1 : 0,
+        route: p.route,
+    }));
     const queries = procedures.filter((p) => p.type === 'query').length;
     const mutations = procedures.filter((p) => p.type === 'mutation').length;
     return {
         procedures,
-        namespaces,
+        namespaces: staticResult.namespaces,
         totalCount: procedures.length,
         queries,
         mutations,
         discoveryInfo: {
-            scannedFiles: result.scannedFiles.length,
-            loadedFiles: result.loadedFiles.length,
-            warnings: result.warnings.length,
+            scannedFiles: staticResult.files.length,
+            loadedFiles: staticResult.files.length,
+            warnings: staticResult.errors.length,
         },
     };
 }

package/dist/resources/static-analyzer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Static TypeScript Analyzer
+ *
+ * Extracts procedure information from TypeScript source files without execution.
+ * Uses TypeScript Compiler API in parse-only mode for accurate AST analysis.
+ * Falls back to regex for edge cases.
+ */
+export interface StaticProcedureInfo {
+    name: string;
+    namespace: string;
+    type: 'query' | 'mutation' | 'unknown';
+    hasInputSchema: boolean;
+    hasOutputSchema: boolean;
+    hasGuards: boolean;
+    hasMiddleware: boolean;
+    route?: {
+        method: string;
+        path: string;
+    };
+    restOverride?: {
+        method?: string;
+        path?: string;
+    };
+}
+export interface StaticAnalysisResult {
+    procedures: StaticProcedureInfo[];
+    namespaces: string[];
+    files: string[];
+    errors: string[];
+}
+/**
+ * Analyze a procedures directory statically
+ */
+export declare function analyzeDirectory(proceduresPath: string): StaticAnalysisResult;
+/**
+ * Format static analysis result as text
+ */
+export declare function formatStaticAnalysisAsText(result: StaticAnalysisResult): string;

package/dist/resources/static-analyzer.js

@@ -0,0 +1,377 @@
+/**
+ * Static TypeScript Analyzer
+ *
+ * Extracts procedure information from TypeScript source files without execution.
+ * Uses TypeScript Compiler API in parse-only mode for accurate AST analysis.
+ * Falls back to regex for edge cases.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import ts from 'typescript';
+// ============================================================================
+// Procedure Name to HTTP Method Mapping
+// ============================================================================
+const METHOD_PREFIXES = {
+    get: { method: 'GET', type: 'query' },
+    list: { method: 'GET', type: 'query' },
+    find: { method: 'GET', type: 'query' },
+    search: { method: 'GET', type: 'query' },
+    create: { method: 'POST', type: 'mutation' },
+    add: { method: 'POST', type: 'mutation' },
+    update: { method: 'PUT', type: 'mutation' },
+    edit: { method: 'PUT', type: 'mutation' },
+    patch: { method: 'PATCH', type: 'mutation' },
+    delete: { method: 'DELETE', type: 'mutation' },
+    remove: { method: 'DELETE', type: 'mutation' },
+};
+// ============================================================================
+// Main Analysis Functions
+// ============================================================================
+/**
+ * Analyze a procedures directory statically
+ */
+export function analyzeDirectory(proceduresPath) {
+    const result = {
+        procedures: [],
+        namespaces: [],
+        files: [],
+        errors: [],
+    };
+    try {
+        const entries = readdirSync(proceduresPath);
+        for (const entry of entries) {
+            const fullPath = join(proceduresPath, entry);
+            try {
+                const stat = statSync(fullPath);
+                if (stat.isFile() && isTypeScriptFile(entry) && !isExcluded(entry)) {
+                    result.files.push(fullPath);
+                    try {
+                        const content = readFileSync(fullPath, 'utf-8');
+                        const collections = analyzeFileWithAST(fullPath, content);
+                        for (const collection of collections) {
+                            if (!result.namespaces.includes(collection.namespace)) {
+                                result.namespaces.push(collection.namespace);
+                            }
+                            for (const proc of collection.procedures) {
+                                const info = toProcedureInfo(proc, collection.namespace);
+                                result.procedures.push(info);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        result.errors.push(`Error analyzing ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+            catch (err) {
+                result.errors.push(`Error accessing ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        result.errors.push(`Error reading directory: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result;
+}
+// ============================================================================
+// TypeScript Compiler API Analysis
+// ============================================================================
+/**
+ * Parse a TypeScript file and extract procedure information using the TS Compiler API.
+ * Uses parse-only mode (no type checking) for speed and to avoid import resolution.
+ */
+function analyzeFileWithAST(filePath, content) {
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, // setParentNodes - needed for tree traversal
+    ts.ScriptKind.TS);
+    const collections = [];
+    // Visit all nodes looking for procedures() or defineProcedures() calls
+    function visit(node) {
+        if (ts.isCallExpression(node)) {
+            const collection = tryExtractProcedureCollection(node);
+            if (collection) {
+                collections.push({ ...collection, filePath });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    // If no collections found via AST, try regex fallback
+    if (collections.length === 0) {
+        const regexResult = analyzeFileWithRegex(filePath, content);
+        if (regexResult) {
+            collections.push(regexResult);
+        }
+    }
+    return collections;
+}
+/**
+ * Try to extract a procedure collection from a call expression.
+ * Looks for: procedures('namespace', { ... }) or defineProcedures('namespace', { ... })
+ */
+function tryExtractProcedureCollection(node) {
+    // Check if this is a procedures() or defineProcedures() call
+    const callee = node.expression;
+    let functionName;
+    if (ts.isIdentifier(callee)) {
+        functionName = callee.text;
+    }
+    if (functionName !== 'procedures' && functionName !== 'defineProcedures') {
+        return null;
+    }
+    // Extract namespace from first argument
+    const [namespaceArg, proceduresArg] = node.arguments;
+    if (!namespaceArg || !ts.isStringLiteral(namespaceArg)) {
+        return null;
+    }
+    const namespace = namespaceArg.text;
+    // Extract procedures from second argument (object literal)
+    if (!proceduresArg || !ts.isObjectLiteralExpression(proceduresArg)) {
+        return null;
+    }
+    const procedures = [];
+    for (const prop of proceduresArg.properties) {
+        if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+            const procedureName = prop.name.text;
+            const procedureInfo = extractProcedureInfo(prop.initializer);
+            procedures.push({
+                name: procedureName,
+                ...procedureInfo,
+            });
+        }
+    }
+    return { namespace, procedures };
+}
+/**
+ * Extract procedure information from a procedure builder chain.
+ * Handles: procedure().input(...).output(...).guard(...).query/mutation(...)
+ */
+function extractProcedureInfo(node) {
+    const info = {
+        type: 'unknown',
+        hasInput: false,
+        hasOutput: false,
+        hasGuard: false,
+        hasMiddleware: false,
+    };
+    // Walk the call chain
+    function walkChain(n) {
+        if (!ts.isCallExpression(n))
+            return;
+        const callee = n.expression;
+        // Check for method calls on the chain
+        if (ts.isPropertyAccessExpression(callee)) {
+            const methodName = callee.name.text;
+            switch (methodName) {
+                case 'query':
+                    info.type = 'query';
+                    break;
+                case 'mutation':
+                    info.type = 'mutation';
+                    break;
+                case 'input':
+                    info.hasInput = true;
+                    break;
+                case 'output':
+                    info.hasOutput = true;
+                    break;
+                case 'guard':
+                    info.hasGuard = true;
+                    break;
+                case 'use':
+                    info.hasMiddleware = true;
+                    break;
+                case 'rest':
+                    info.restOverride = extractRestOverride(n.arguments[0]);
+                    break;
+            }
+            // Continue walking up the chain
+            walkChain(callee.expression);
+        }
+    }
+    walkChain(node);
+    return info;
+}
+/**
+ * Extract REST override configuration from .rest({ method, path }) call
+ */
+function extractRestOverride(arg) {
+    if (!arg || !ts.isObjectLiteralExpression(arg)) {
+        return undefined;
+    }
+    const result = {};
+    for (const prop of arg.properties) {
+        if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+            const key = prop.name.text;
+            if ((key === 'method' || key === 'path') && ts.isStringLiteral(prop.initializer)) {
+                result[key] = prop.initializer.text;
+            }
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+// ============================================================================
+// Regex Fallback Analysis
+// ============================================================================
+/**
+ * Fallback regex-based analysis for files that don't match the standard pattern
+ */
+function analyzeFileWithRegex(filePath, content) {
+    const procedures = [];
+    let namespace = '';
+    // Extract namespace from procedures() call
+    const namespaceMatch = content.match(/procedures\s*\(\s*['"]([^'"]+)['"]/);
+    if (namespaceMatch) {
+        namespace = namespaceMatch[1];
+    }
+    else {
+        // Derive from filename
+        const filename = basename(filePath, extname(filePath));
+        if (filename !== 'index') {
+            namespace = filename;
+        }
+    }
+    if (!namespace) {
+        return null;
+    }
+    // Extract procedure names using regex
+    const procedurePattern = /(\w+)\s*:\s*procedure\s*[.(]/g;
+    const matches = content.matchAll(procedurePattern);
+    for (const match of matches) {
+        const name = match[1];
+        // Determine type from naming convention
+        let type = 'unknown';
+        for (const [prefix, info] of Object.entries(METHOD_PREFIXES)) {
+            if (name.toLowerCase().startsWith(prefix)) {
+                type = info.type;
+                break;
+            }
+        }
+        // Check for explicit .query() or .mutation()
+        if (content.includes(`${name}`) && content.includes('.query(')) {
+            type = 'query';
+        }
+        else if (content.includes(`${name}`) && content.includes('.mutation(')) {
+            type = 'mutation';
+        }
+        procedures.push({
+            name,
+            type,
+            hasInput: content.includes('.input('),
+            hasOutput: content.includes('.output('),
+            hasGuard: content.includes('.guard('),
+            hasMiddleware: content.includes('.use('),
+        });
+    }
+    if (procedures.length === 0) {
+        return null;
+    }
+    return { namespace, procedures, filePath };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Convert parsed procedure to StaticProcedureInfo
+ */
+function toProcedureInfo(proc, namespace) {
+    const route = inferRestRoute(proc.name, namespace, proc.restOverride);
+    return {
+        name: proc.name,
+        namespace,
+        type: proc.type,
+        hasInputSchema: proc.hasInput,
+        hasOutputSchema: proc.hasOutput,
+        hasGuards: proc.hasGuard,
+        hasMiddleware: proc.hasMiddleware,
+        route,
+        restOverride: proc.restOverride,
+    };
+}
+/**
+ * Infer REST route from procedure name and namespace
+ */
+function inferRestRoute(procedureName, namespace, override) {
+    const basePath = `/api/${namespace}`;
+    // Use override if provided
+    if (override?.method && override?.path) {
+        return { method: override.method, path: override.path };
+    }
+    // Infer from naming convention
+    for (const [prefix, info] of Object.entries(METHOD_PREFIXES)) {
+        if (procedureName.toLowerCase().startsWith(prefix)) {
+            // Collection endpoints (no :id)
+            if (['list', 'find', 'search', 'create', 'add'].includes(prefix)) {
+                return {
+                    method: override?.method || info.method,
+                    path: override?.path || basePath,
+                };
+            }
+            // Resource endpoints (with :id)
+            return {
+                method: override?.method || info.method,
+                path: override?.path || `${basePath}/:id`,
+            };
+        }
+    }
+    // Default to GET collection
+    return { method: 'GET', path: basePath };
+}
+/**
+ * Check if file is a TypeScript file
+ */
+function isTypeScriptFile(filename) {
+    const ext = extname(filename);
+    return ['.ts', '.tsx', '.mts'].includes(ext);
+}
+/**
+ * Check if file should be excluded
+ */
+function isExcluded(filename) {
+    return (filename.startsWith('_') ||
+        filename.endsWith('.test.ts') ||
+        filename.endsWith('.spec.ts') ||
+        filename.endsWith('.d.ts') ||
+        filename === 'index.ts');
+}
+// ============================================================================
+// Formatting
+// ============================================================================
+/**
+ * Format static analysis result as text
+ */
+export function formatStaticAnalysisAsText(result) {
+    const lines = [
+        '# VeloxTS Procedures',
+        '',
+        `Total: ${result.procedures.length} procedures`,
+        `Namespaces: ${result.namespaces.join(', ') || 'none'}`,
+        `Files analyzed: ${result.files.length}`,
+        '',
+    ];
+    if (result.errors.length > 0) {
+        lines.push('## Analysis Notes');
+        for (const error of result.errors) {
+            lines.push(`- ${error}`);
+        }
+        lines.push('');
+    }
+    // Group by namespace
+    const byNamespace = new Map();
+    for (const proc of result.procedures) {
+        const list = byNamespace.get(proc.namespace) ?? [];
+        list.push(proc);
+        byNamespace.set(proc.namespace, list);
+    }
+    for (const [namespace, procs] of byNamespace) {
+        lines.push(`## ${namespace}`);
+        lines.push('');
+        for (const proc of procs) {
+            const type = proc.type === 'query' ? 'Q' : proc.type === 'mutation' ? 'M' : '?';
+            const route = proc.route ? ` -> ${proc.route.method} ${proc.route.path}` : '';
+            const guards = proc.hasGuards ? ' [guarded]' : '';
+            lines.push(`- [${type}] ${proc.name}${route}${guards}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/package.json

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