mcp-server by Desckars - MCP Server

🚀 Universal MCP Server Java\n\nUn servidor Model Context Protocol (MCP) universal implementado en Java usando Spring Boot, compatible con múltiples LLMs (OpenAI GPT, Google Gemini, Hugging Face) y bases de datos.\n\n## ✨ Características\n\n- ✅ Implementación completa del protocolo MCP 2024-11-05\n- 🤖 Compatible con múltiples LLMs (OpenAI, Gemini, Hugging Face)\n- 🗄️ Soporte para MongoDB y operaciones de base de datos\n- 🛠️ Herramientas universales extensibles y categorizadas\n- 📁 Gestión de recursos integrada con control de acceso\n- 🔌 Transporte stdio optimizado para múltiples clientes\n- 📊 Estadísticas y monitoreo en tiempo real\n- 🔒 Sistema de seguridad robusto con sandbox\n- 🏗️ Arquitectura modular Spring Boot\n- 🧪 Suite de pruebas completa\n\n## 📋 Requisitos\n\n- Java 17 o superior\n- Maven 3.8+\n- MongoDB (opcional, para herramientas de base de datos)\n- Spring Boot 3.2+\n\n## 🛠️ Instalación\n\n### 1. Clonar el repositorio\n`bash\ngit clone https://github.com/Desckars/mcp-server.git\ncd mcp-server\n`\n\n### 2. Configurar variables de entorno (opcional)\n`bash\n# Para habilitar LLMs\nexport OPENAI_API_KEY=\"tu-api-key-openai\"\nexport GEMINI_API_KEY=\"tu-api-key-gemini\"\nexport HUGGINGFACE_API_KEY=\"tu-api-key-huggingface\"\n\n# Para habilitar MongoDB\nexport MONGODB_URI=\"mongodb://localhost:27017/mcp_server\"\n`\n\n### 3. Compilar el proyecto\n`bash\nmvn clean compile\n`\n\n### 4. Ejecutar pruebas\n`bash\nmvn test\n`\n\n### 5. Empaquetar la aplicación\n`bash\nmvn package\n`\n\n## 🚀 Uso\n\n### Ejecución Local\n`bash\n# Usando Maven\nmvn spring-boot:run\n\n# Usando JAR compilado\njava -jar target/mcp-server-1.0.0.jar\n`\n\n### Integración con Claude Desktop\n\n1. Agregar al archivo de configuración de Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` en macOS):\n\n`json\n{\n \"mcpServers\": {\n \"universal-mcp-server-java\": {\n \"command\": \"java\",\n \"args\": [\"-jar\", \"/ruta/completa/al/mcp-server-1.0.0.jar\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"tu-api-key\",\n \"MONGODB_URI\": \"mongodb://localhost:27017\"\n }\n }\n }\n}\n`\n\n2. Reiniciar Claude Desktop\n\n### Integración con otros clientes MCP\n\nEl servidor es compatible con cualquier cliente que implemente el protocolo MCP 2024-11-05.\n\n## 🛠️ Herramientas Disponibles\n\n### 1. Calculator (calculadora)\nOperaciones matemáticas básicas y avanzadas:\n\n`json\n{\n \"name\": \"calculator\",\n \"arguments\": {\n \"operation\": \"add|subtract|multiply|divide|power|sqrt|sin|cos|tan|log|ln|abs|round|floor|ceil|sum|average|min|max|median|std_dev\",\n \"a\": 10,\n \"b\": 5,\n \"precision\": 6\n }\n}\n`\n\nEjemplos:\n- Operaciones básicas: `{\"operation\": \"add\", \"a\": 10, \"b\": 5}`\n- Funciones avanzadas: `{\"operation\": \"sin\", \"a\": 90}`\n- Operaciones con listas: `{\"operation\": \"average\", \"a\": [1, 2, 3, 4, 5]}`\n\n### 2. FileSystem (sistema de archivos)\nOperaciones seguras de archivos:\n\n`json\n{\n \"name\": \"filesystem\",\n \"arguments\": {\n \"action\": \"read|write|list|info|exists|delete|mkdir\",\n \"path\": \"ruta/relativa/archivo.txt\",\n \"content\": \"contenido del archivo\",\n \"encoding\": \"UTF-8\",\n \"recursive\": false\n }\n}\n`\n\nEjemplos:\n- Leer archivo: `{\"action\": \"read\", \"path\": \"data/example.txt\"}`\n- Escribir archivo: `{\"action\": \"write\", \"path\": \"output/result.txt\", \"content\": \"Hello World!\"}`\n- Listar directorio: `{\"action\": \"list\", \"path\": \".\", \"recursive\": true}`\n\n### 3. Database (base de datos) - Próximamente\nOperaciones con MongoDB:\n\n`json\n{\n \"name\": \"database\",\n \"arguments\": {\n \"operation\": \"find|insert|update|delete|aggregate\",\n \"collection\": \"users\",\n \"query\": {\"name\": \"John\"},\n \"data\": {\"age\": 30}\n }\n}\n`\n\n### 4. LLM Tools - Próximamente\nInteracción con diferentes LLMs:\n\n`json\n{\n \"name\": \"openai|gemini|huggingface\",\n \"arguments\": {\n \"prompt\": \"Explica la inteligencia artificial\",\n \"model\": \"gpt-3.5-turbo\",\n \"max_tokens\": 150\n }\n}\n`\n\n## 📁 Recursos Disponibles\n\n### Server Info\nInformación del servidor:\n`\nmcp://server/info\n`\n\n### Database Status\nEstado de la base de datos:\n`\nmcp://database/status\n`\n\n### File Resources\nArchivos del sistema:\n`\nfile:///workspace/archivo.txt\n`\n\n## 🔧 Configuración\n\n### Variables de Entorno\n\n| Variable | Descripción | Por defecto |\n|----------|-------------|-------------|\n| `OPENAI_API_KEY` | API Key de OpenAI | - |\n| `GEMINI_API_KEY` | API Key de Google Gemini | - |\n| `HUGGINGFACE_API_KEY` | API Key de Hugging Face | - |\n| `MONGODB_URI` | URI de conexión MongoDB | `mongodb://localhost:27017` |\n\n### Archivo de Configuración\n\nEditar `src/main/resources/application.properties`:\n\n`properties\n# Habilitar LLMs\nmcp.llm.enabled=true\nmcp.llm.openai.enabled=true\nmcp.llm.gemini.enabled=true\n\n# Habilitar base de datos\nmcp.database.enabled=true\nmcp.database.connection-string=${MONGODB_URI}\n\n# Configurar herramientas\nmcp.tools.filesystem.max-file-size=5242880\nmcp.tools.calculator.enable-advanced=true\n\n# Seguridad\nmcp.security.sandbox-enabled=true\nmcp.security.max-execution-time=10000\n`\n\n## 🏗️ Arquitectura\n\n\nsrc/main/java/com/desckars/mcpserver/\n├── UniversalMCPServerApplication.java # Aplicación principal\n├── config/\n│ └── MCPConfig.java # Configuración centralizada\n├── protocol/\n│ └── MCPProtocolHandler.java # Manejo del protocolo MCP\n├── transport/\n│ └── StdioTransport.java # Transporte stdio\n├── handlers/\n│ ├── ToolManager.java # Gestor de herramientas\n│ └── ResourceManager.java # Gestor de recursos\n├── tools/\n│ ├── CalculatorTool.java # Herramienta calculadora\n│ ├── FileSystemTool.java # Herramienta filesystem\n│ ├── DatabaseTool.java # Herramientas de BD\n│ └── llm/ # Herramientas LLM\n├── database/\n│ └── DatabaseService.java # Servicio de base de datos\n└── llm/\n └── LLMService.java # Servicio de LLMs\n\n\n## 🧪 Testing\n\n`bash\n# Ejecutar todas las pruebas\nmvn test\n\n# Ejecutar pruebas específicas\nmvn test -Dtest=CalculatorToolTest\n\n# Ejecutar con cobertura\nmvn test jacoco:report\n`\n\n## 📊 Monitoreo\n\nEl servidor incluye endpoints de monitoreo (si se habilita Actuator):\n\n`bash\n# Estado de salud\ncurl http://localhost:8080/actuator/health\n\n# Información del servidor\ncurl http://localhost:8080/actuator/info\n\n# Métricas\ncurl http://localhost:8080/actuator/metrics\n`\n\n## 🔒 Seguridad\n\n- Sandbox habilitado por defecto\n- Validación de rutas para operaciones de archivos\n- Límites de tiempo para ejecución de herramientas\n- Validación de entrada en todas las herramientas\n- Control de acceso a recursos sensibles\n\n## 🚧 Desarrollo\n\n### Agregar una nueva herramienta\n\n1. Implementar la interfaz `ToolManager.MCPTool`:\n\njava\npublic class MiHerramienta implements ToolManager.MCPTool {\n @Override\n public String getName() { return \"mi-herramienta\"; }\n \n @Override\n public String getDescription() { \n return \"Descripción de mi herramienta\"; \n }\n \n @Override\n public String getCategory() { return \"utilidades\"; }\n \n @Override\n public ObjectNode getInputSchema(ObjectMapper mapper) {\n // Definir schema JSON\n }\n \n @Override\n public String execute(JsonNode arguments, ObjectMapper mapper) throws Exception {\n // Implementar lógica de la herramienta\n }\n}\n\n\n2. Registrar en `UniversalMCPServerApplication.java`:\n\n`java\nMiHerramienta miHerramienta = new MiHerramienta();\ntoolManager.registerTool(miHerramienta);\n`\n\n### Agregar un nuevo recurso\n\n1. Implementar la interfaz `ResourceManager.MCPResource`:\n\n`java\npublic class MiRecurso implements ResourceManager.MCPResource {\n @Override\n public String getUri() { return \"mcp://mi-recurso\"; }\n \n @Override\n public String getName() { return \"Mi Recurso\"; }\n \n // ... otros métodos\n}\n`\n\n## 📈 Roadmap\n\n- [ ] v1.1: Herramientas de base de datos MongoDB completas\n- [ ] v1.2: Integración completa con LLMs (OpenAI, Gemini, Hugging Face)\n- [ ] v1.3: Soporte para prompts personalizados\n- [ ] v1.4: API REST complementaria\n- [ ] v1.5: Interfaz web de administración\n- [ ] v1.6: Soporte para más bases de datos (PostgreSQL, MySQL)\n- [ ] v1.7: Sistema de plugins externo\n- [ ] v2.0: Clustering y alta disponibilidad\n\n## 🤝 Contribuir\n\n1. Fork el repositorio\n2. Crear branch para tu feature (`git checkout -b feature/mi-feature`)\n3. Commit tus cambios (`git commit -m 'Agregar mi feature'`)\n4. Push al branch (`git push origin feature/mi-feature`)\n5. Crear Pull Request\n\n### Pautas de contribución\n\n- Seguir las convenciones de código Java\n- Escribir pruebas para nuevas funcionalidades\n- Documentar cambios en el README\n- Usar commits descriptivos con prefijos convencionales\n\n## 📄 Licencia\n\nEste proyecto está bajo la .\n\n## 🆘 Soporte\n\n- Issues: GitHub Issues\n- Documentación: Wiki del proyecto\n- Discusiones: GitHub Discussions\n\n## 🙏 Agradecimientos\n\n- Model Context Protocol por el protocolo base\n- Spring Boot por el framework\n- Jackson por el procesamiento JSON\n- La comunidad de desarrolladores por sus contribuciones\n\n---\n\nDesarrollado por Desckars con ❤️\n\n⭐ Si este proyecto te resulta útil, no olvides darle una estrella!"