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

✅ Nově implementováno:

✅ OAuth2 autentizace - kompletní Authorization Code flow s token management 🆕
✅ Autentizační middleware - všechny API endpointy jsou chráněny autentizací 🆕
✅ Token storage v paměti - singleton OAuth2Service s automatickým refreshem 🆕

🚧 Není implementováno (mimo scope):

🚧 Rate limiting - pro produkci by bylo vhodné
🚧 Další entity - Projekty, Úkoly, atd. (lze implementovat stejným způsobem)
🚧 Perzistentní token storage - tokeny jsou jen v RAM (doporučeno Redis/DB pro produkci)

🚀 Rychlé spuštění

1. Instalace

npm install

2. Konfigurace

OAuth2 autentizace (doporučeno) 🆕

# eWay-CRM API
EWAY_API_URL=https://trial.eway-crm.com/31994/API.svc
EWAY_USERNAME=api  # Nutné i pro OAuth2

# OAuth2 konfigurace
EWAY_CLIENT_ID=váš-client-id
EWAY_CLIENT_SECRET=váš-client-secret
EWAY_REDIRECT_URI=https://oauth.pstmn.io/v1/browser-callback

# 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

Legacy autentizace (fallback)

# eWay-CRM API konfigurace
EWAY_API_URL=https://trial.eway-crm.com/31994
EWAY_USERNAME=api
EWAY_PASSWORD=your-password-here  # Automaticky se hashuje na MD5
# nebo
# EWAY_PASSWORD_HASH=470AE7216203E23E1983EF1851E72947  # Již hashované heslo

# Zbytek stejný jako výše...

Automatická detekce:

Pokud jsou nastaveny EWAY_CLIENT_ID a EWAY_CLIENT_SECRET → použije OAuth2
Jinak pokud je nastaven EWAY_PASSWORD → použije legacy autentizaci
Aplikace automaticky detekuje správnou metodu

3. Build & Spuštění

npm run build
npm start

4. OAuth2 autorizace (pokud používáte OAuth2) 🆕

# Krok 1: Navštivte authorization endpoint v prohlížeči
http://localhost:3000/api/v1/oauth2/authorize

# Krok 2: Přihlaste se přes Azure AD
# Budete přesměrováni na eWay-CRM login

# Krok 3: Po úspěšné autorizaci budete přesměrováni zpět
# Tokeny se automaticky uloží do paměti serveru

# Krok 4: Nyní můžete volat API endpointy
curl http://localhost:3000/api/v1/companies

Poznámka: Tokeny jsou uloženy v paměti (RAM), po restartu serveru je potřeba znovu projít OAuth2 flow.

5. 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

OAuth2 autentizace 🆕

GET /api/v1/oauth2/authorize - Zahájit OAuth2 autorizaci
GET /api/v1/oauth2/callback - OAuth2 callback (automaticky voláno)
GET /api/v1/oauth2/status - Stav OAuth2 tokenu
POST /api/v1/oauth2/refresh - Manuální refresh tokenu
POST /api/v1/oauth2/logout - Odhlášení (vymazání tokenu)

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 🔒

🔒 = Vyžaduje autentizaci (OAuth2 nebo Legacy)

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 🔒

🔒 = Vyžaduje autentizaci | ⚠️ = Může být nestabilní na trial instanci

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/
│   ├── auth.middleware.ts      # OAuth2/Legacy autentizač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í:

✅ MCP Server - REST API server běžící na portu 3000
✅ eWay-CRM integrace - funkční připojení k trial.eway-crm.com
✅ Companies CRUD - kompletní správa společností 🔒
✅ Contacts CREATE/READ - vytváření a čtení kontaktů 🔒
✅ Deals CRUD - kompletní správa obchodů/příležitostí 🔒
✅ OAuth2 autentizace - Authorization Code flow s token management 🆕
✅ Autentizační middleware - ochrana všech API endpointů 🆕
✅ TypeScript - type-safe kód s DTO modely
✅ Error handling - structured error responses
✅ Logging - comprehensive logging with Winston
✅ Validation - Zod schemas pro všechny endpointy

🔒 = Všechny CRUD endpointy jsou nyní chráněny autentizací!

🏆 Bonus funkce:

✅ OAuth2 Authorization Code Flow - kompletní implementace 🆕
✅ In-memory token storage - OAuth2Service singleton s auto-refresh 🆕
✅ Autentizační middleware - requireAuth pro ochranu endpointů 🆕
✅ Dual auth support - OAuth2 + Legacy fallback 🆕
✅ 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:

Použít produkční eWay-CRM instanci s kompletnějšími daty
Implementovat perzistentní token storage (Redis/Database místo RAM)
Přidat rate limiting a monitoring
Optimalizovat Contact UPDATE/DELETE functionality
Zvážit implementaci session-based autentizace pro multi-user prostředí

🔐 Autentizace - Jak to funguje

OAuth2 Flow (doporučeno)

Iniciace autorizace:

   GET /api/v1/oauth2/authorize
   → Server vygeneruje authorization URL
   → Přesměrování na Azure AD login

Callback po přihlášení:

   GET /api/v1/oauth2/callback?code=...
   → Server vymění code za access_token a refresh_token
   → Tokeny se uloží do paměti (OAuth2Service)
   → Automatické přihlášení k eWay-CRM API

Použití API:

   GET /api/v1/companies
   → requireAuth middleware zkontroluje token
   → Automatický refresh pokud expiruje
   → Request pokračuje k API

Token Management v paměti

OAuth2Service (singleton):

Tokeny uloženy v RAM (storedToken: StoredToken | null)
Automatický refresh před expirací (60s buffer)
Metody: getValidAccessToken(), hasValidToken(), clearToken()

⚠️ Poznámka: Po restartu serveru je potřeba znovu projít OAuth2 flow

Autentizační middleware

Všechny API endpointy (Companies, Contacts, Deals) jsou chráněny requireAuth middleware:

// Automaticky kontroluje:
1. Platnost OAuth2 tokenu (pro OAuth2)
2. Připojení k eWay-CRM
3. Automatické přihlášení pokud je potřeba
4. Friendly error messages (401) s instrukcemi

Ewaycrm MCP Server

快速接入

详细介绍