Universal MCP Server

Un servidor MCP universal con una arquitectura de plugins modular.

GitHubPrueba este MCPPatrocinado

Documentación

Universal MCP Server

Servidor MCP universal con arquitectura modular de plugins. Permite añadir fácilmente nuevas herramientas sin modificar el código principal.

⚙️ Instalación y configuración

1. Instalación de dependencias

npm install

2. Configuración de variables de entorno

Cree el archivo .env en la raíz del proyecto basado en .env.example:

cp .env.example .env

Complete las variables necesarias:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# Server Configuration
PORT=8080

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/timelix

# Example for local development:
# DATABASE_URL=postgresql://postgres:password@localhost:5432/timelix

# Example for production with SSL:
# DATABASE_URL=postgresql://username:password@host:5432/database?sslmode=require

🏠 Desarrollo local

Para el desarrollo local, use Docker Compose con reenvío de puertos:

# Запуск для разработки (с портом 8080 наружу)
docker-compose -f docker-compose.local.yml up --build

# Запуск в фоне
docker-compose -f docker-compose.local.yml up --build -d

# Остановка
docker-compose -f docker-compose.local.yml down

El servidor estará disponible en http://localhost:8080 con endpoint SSE en /sse.

Alternativamente mediante npm (para desarrollo con recarga en caliente):

npm run dev

🚀 Despliegue en producción

En el servidor, use Docker Compose normal:

# На сервере - деплой в продакшн
docker-compose up --build -d

# Остановка
docker-compose down

# Обновление (пересборка)
docker-compose down
docker-compose up --build -d

🚀 Características

  • Arquitectura modular: añada nuevas herramientas simplemente creando archivos en la carpeta src/tools/
  • Carga automática: el sistema detecta y registra automáticamente todas las herramientas
  • TypeScript: tipado completo para seguridad y comodidad de desarrollo
  • Soporte Docker: configuraciones listas de Docker y Docker Compose
  • Herramientas listas: 4 herramientas integradas para diversas tareas

Obtención del token del bot de Telegram:

  1. Busque el bot @BotFather en Telegram
  2. Envíe el comando /newbot
  3. Siga las instrucciones para crear el bot
  4. Copie el token obtenido

Obtención del Chat ID:

  1. Inicie su bot
  2. Envíele cualquier mensaje
  3. Vaya al enlace: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  4. Encuentre el valor de chat.id en la respuesta

Importante:

  • docker-compose.local.yml - para desarrollo local (puerto 8080 hacia afuera)
  • docker-compose.yml - para producción (sin reenvío de puertos, con etiquetas de Coolify)

🔧 Configuración de Claude Desktop

Edite el archivo de configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Añada la siguiente configuración:

{
    "mcpServers": {
        "Universal MCP Server": {
            "url": "http://localhost:8080/sse"
        }
    }
}

Después de cambiar la configuración, reinicie Claude Desktop.

🛠️ Creación de nuevas herramientas

Para añadir una nueva herramienta, cree un archivo en la carpeta src/tools/ con el siguiente formato:

import { z } from 'zod'
import type { ToolDefinition } from '../types/tool.js'

export const toolDefinition: ToolDefinition = {
    name: 'myNewTool',
    description: 'Описание нового инструмента',
    inputSchema: z.object({
        parameter1: z.string().describe('Описание параметра'),
        parameter2: z.number().optional().describe('Опциональный параметр'),
    }),
    handler: async (args) => {
        // Логика инструмента
        return {
            success: true,
            result: 'Результат работы инструмента',
        }
    },
}

El sistema detectará y registrará automáticamente la nueva herramienta en el próximo inicio del servidor.

📁 Estructura del proyecto

Universal-MCP-Server/
├── src/
│   ├── tools/                   # 🔧 Папка с инструментами
│   │   ├── README.md           # Документация для разработчиков
│   │   ├── messages.ts         # Telegram сообщения
│   │   ├── http-requests.ts    # HTTP запросы
│   │   ├── file-operations.ts  # Файловые операции
│   │   └── database-tool.ts    # SQL запросы
│   ├── types/
│   │   └── tool.ts             # TypeScript интерфейсы
│   ├── utils/
│   │   └── tool-loader.ts      # Автозагрузчик инструментов
│   └── main.ts                 # Главный файл сервера
├── dist/                       # Скомпилированные файлы
├── docker-compose.yml          # Docker Compose для продакшена
├── docker-compose.local.yml    # Docker Compose для локальной разработки
├── Dockerfile                  # Docker образ
├── .env                        # Переменные окружения
├── .env.example               # Пример переменных окружения
└── README.md                   # Эта документация

📚 Herramientas disponibles

📱 sendTelegramMessage

Envío de mensajes a Telegram

// Параметры:
{
    text: string // Текст сообщения
}

🌐 httpRequest

Realización de solicitudes HTTP a APIs externas

// Параметры:
{
  url: string,           // URL для запроса
  method?: "GET" | "POST" | "PUT" | "DELETE", // HTTP метод (по умолчанию GET)
  headers?: object,      // HTTP заголовки
  body?: string         // Тело запроса (для POST/PUT)
}

🧮 calculator

Cálculos matemáticos

// Параметры:
{
    expression: string // Математическое выражение
}

🗂️ manageBlocks

Gestión universal de bloques - funcionalidad CRUD completa

// Параметры:
{
  operation: "list" | "create" | "update" | "delete" | "get", // Тип операции
  userId: string,        // ID пользователя
  blockId?: string,      // ID блока (для get, update, delete)
  parentId?: string,     // ID родительского блока
  type?: "text" | "todo" | "media" | "link" | "container" | "unit_ref" | "calendar" | "database", // Тип блока
  title?: string,        // Заголовок блока
  content?: object,      // Содержимое блока (JSON)
  style?: object,        // Стили блока (JSON)
  position?: object,     // Позиция блока (JSON)
  order?: number,        // Порядок блока
  archived?: boolean,    // Архивирован ли блок
  tags?: any[]          // Теги блока
}

✅ createTodo

Crear una nueva tarea (todo)

// Параметры:
{
  title: string,         // Название задачи (обязательно)
  description?: string,  // Описание задачи
  priority?: "high" | "medium" | "low", // Приоритет задачи
  dueDate?: string,      // Срок выполнения (ISO строка)
  tags?: string[],       // Теги задачи
  projectId?: string     // ID проекта
}

📖 readTodos

Leer tareas (todos) - por ID, posición, búsqueda o lista de todas

// Параметры:
{
  todoId?: string,       // Точный ID задачи (если известен)
  position?: number,     // Номер задачи в списке (1, 2, 3...)
  titleSearch?: string   // Поиск по части названия задачи
}

✏️ updateTodo

Actualizar una tarea existente (todo)

// Параметры:
{
  // Поиск задачи для обновления (один из параметров):
  todoId?: string,       // Точный ID задачи
  position?: number,     // Номер задачи в списке
  titleSearch?: string,  // Поиск по части названия

  // Поля для обновления:
  title?: string,        // Новое название задачи
  description?: string,  // Новое описание задачи
  completed?: boolean,   // Новый статус выполнения
  priority?: "high" | "medium" | "low", // Новый приоритет
  dueDate?: string,      // Новый срок выполнения
  tags?: string[],       // Новые теги задачи
  projectId?: string     // Новый ID проекта
}

🗑️ deleteTodo

Eliminar una tarea (todo) - eliminación suave

// Параметры:
{
  todoId?: string,       // Точный ID задачи (если известен)
  position?: number,     // Номер задачи в списке (1, 2, 3...)
  titleSearch?: string   // Поиск по части названия задачи
}

🤖 manageUnits

Gestión universal de agentes (asistentes de IA) - funcionalidad CRUD completa

// Параметры:
{
  operation: "list" | "create" | "update" | "delete" | "get", // Тип операции
  userId: string,        // ID пользователя
  unitId?: string,       // ID агента (для get, update, delete)
  name?: string,         // Имя агента
  description?: string,  // Описание агента
  avatar?: string,       // Аватар агента
  model?: string,        // Модель ИИ (например, gpt-4, claude-3)
  systemPrompt?: string, // Системный промпт агента
  tools?: any[],        // Инструменты агента
  isDefault?: boolean,   // Агент по умолчанию
  avatarUrl?: string,    // URL аватара агента
  unitType?: "assistant" | "human" | "timelix" | "system", // Тип агента
  nameSearch?: string   // Поиск по части имени агента
}

🔧 Características técnicas

  • ES Modules: sistema modular moderno de JavaScript
  • TypeScript: tipado completo con compilación a ES2020
  • Express.js: servidor HTTP para el protocolo MCP
  • Server-Sent Events (SSE): para la comunicación MCP
  • Zod: validación de esquemas para seguridad de tipos
  • Carga automática: variables de entorno mediante dotenv

🐳 Docker

El proyecto incluye configuraciones Docker listas:

  • Dockerfile - imagen para compilar la aplicación
  • docker-compose.yml - para despliegue en producción (sin reenvío de puertos)
  • docker-compose.local.yml - para desarrollo local (con puerto 8080 hacia afuera)

Desarrollo local:

docker-compose -f docker-compose.local.yml up --build -d

Despliegue en producción:

docker-compose up --build -d

🤝 Contribución al proyecto

  1. Haga un fork del repositorio
  2. Cree una rama para la nueva funcionalidad
  3. Añada sus herramientas en src/tools/
  4. Pruebe los cambios
  5. Cree un Pull Request

📄 Licencia

Licencia MIT. Consulte el archivo LICENSE para más detalles.

Creado con ❤️ para simplificar el trabajo con herramientas MCP