Universal MCP Server

Um servidor MCP universal com arquitetura modular de plugins.

GitHubExperimente este MCPPatrocinado

Documentação

Universal MCP Server

Servidor MCP universal com arquitetura modular de plugins. Permite adicionar facilmente novas ferramentas sem alterar o código principal.

⚙️ Instalação e configuração

1. Instalação de dependências

npm install

2. Configuração das variáveis de ambiente

Crie o arquivo .env na raiz do projeto com base no .env.example:

cp .env.example .env

Preencha as variáveis necessárias:

# 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

🏠 Desenvolvimento local

Para desenvolvimento local, use o Docker Compose com redirecionamento de porta:

# Запуск для разработки (с портом 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

O servidor estará disponível em http://localhost:8080 com endpoint SSE em /sse.

Alternativamente via npm (para desenvolvimento com hot reload):

npm run dev

🚀 Deploy em produção

No servidor, use o Docker Compose padrão:

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

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

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

🚀 Recursos

  • Arquitetura modular: adicione novas ferramentas simplesmente criando arquivos na pasta src/tools/
  • Carregamento automático: o sistema detecta e registra automaticamente todas as ferramentas
  • TypeScript: tipagem completa para segurança e conveniência no desenvolvimento
  • Suporte a Docker: configurações prontas de Docker e Docker Compose
  • Ferramentas prontas: 4 ferramentas integradas para diversas tarefas

Obtendo o token do bot do Telegram:

  1. Encontre o bot @BotFather no Telegram
  2. Envie o comando /newbot
  3. Siga as instruções para criar o bot
  4. Copie o token obtido

Obtendo o Chat ID:

  1. Inicie o seu bot
  2. Envie qualquer mensagem para ele
  3. Acesse o link: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  4. Encontre o valor de chat.id na resposta

Importante:

  • docker-compose.local.yml - para desenvolvimento local (porta 8080 exposta)
  • docker-compose.yml - para produção (sem redirecionamento de portas, com labels do Coolify)

🔧 Configuração do Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

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

Adicione a seguinte configuração:

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

Após alterar a configuração, reinicie o Claude Desktop.

🛠️ Criando novas ferramentas

Para adicionar uma nova ferramenta, crie um arquivo na pasta src/tools/ com o seguinte 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: 'Результат работы инструмента',
        }
    },
}

O sistema detectará e registrará automaticamente a nova ferramenta na próxima inicialização do servidor.

📁 Estrutura do projeto

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                   # Эта документация

📚 Ferramentas disponíveis

📱 sendTelegramMessage

Envio de mensagens para o Telegram

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

🌐 httpRequest

Execução de requisições HTTP para 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

Gerenciamento universal de blocos - funcionalidade 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

Criar uma nova tarefa (todo)

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

📖 readTodos

Ler tarefas (todos) - por ID, posição, busca ou listar todas

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

✏️ updateTodo

Atualizar uma tarefa 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

Excluir uma tarefa (todo) - exclusão suave

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

🤖 manageUnits

Gerenciamento universal de agentes (assistentes de IA) - funcionalidade 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   // Поиск по части имени агента
}

🔧 Detalhes técnicos

  • ES Modules: sistema moderno de módulos JavaScript
  • TypeScript: tipagem completa com compilação para ES2020
  • Express.js: servidor HTTP para o protocolo MCP
  • Server-Sent Events (SSE): para comunicação MCP
  • Zod: validação de esquemas para segurança de tipos
  • Carregamento automático: variáveis de ambiente via dotenv

🐳 Docker

O projeto inclui configurações Docker prontas:

  • Dockerfile - imagem para build da aplicação
  • docker-compose.yml - para deploy em produção (sem redirecionamento de portas)
  • docker-compose.local.yml - para desenvolvimento local (com porta 8080 exposta)

Desenvolvimento local:

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

Deploy em produção:

docker-compose up --build -d

🤝 Contribuindo com o projeto

  1. Faça um fork do repositório
  2. Crie uma branch para a nova funcionalidade
  3. Adicione suas ferramentas em src/tools/
  4. Teste as alterações
  5. Crie um Pull Request

📄 Licença

Licença MIT. Consulte o arquivo LICENSE para detalhes.

Criado com ❤️ para simplificar o trabalho com ferramentas MCP