{"_id":"@apprecio/apprecio-mcp-base","name":"@apprecio/apprecio-mcp-base","dist-tags":{"latest":"1.1.10"},"versions":{"1.1.10":{"name":"@apprecio/apprecio-mcp-base","version":"1.1.10","description":"Base package for creating Apprecio MCP servers with consistency","main":"dist/index.js","types":"dist/index.d.ts","type":"module","bin":{"apprecio-mcp":"dist/cli/index.js","mcp-generate":"cli/dist/generate-feature.js"},"scripts":{"build":"tsc -p ts.config.json && tsc-alias -p ts.config.json","start":"node dist/index.js","dev":"node -r ts.config-paths/register --loader tsx src/index.ts","prepare":"npm run build","test":"jest --coverage","build:cli":"tsc -p cli/ts.config.json","build:all":"npm run build && npm run build:cli","generate":"tsx cli/generate-feature.ts","generate:feature":"tsx cli/generate-feature.ts feature","generate:tool":"tsx cli/generate-feature.ts tool","cli:build":"npm run build:cli && npm link","prepublishOnly":"npm run build:all"},"keywords":["mcp","apprecio","server","base","typescript"],"author":{"name":"Apprecio Team"},"license":"MIT","peerDependencies":{"@modelcontextprotocol/sdk":"^1.23.0","express":"^5.1.0"},"dependencies":{"axios":"^1.9.0","chalk":"^5.3.0","commander":"^11.1.0","cors":"^2.8.5","dotenv":"^16.5.0","express-rate-limit":"^8.1.0","helmet":"^8.1.0","http-terminator":"^3.2.0","inquirer":"^9.2.12","mongoose":"^8.18.0","winston":"^3.11.0","zod":"^3.24.4","jsdom":"^26.1.0","dompurify":"^3.2.6","fs-extra":"^11.2.0"},"devDependencies":{"@types/cors":"^2.8.19","@types/express":"^5.0.1","@types/express-rate-limit":"^5.1.3","@types/fs-extra":"^11.0.4","@types/dompurify":"^3.0.5","@types/jsdom":"^21.1.7","@types/helmet":"^0.0.48","@types/inquirer":"^9.0.7","@types/jest":"^30.0.0","@types/node":"^22.14.1","jest":"^30.0.5","ts-jest":"^29.4.1","tsc-alias":"^1.8.16","typescript":"^5.9.2"},"_id":"@apprecio/apprecio-mcp-base@1.1.10","gitHead":"9c1ffa059bb6d5c4de89a75e13b6730661a27d66","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-E3hQ5dA4lGR11+OMEVOoPsyJV5MrgHP04CGNr4u8rgvraUCRcx5Z02/Xu+oU24GXJON9b/599LkYvMByqDmPsQ==","shasum":"40c552927475c2daad142dc6911707c41cfcc82f","tarball":"https://registry.npmjs.org/@apprecio/apprecio-mcp-base/-/apprecio-mcp-base-1.1.10.tgz","fileCount":75,"unpackedSize":177223,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDtfT8Gkzioy1zo1IuU0NviyUV9S4c9BepNClVWgQ3xPgIgBPk4trBKfFj8IyMydyz4X5yR9MKkeO+ox5x6W0FJU0U="}]},"_npmUser":{"name":"apprecio","email":"jleiva@dcanje.com"},"directories":{},"maintainers":[{"name":"apprecio","email":"jleiva@dcanje.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/apprecio-mcp-base_1.1.10_1767033204758_0.2943265724612536"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-29T18:33:24.637Z","1.1.10":"2025-12-29T18:33:24.933Z","modified":"2025-12-29T18:33:25.222Z"},"maintainers":[{"name":"apprecio","email":"jleiva@dcanje.com"}],"description":"Base package for creating Apprecio MCP servers with consistency","keywords":["mcp","apprecio","server","base","typescript"],"author":{"name":"Apprecio Team"},"license":"MIT","readme":"# apprecio-mcp-base\n\nBase package para crear servidores MCP (Model Context Protocol) de Apprecio con consistencia y reutilización de código.\n\n## 🚀 Características\n\n- **Servidor Base Abstracto**: Clase `McpBaseServer` que encapsula toda la lógica común\n- **Sistema de Features**: Arquitectura modular con `FeatureModule`\n- **Configuración Centralizada**: Sistema de configuración con validación Zod\n- **Logger Unificado**: Winston logger con niveles configurables y rotación de archivos\n- **Middlewares Reutilizables**: Autenticación Bearer Token, Rate Limiting, CORS, Helmet\n- **Conectores Database**: MongoDB y Redis pre-configurados\n- **Port Management**: Búsqueda automática de puertos disponibles\n- **Graceful Shutdown**: Manejo automático de señales SIGINT/SIGTERM\n- **TypeScript First**: Completamente tipado con soporte para path aliases\n- **CLI Generator**: Generador de proyectos y features automático\n\n## 📦 Instalación\n\n```bash\nnpm install apprecio-mcp-base\n# o\npnpm add apprecio-mcp-base\n```\n\n## 🎯 Quick Start\n\n### Opción 1: Usar el CLI (Recomendado)\n\n```bash\n# 1. Setup global link (una vez)\ncd apprecio-mcp-base\nnpm run build\nnpm link\n\n# 2. Generar nuevo proyecto\nmcp-generate init\n\n# Responder wizard:\n# - Nombre del proyecto\n# - Ruta\n# - Usar MongoDB (sí/no)\n# - Base URL de tu API\n# ¿Instalar dependencias? Yes\n# ¿Linkear apprecio-mcp-base? Yes\n\n# 3. Ejecutar\ncd my-project\nnpm run dev\n```\n\n### Opción 2: Manual\n\n```typescript\nimport { \n    McpBaseServer, \n    createServer, \n    findAvailablePort,\n    createMongoDBConnector,\n    logger,\n    type MongoDBConnector\n} from 'apprecio-mcp-base';\n\nclass MyMcpServer extends McpBaseServer {\n    private dbConnector?: MongoDBConnector;\n\n    protected async registerFeatures(): Promise<void> {\n        // Registrar tus features\n        this.registerFeature('users', usersFeature);\n    }\n\n    protected async onBeforeStart(): Promise<void> {\n        const mongoUri = this.config.mongodbUri;\n        if (mongoUri) {\n            this.dbConnector = createMongoDBConnector(mongoUri);\n            await this.dbConnector.connect();\n        }\n    }\n\n    protected async onBeforeShutdown(): Promise<void> {\n        if (this.dbConnector) {\n            await this.dbConnector.disconnect();\n        }\n    }\n}\n\nasync function main() {\n    const server = new MyMcpServer({\n        name: 'my-mcp-server',\n        version: '1.0.0',\n    });\n\n    const port = await findAvailablePort(server.getConfig().ssePort);\n    const { httpServer, transport } = await createServer(port);\n    \n    await server.start(httpServer, transport, port);\n}\n\nmain();\n```\n\n## 🔧 CLI Generator\n\nEl paquete incluye un CLI para generar proyectos y features automáticamente.\n\n### Comandos Disponibles\n\n```bash\n# Generar nuevo proyecto\nmcp-generate init\n\n# Generar nueva feature\nmcp-generate feature\n\n# Help\nmcp-generate --help\n```\n\n### Generar Proyecto\n\n```bash\nmcp-generate init\n\n# Wizard interactivo:\n? Nombre del proyecto: my-awesome-mcp\n? Ruta: ./my-awesome-mcp\n? Descripción: My awesome MCP server\n? Autor: Tu Nombre\n? ¿Usar MongoDB? No\n? Base URL de tu API: https://api.example.com\n? ¿Instalar dependencias? Yes\n? ¿Linkear apprecio-mcp-base? Yes\n\n# Genera:\n# ✅ Estructura completa del proyecto\n# ✅ Archivos base (main.ts, services, utils)\n# ✅ Scripts de setup (post-install.sh, check-permissions.sh)\n# ✅ Configuración (.env, tsconfig.json, package.json)\n# ✅ README.md completo\n```\n\n### Generar Feature\n\n```bash\ncd my-project\nnpm run generate\n\n# Wizard interactivo:\n? Nombre de la feature: users\n? Descripción: Manage users\n? ¿Necesita service? Yes\n? Tipo de service: API Client\n? Tools: [x] list, [x] get, [x] create, [x] update\n? Nombre de la entidad: user\n? ¿Auto-registrar en main.ts? Yes\n\n# Genera:\n# ✅ users.feature.ts - Feature module con tools\n# ✅ users.service.ts - Business logic\n# ✅ users.validation.ts - Zod schemas\n# ✅ Actualiza main.ts automáticamente\n```\n\n## 📚 Sistema de Features\n\n### Crear un Feature Module\n\n```typescript\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { logger, type FeatureModule } from 'apprecio-mcp-base';\n\nexport const usersFeature: FeatureModule = {\n    name: 'users',\n\n    register(mcpServer: McpServer): void {\n        // Registrar tool\n        mcpServer.tool(\n            'list_users',\n            'List all users',\n            {\n                page: { type: 'number', description: 'Page number' },\n                limit: { type: 'number', description: 'Items per page' }\n            },\n            async (args, extra) => {\n                // Extraer token de auth\n                const req = extra as any;\n                const token = req?.requestInfo?.headers?.authorization;\n                \n                // Tu lógica aquí\n                const users = await userService.list(args);\n                \n                return {\n                    content: [{\n                        type: 'text',\n                        text: JSON.stringify(users)\n                    }]\n                };\n            }\n        );\n\n        logger.info('Users feature registered');\n    },\n\n    async initialize(): Promise<void> {\n        logger.info('Users feature initialized');\n    },\n\n    async cleanup(): Promise<void> {\n        logger.info('Users feature cleaned up');\n    }\n};\n```\n\n### Registrar Features\n\n```typescript\nclass MyMcpServer extends McpBaseServer {\n    protected async registerFeatures(): Promise<void> {\n        this.registerFeature('users', usersFeature);\n        this.registerFeature('products', productsFeature);\n        this.registerFeature('orders', ordersFeature);\n        \n        logger.info('All features registered');\n    }\n}\n```\n\n## 🔐 Autenticación\n\n### Middleware de Autenticación\n\n```typescript\nimport { createAuthMiddleware } from 'apprecio-mcp-base';\n\n// Crear middleware\nconst auth = createAuthMiddleware({\n    apiKey: process.env.API_KEY,\n    enabled: process.env.AUTH_ENABLED !== 'false'\n});\n\n// Usar en Express\napp.get('/health', handler); // Público\n\napp.use('/sse', auth); // Protegido\napp.post('/sse', handler);\n```\n\n### Usar Token en Features\n\n```typescript\nmcpServer.tool('secure_action', schema, async (args, extra) => {\n    // Extraer token\n    const req = extra as any;\n    const token = req?.requestInfo?.headers?.authorization;\n    \n    if (!token) {\n        throw new Error('Unauthorized');\n    }\n    \n    // Validar y usar token\n    const isValid = await validateToken(token);\n    if (!isValid) {\n        throw new Error('Invalid token');\n    }\n    \n    // Procesar acción\n    return { content: [{ type: 'text', text: 'Success' }] };\n});\n```\n\n## 📝 Configuración\n\n### Variables de Entorno\n\n```env\n# Authentication\nAPI_KEY=your-secret-key-here\nAUTH_ENABLED=false\n\n# Database (opcional)\nMONGODB_URI=mongodb://localhost:27017/mydb\n\n# Server\nMCP_SSE_PORT=3200\n\n# Timeouts (ms)\nMCP_TIMEOUT=180000\nSSE_TIMEOUT=1800000\n\n# Logging\nLOG_LEVEL=info\n\n# CORS\nCORS_ALLOW_ORIGIN=*\n\n# Rate Limiting\nRATE_LIMIT_WINDOW_MS=900000\nRATE_LIMIT_MAX_REQUESTS=100\n```\n\n### Acceder a Configuración\n\n```typescript\nclass MyMcpServer extends McpBaseServer {\n    protected async registerFeatures(): Promise<void> {\n        // Acceder a config\n        const config = this.config;\n        \n        logger.info(`Server port: ${config.ssePort}`);\n        logger.info(`MongoDB URI: ${config.mongodbUri}`);\n        logger.info(`Log level: ${config.logLevel}`);\n    }\n}\n```\n\n## 🗄️ Database Connectors\n\n### MongoDB\n\n```typescript\nimport { createMongoDBConnector } from 'apprecio-mcp-base';\n\n// Crear conector\nconst db = createMongoDBConnector('mongodb://localhost:27017/db');\n\n// Conectar\nawait db.connect();\n\n// Usar mongoose\nconst connection = db.getConnection();\nconst User = connection.model('User', userSchema);\n\n// Desconectar\nawait db.disconnect();\n```\n\n### Redis\n\n```typescript\nimport { createRedisConnector } from 'apprecio-mcp-base';\n\n// Crear conector\nconst redis = createRedisConnector('redis://localhost:6379');\n\n// Conectar\nawait redis.connect();\n\n// Usar\nconst client = redis.getClient();\nawait client.set('key', 'value');\nconst value = await client.get('key');\n\n// Desconectar\nawait redis.disconnect();\n```\n\n## 📊 Logger\n\n```typescript\nimport { logger, createChildLogger, setLogLevel } from 'apprecio-mcp-base';\n\n// Uso básico\nlogger.info('Server started');\nlogger.error('Error occurred', error);\nlogger.debug('Debug info', { metadata });\nlogger.warn('Warning message');\n\n// Logger con contexto\nconst featureLogger = createChildLogger('UsersFeature');\nfeatureLogger.info('User created', { userId: 123 });\n\n// Cambiar nivel dinámicamente\nsetLogLevel('debug');\n```\n\n## 🛠️ Desarrollo\n\n### Estructura del Proyecto\n\n```\napprecio-mcp-base/\n├── cli/                      # CLI generator\n│   ├── generators/\n│   │   ├── init-generator.ts       # Generador de proyectos\n│   │   ├── feature-generator.ts    # Generador de features\n│   │   ├── service-generator.ts    # Generador de services\n│   │   ├── router-generator.ts     # Generador de routers\n│   │   └── main-updater.ts         # Actualizador de main.ts\n│   ├── templates/\n│   │   ├── post-install.sh\n│   │   └── check-permissions.sh\n│   └── generate-feature.ts   # Entry point del CLI\n├── src/\n│   ├── core/                 # Núcleo del framework\n│   │   ├── McpBaseServer.ts  # Clase base\n│   │   ├── config.ts         # Sistema de configuración\n│   │   ├── logger.ts         # Logger centralizado\n│   │   └── types.ts          # Tipos compartidos\n│   ├── middleware/           # Middlewares Express\n│   │   ├── auth.ts           # Autenticación Bearer\n│   │   ├── rate-limit.ts     # Rate limiting\n│   │   └── cors.ts           # CORS config\n│   ├── database/             # Conectores DB\n│   │   ├── mongodb.ts\n│   │   └── redis.ts\n│   ├── server/               # Server builders\n│   │   └── express.ts\n│   ├── utils/                # Utilidades\n│   │   ├── port.ts           # Port finder\n│   │   └── shutdown.ts       # Graceful shutdown\n│   └── index.ts              # Exports principales\n├── examples/                 # Ejemplos de uso\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n### Scripts Disponibles\n\n```bash\n# Build del paquete\nnpm run build\n\n# Build con watch\nnpm run build:watch\n\n# Build CLI\nnpm run build:cli\n\n# Build todo\nnpm run build:all\n\n# Link global\nnpm link\n\n# Generate feature (si estás en un proyecto)\nnpm run generate\n```\n\n### Desarrollo del CLI\n\n```bash\n# Build CLI\nnpm run build:cli\n\n# Link globalmente\nnpm link\n\n# Usar en cualquier lugar\nmcp-generate init\n```\n\n## 🚀 Setup para Desarrollo\n\n### 1. Setup Inicial\n\n```bash\n# Clone repo\ngit clone https://github.com/apprecio/apprecio-mcp-base.git\ncd apprecio-mcp-base\n\n# Instalar dependencias\nnpm install\n\n# Build\nnpm run build\n\n# Link global\nnpm link\n```\n\n### 2. Crear Proyecto de Prueba\n\n```bash\n# Generar proyecto\nmcp-generate init\n\n# Configurar\ncd my-test-project\nnpm install\nnpm link apprecio-mcp-base\n\n# Ejecutar\nnpm run dev\n```\n\n### 3. Desarrollo Iterativo\n\n```bash\n# Terminal 1: Watch mode en apprecio-mcp-base\ncd apprecio-mcp-base\nnpm run build:watch\n\n# Terminal 2: Tu proyecto\ncd my-test-project\nnpm run dev\n\n# Los cambios en apprecio-mcp-base se reflejan automáticamente\n```\n\n## 📚 API Reference\n\n### McpBaseServer\n\n```typescript\nabstract class McpBaseServer {\n    constructor(options: ServerOptions)\n    \n    // Métodos abstractos\n    protected abstract registerFeatures(): Promise<void>\n    \n    // Hooks opcionales\n    protected async onBeforeStart?(): Promise<void>\n    protected async onBeforeShutdown?(): Promise<void>\n    \n    // Métodos públicos\n    getMcpServer(): McpServer\n    getConfig(): BaseConfig\n    getFeatures(): Map<string, FeatureModule>\n    \n    // Lifecycle\n    async start(httpServer: HttpServer, transport: Transport, port: number): Promise<void>\n}\n```\n\n### FeatureModule\n\n```typescript\ninterface FeatureModule {\n    name: string;\n    register(mcpServer: McpServer): void;\n    initialize?(): Promise<void>;\n    cleanup?(): Promise<void>;\n}\n```\n\n### BaseConfig\n\n```typescript\nclass BaseConfig {\n    get apiKey(): string\n    get mongodbUri(): string | undefined\n    get ssePort(): number\n    get logLevel(): 'debug' | 'info' | 'warn' | 'error'\n    get mcpTimeout(): number\n    get sseTimeout(): number\n    get corsAllowOrigin(): string\n    get rateLimitWindowMs(): number\n    get rateLimitMaxRequests(): number\n}\n```\n\n## 🆘 Troubleshooting\n\n### Error: Cannot find module 'apprecio-mcp-base'\n\n```bash\n# Verificar link global\nnpm list -g apprecio-mcp-base --depth=0\n\n# Si no está linkeado:\ncd apprecio-mcp-base\nnpm run build\nnpm link\n\n# En tu proyecto:\nnpm link apprecio-mcp-base\n```\n\n### Error: EACCES (Permission Denied)\n\n```bash\n# En el proyecto generado\n./check-permissions.sh\n\n# Arreglar permisos\nsudo chown -R $(whoami) .\nchmod -R 755 .\n```\n\n### Error: npm cache EACCES\n\n```bash\n# Arreglar caché de npm\nsudo chown -R $(whoami) ~/.npm\nnpm cache clean --force\nnpm install\n```\n\n### Cambios no se reflejan\n\n```bash\n# Rebuild apprecio-mcp-base\ncd apprecio-mcp-base\nnpm run build\n\n# Los proyectos linkeados ven cambios automáticamente\n```\n\n## 💡 Best Practices\n\n### ✅ DO:\n\n- Usa el CLI para generar proyectos y features\n- Mantén features pequeños y enfocados\n- Usa el logger en lugar de console.log\n- Implementa cleanup en features con recursos\n- Usa TypeScript strict mode\n- Valida inputs con Zod\n\n### ❌ DON'T:\n\n- No uses `sudo npm install`\n- No modifies archivos generados manualmente\n- No uses console.log en producción\n- No olvides implementar cleanup\n- No hardcodees configuración\n\n## 🎯 Ejemplos\n\nVer `examples/` para:\n\n- Servidor MCP simple\n- Servidor con MongoDB\n- Servidor con múltiples features\n- Feature con autenticación\n- Feature con validación Zod\n\n## 📖 Documentación\n\n- [Model Context Protocol](https://modelcontextprotocol.io) - Especificación MCP\n- [TypeScript](https://www.typescriptlang.org/) - TypeScript docs\n- [Winston](https://github.com/winstonjs/winston) - Logger docs\n- [Zod](https://zod.dev/) - Validation docs\n\n## 🤝 Contribuir\n\n1. Fork el proyecto\n2. Crea una branch: `git checkout -b feature/amazing-feature`\n3. Commit cambios: `git commit -m 'Add amazing feature'`\n4. Push: `git push origin feature/amazing-feature`\n5. Abre un Pull Request\n\n## 📄 Licencia\n\nMIT © Apprecio\n\n## 🔗 Links\n\n- [GitHub](https://github.com/apprecio/apprecio-mcp-base)\n- [npm](https://www.npmjs.com/package/apprecio-mcp-base)\n- [Issues](https://github.com/apprecio/apprecio-mcp-base/issues)\n\n---\n\n**Hecho con ❤️ por el equipo de Apprecio**","readmeFilename":"README.md","_rev":"1-40ae6ddf09dafd81261b4c1135c86b68"}