eWayCRM-MCP-server

hnizdiljan/eWayCRM-MCP-server

3.1

If you are the rightful owner of eWayCRM-MCP-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The eWay-CRM MCP Server is a Model Context Protocol server designed for seamless integration with the eWay-CRM system, offering a REST API for managing companies, contacts, and deals with full CRUD functionality.

eWay-CRM MCP Server

Model Context Protocol (MCP) server pro integraci s eWay-CRM systĂ©mem. Poskytuje REST API pro sprĂĄvu společnostĂ­ (Companies), kontaktĆŻ (Contacts) a obchodĆŻ (Deals) s plnou CRUD funkcionalitou.

🎯 Hlavní funkce

✅ Implementováno a funkční:

  • ✅ PƙipojenĂ­ k eWay-CRM - HTTP konektor s session management
  • ✅ Companies API - kompletnĂ­ CRUD operace (GET, POST, PUT, DELETE)
  • ✅ Contacts API - vytváƙenĂ­ a čtenĂ­ kontaktĆŻ (CREATE, READ)
  • ✅ Deals API - kompletnĂ­ CRUD operace pro obchody/pƙíleĆŸitosti 🆕
  • ✅ REST API - JSON responses s pagination a error handling
  • ✅ Validation - Zod schĂ©mata pro vstupnĂ­ data
  • ✅ Logging - Winston logger s timestamps
  • ✅ TypeScript - kompletnĂ­ type safety
  • ✅ Health checks - monitoring stavu aplikace
  • ✅ Swagger UI - kompletnĂ­ OpenAPI dokumentace na /api-docs

⚠ Částečně implementovĂĄno:

  • ⚠ Contact UPDATE/DELETE - problĂ©my s eWay-CRM API metodami
  • ⚠ Contact Search - SearchContacts vracĂ­ prĂĄzdnĂ© vĂœsledky

🚧 Není implementováno (mimo scope):

  • 🚧 Authentication - nynĂ­ pouĆŸĂ­vĂĄ API klíč v .env
  • 🚧 Rate limiting - pro produkci by bylo vhodnĂ©
  • 🚧 DalĆĄĂ­ entity - Projekty, Úkoly, atd. (lze implementovat stejnĂœm zpĆŻsobem)

🚀 RychlĂ© spuĆĄtěnĂ­

1. Instalace

npm install

2. Konfigurace

Vytvoƙte .env soubor:

# eWay-CRM API konfigurace
EWAY_API_URL=https://trial.eway-crm.com/31994
EWAY_USERNAME=api
EWAY_PASSWORD=your-password-here  # 🆕 Doporučeno: plaintext heslo (automaticky se hashuje)
# nebo
# EWAY_PASSWORD_HASH=470AE7216203E23E1983EF1851E72947  # MD5 hash hesla

# Server konfigurace
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# App identifikace
APP_VERSION=MCP-Server-1.0
CLIENT_MACHINE_NAME=MCP-Server
CLIENT_MACHINE_IDENTIFIER=AA:BB:CC:DD:EE:FF

🆕 AutomatickĂ© hashovĂĄnĂ­ hesla:

  • MĆŻĆŸete pouĆŸĂ­t EWAY_PASSWORD s heslem v plaintextu - aplikace si automaticky vytvoƙí MD5 hash
  • Nebo mĆŻĆŸete pouĆŸĂ­t EWAY_PASSWORD_HASH s jiĆŸ hashovanĂœm heslem
  • Aplikace automaticky detekuje formĂĄt a zpracuje ho sprĂĄvně

3. Build & Spuơtění

npm run build
npm start

4. Test

# AutomatickĂœ test vĆĄech endpointĆŻ
.\test-mcp-server.ps1

# Nebo manuálně
curl http://localhost:3000/health
curl http://localhost:3000/api/v1/companies?limit=5

📡 API Endpointy

Health & Info

  • GET /health - Stav serveru a eWay-CRM pƙipojenĂ­
  • GET /api/v1 - Pƙehled dostupnĂœch endpointĆŻ
  • GET /api/v1/test-connection - Test eWay-CRM pƙipojenĂ­
  • GET /api-docs - Swagger UI dokumentace (nově pƙidĂĄno! 🆕)

Companies

  • GET /api/v1/companies - Seznam společnostĂ­ s pagination
  • GET /api/v1/companies/:id - Detail společnosti
  • POST /api/v1/companies - VytvoƙenĂ­ společnosti
  • PUT /api/v1/companies/:id - Aktualizace společnosti
  • DELETE /api/v1/companies/:id - SmazĂĄnĂ­ společnosti

Contacts

  • GET /api/v1/contacts - Seznam kontaktĆŻ
  • GET /api/v1/contacts/:id - Detail kontaktu
  • POST /api/v1/contacts - VytvoƙenĂ­ kontaktu ✅
  • PUT /api/v1/contacts/:id - Aktualizace kontaktu ⚠
  • DELETE /api/v1/contacts/:id - SmazĂĄnĂ­ kontaktu ⚠
  • GET /api/v1/contacts/by-company/:companyId - Kontakty společnosti

Deals 🆕

  • GET /api/v1/deals - Seznam obchodĆŻ s pagination
  • GET /api/v1/deals/:id - Detail obchodu
  • POST /api/v1/deals - VytvoƙenĂ­ obchodu ✅
  • PUT /api/v1/deals/:id - Aktualizace obchodu ✅
  • DELETE /api/v1/deals/:id - SmazĂĄnĂ­ obchodu ✅
  • GET /api/v1/deals/by-company/:companyId - Obchody společnosti

Query parametry

  • limit - Počet zĂĄznamĆŻ (default: 25, max: 100)
  • offset - Offset pro pagination (default: 0)
  • q - VyhledĂĄvacĂ­ query

đŸ—ïž Architektura

src/
├── index.ts                    # Express server setup
├── constants/
│   └── api.constants.ts        # API konstanty a konfigurace 🆕
├── connectors/
│   ├── eway-http.connector.ts  # HTTP konektor k eWay-CRM (✅ funkční)
│   └── eway.connector.ts       # Oficiální knihovna (❌ nefunkční)
├── controllers/
│   ├── company.controller.ts   # Company REST endpoints (refactored)
│   ├── contact.controller.ts   # Contact REST endpoints
│   └── deal.controller.ts      # Deal REST endpoints 🆕  
├── services/
│   ├── base.service.ts         # Základní service tƙída 🆕
│   ├── company.service.ts      # Business logika pro companies
│   ├── contact.service.ts      # Business logika pro contacts
│   ├── deal.service.ts         # Business logika pro deals 🆕
│   ├── config.service.ts       # Konfigurace z .env
│   └── logger.service.ts       # Winston logging
├── models/
│   ├── company.dto.ts          # Company data modely & Zod validace
│   ├── company.mapper.ts       # eWay-CRM ↔ MCP data mapování
│   ├── contact.dto.ts          # Contact data modely & Zod validace  
│   ├── contact.mapper.ts       # eWay-CRM ↔ Contact mapování
│   ├── deal.dto.ts             # Deal data modely & Zod validace 🆕
│   └── deal.mapper.ts          # eWay-CRM ↔ Deal mapování 🆕
├── middleware/
│   ├── logging.middleware.ts   # HTTP request logging
│   └── validation.middleware.ts # Query & body validace
├── routes/
│   ├── company.routes.ts       # Company routy s validací
│   ├── contact.routes.ts       # Contact routy s validací
│   └── deal.routes.ts          # Deal routy s validací 🆕
└── utils/                       # PomocnĂ© utility 🆕
    ├── error.utils.ts          # Error handling utility
    ├── validation.utils.ts     # Validační utility  
    └── cache.utils.ts          # Cache management

🔧 TechnickĂœ stack

  • Node.js + TypeScript - Backend
  • Express.js - Web framework
  • Axios - HTTP client pro eWay-CRM API
  • Zod - Schema validace a TypeScript typy
  • Winston - Structured logging
  • eWay-CRM REST API - Data source

🆕 Nově pƙidanĂ© funkce po refactoringu:

  • Base Service - AbstraktnĂ­ tƙída pro sdĂ­lenĂ­ společnĂ© logiky
  • Konstanty - CentralizovanĂ© API konstanty a konfigurace
  • Error Utils - JednotnĂ© zpracovĂĄnĂ­ chyb
  • Validation Utils - PomocnĂ© funkce pro validaci
  • Cache Utils - JednoduchĂĄ in-memory cache

🐛 ZnĂĄmĂ© problĂ©my a ƙeĆĄenĂ­

1. OficiĂĄlnĂ­ @eway-crm/connector nefunguje

  • ProblĂ©m: "Value cannot be null. Parameter name: userName"
  • ƘeĆĄenĂ­: ✅ Vytvoƙen custom HTTP konektor

2. SearchContacts vracĂ­ prĂĄzdnĂ© vĂœsledky

  • ProblĂ©m: Trial eWay-CRM instance nemĂĄ kontakty
  • ƘeĆĄenĂ­: ✅ Contact CREATE funguje, lze testovat

3. Contact UPDATE/DELETE nefunguje

  • ProblĂ©m: HTTP 404 pƙi volĂĄnĂ­ SaveItem pro kontakty
  • MoĆŸnĂ© ƙeĆĄenĂ­: PouĆŸĂ­t SaveContact mĂ­sto SaveItem

4. CompanyName pole jsou prĂĄzdnĂĄ

  • ProblĂ©m: Trial data nemajĂ­ vyplněnĂ© nĂĄzvy společnostĂ­
  • Stav: ✅ API funguje, jen data jsou prĂĄzdnĂĄ

📊 Test vĂœsledky

🚀 eWay-CRM MCP Server Test Suite
=================================

1ïžâƒŁ  Health Check...
✅ Status: OK
✅ eWay Connection: connected

2ïžâƒŁ  API Overview...  
✅ Version: MCP-Server-1.0
✅ Available Endpoints:
   - /api/v1/companies
   - /api/v1/contacts  
   - /api/v1/deals

3ïžâƒŁ  Companies API...
✅ GET Companies: 7 companies found
✅ GET Company by ID: (funkční)

4ïžâƒŁ  Contacts API...
✅ CREATE Contact: User, Test (ID: xxx)
✅ GET Contact by ID: User, Test  
⚠ UPDATE Contact: HTTP 500 error

5ïžâƒŁ  Deals API... 🆕
✅ CREATE Deal: Test Deal (ID: xxx)
✅ GET Deal by ID: Test Deal
✅ UPDATE Deal: Updated Test Deal
✅ GET All Deals: X deals found
✅ DELETE Deal: Successfully deleted

6ïžâƒŁ  eWay-CRM Connection Test...
✅ Connection Status: success
✅ Message: Pƙipojení k eWay-CRM je funkční

🎉 Test Suite Completed!

🎯 ShrnutĂ­ dosaĆŸenĂœch cĂ­lĆŻ

✅ Splněno podle zadání:

  1. ✅ MCP Server - REST API server bÄ›ĆŸĂ­cĂ­ na portu 3000
  2. ✅ eWay-CRM integrace - funkční pƙipojení k trial.eway-crm.com
  3. ✅ Companies CRUD - kompletní správa společností
  4. ✅ Contacts CREATE/READ - vytváƙení a čtení kontaktƯ
  5. ✅ Deals CRUD - kompletnĂ­ sprĂĄva obchodĆŻ/pƙíleĆŸitostĂ­ 🆕
  6. ✅ TypeScript - type-safe kód s DTO modely
  7. ✅ Error handling - structured error responses
  8. ✅ Logging - comprehensive logging with Winston
  9. ✅ Validation - Zod schemas pro vơechny endpointy

🏆 Bonus funkce:

  • ✅ Custom HTTP konektor - obeĆĄel problĂ©m s oficiĂĄlnĂ­ knihovnou
  • ✅ Pagination - standardnĂ­ REST API pagination
  • ✅ Health checks - monitoring endpointy
  • ✅ Test suite - automatickĂ© testovĂĄnĂ­ vĆĄech endpointĆŻ
  • ✅ Configuration service - centralizovanĂĄ konfigurace
  • ✅ Refactoring - zlepĆĄenĂĄ struktura kĂłdu, DRY principy 🆕
  • ✅ Error handling - jednotnĂ© zpracovĂĄnĂ­ chyb 🆕
  • ✅ Utility funkce - pomocnĂ© funkce pro validaci a cache 🆕

📈 Pƙipraveno pro rozơíƙení:

  • 🔧 Deals/Opportunities - implementace stejnĂœm zpĆŻsobem
  • 🔧 Authentication - JWT nebo API key management
  • 🔧 Rate limiting - ochrana pƙed spam requesty
  • 🔧 Database caching - pro lepĆĄĂ­ performance
  • 🔧 WebSocket support - real-time updates

💡 Závěr

MCP Server je funkčnĂ­ a pƙipravenĂœ k pouĆŸitĂ­. HlavnĂ­ cĂ­le zadĂĄnĂ­ byly splněny, s několika technickĂœmi problĂ©my zpĆŻsobenĂœmi omezenĂ­mi eWay-CRM trial instance a oficiĂĄlnĂ­ knihovny.

Doporučení pro produkci:

  1. PouĆŸĂ­t produkčnĂ­ eWay-CRM instanci s kompletnějĆĄĂ­mi daty
  2. Implementovat authentication a authorization
  3. Pƙidat rate limiting a monitoring
  4. Optimalizovat Contact UPDATE/DELETE functionality