feat(modules-local): add dynamic loading of local modules and update .gitignore

.gitignore

@@ -62,6 +62,9 @@ facturascripts/
 .claude/
 /mysql/
 
+# Módulos locales del usuario (nunca se suben al repositorio)
+src/modules-local/
+
 # OpenAPI files - keep the current one, exclude the old one
 /facturascripts.openapi.json
 # Keep the current OpenAPI definition file

src/index.ts

@@ -110,6 +110,8 @@ import { tarifasToolDefinition, tarifasToolImplementation } from './modules/conf
 import { totalModelesToolDefinition, totalModelesToolImplementation } from './modules/system/totalmodeles/index.js';
 import { variantesToolDefinition, variantesToolImplementation } from './modules/core-business/variantes/index.js';
 import { workEventesToolDefinition, workEventesToolImplementation } from './modules/system/workeventes/index.js';
+import { loadLocalModules } from './local-loader.js';
+import type { LoadedLocalModule } from './types/local-module.js';
 
 const server = new Server(
   {
@@ -203,6 +205,8 @@ const subcuentasResource = new SubcuentasResource(fsClient);
 const tarifasResource = new TarifasResource(fsClient);
 const totalModelesResource = new TotalModelesResource(fsClient);
 const workEventesResource = new WorkEventesResource(fsClient);
+// Módulos locales — se cargan en runServer() antes de conectar
+let localModules: LoadedLocalModule[] = [];
 
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
@@ -2095,6 +2099,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
         },
       },
+      // Módulos locales (cargados dinámicamente desde src/modules-local/)
+      ...localModules.map(m => m.toolDefinition),
     ],
   };
 });
@@ -2570,6 +2576,13 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
         description: 'Lista de eventos y trabajos del sistema para monitoreo y seguimiento de procesos',
         mimeType: 'application/json',
       },
+      // Módulos locales (cargados dinámicamente desde src/modules-local/)
+      ...localModules.map(m => ({
+        uri: `facturascripts://${m.resourceName}`,
+        name: `FacturaScripts Local — ${m.resourceName}`,
+        description: m.resourceDescription,
+        mimeType: 'application/json',
+      })),
     ],
   };
 });
@@ -2889,6 +2902,13 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     return await workEventesResource.getResource(uri);
   }
 
+  // Módulos locales
+  for (const localModule of localModules) {
+    if (localModule.instance.matchesUri(uri)) {
+      return await localModule.instance.getResource(uri);
+    }
+  }
+
   throw new Error(`Resource not found: ${uri}`);
 });
 
@@ -3836,8 +3856,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
-      default:
+
+      default: {
+        // Módulos locales
+        const localMod = localModules.find(m => m.toolDefinition.name === name);
+        if (localMod) {
+          const uri = buildUri(localMod.resourceName);
+          const result = await localMod.instance.getResource(uri);
+          return {
+            content: [
+              {
+                type: 'text',
+                text: (result as any).contents?.[0]?.text || 'No data',
+              },
+            ],
+          };
+        }
         throw new Error(`Unknown tool: ${name}`);
+      }
     }
   } catch (error) {
     return {
@@ -3853,6 +3889,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 async function runServer() {
+  localModules = await loadLocalModules(fsClient);
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('MCP FacturaScripts server running on stdio');

src/local-loader.ts

@@ -0,0 +1,81 @@
+import { readdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { FacturaScriptsClient } from './fs/client.js';
+import type { LocalModuleConfig, LoadedLocalModule } from './types/local-module.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Carga dinámicamente todos los módulos locales de la carpeta modules-local/.
+ *
+ * Cada subcarpeta de modules-local/ debe tener un index.js (compilado desde index.ts)
+ * que exporte `moduleConfig` siguiendo la interfaz LocalModuleConfig.
+ *
+ * La carpeta src/modules-local/ está en .gitignore, por lo que los módulos
+ * locales nunca se subirán al repositorio.
+ */
+export async function loadLocalModules(fsClient: FacturaScriptsClient): Promise<LoadedLocalModule[]> {
+  const localModulesDir = join(__dirname, 'modules-local');
+
+  if (!existsSync(localModulesDir)) {
+    return [];
+  }
+
+  const loaded: LoadedLocalModule[] = [];
+
+  let entries: import('fs').Dirent<string>[];
+  try {
+    entries = readdirSync(localModulesDir, { withFileTypes: true, encoding: 'utf8' });
+  } catch {
+    console.error('[local-loader] No se pudo leer el directorio modules-local/');
+    return [];
+  }
+
+  const dirs = entries.filter(e => e.isDirectory());
+
+  for (const dir of dirs) {
+    const indexPath = join(localModulesDir, dir.name as string, 'index.js');
+
+    if (!existsSync(indexPath)) {
+      console.error(`[local-loader] Módulo "${dir.name}" no tiene index.js compilado — ejecuta npm run build`);
+      continue;
+    }
+
+    try {
+      const moduleUrl = pathToFileURL(indexPath).href;
+      const mod = await import(moduleUrl);
+      const config: LocalModuleConfig = mod.moduleConfig;
+
+      if (!config) {
+        console.error(`[local-loader] Módulo "${dir.name}" no exporta "moduleConfig"`);
+        continue;
+      }
+
+      if (!config.resourceName || !config.Resource || !config.toolDefinition) {
+        console.error(`[local-loader] Módulo "${dir.name}": moduleConfig incompleto (faltan resourceName, Resource o toolDefinition)`);
+        continue;
+      }
+
+      const instance = new config.Resource(fsClient);
+
+      loaded.push({
+        instance,
+        toolDefinition: config.toolDefinition,
+        resourceName: config.resourceName,
+        resourceDescription: config.resourceDescription ?? '',
+      });
+
+      console.error(`[local-loader] ✓ Módulo local cargado: ${dir.name} (tool: ${config.toolDefinition.name})`);
+    } catch (err) {
+      console.error(`[local-loader] Error al cargar módulo "${dir.name}":`, err);
+    }
+  }
+
+  if (loaded.length > 0) {
+    console.error(`[local-loader] ${loaded.length} módulo(s) local(es) cargado(s)`);
+  }
+
+  return loaded;
+}

src/types/local-module.ts

@@ -0,0 +1,39 @@
+import { FacturaScriptsClient } from '../fs/client.js';
+
+/**
+ * Interfaz que debe exportar cada módulo local como `moduleConfig`.
+ *
+ * Ejemplo de uso en src/modules-local/mi-modulo/index.ts:
+ *
+ *   import { MiResource } from './resource.js';
+ *   import { toolDefinition } from './tool.js';
+ *   import type { LocalModuleConfig } from '../../types/local-module.js';
+ *
+ *   export const moduleConfig: LocalModuleConfig = {
+ *     resourceName: 'mi-recurso',
+ *     resourceDescription: 'Descripción de mi recurso local',
+ *     Resource: MiResource,
+ *     toolDefinition,
+ *   };
+ */
+export interface LocalModuleConfig {
+  /** Nombre del recurso, usado en la URI: facturascripts://{resourceName} */
+  resourceName: string;
+  /** Descripción visible en el listado de recursos MCP */
+  resourceDescription: string;
+  /** Clase del recurso. Debe implementar getResource(uri) y matchesUri(uri) */
+  Resource: new (client: FacturaScriptsClient) => any;
+  /** Definición de la herramienta MCP (name, description, inputSchema) */
+  toolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: object;
+  };
+}
+
+export interface LoadedLocalModule {
+  instance: any;
+  toolDefinition: LocalModuleConfig['toolDefinition'];
+  resourceName: string;
+  resourceDescription: string;
+}