Огляд

MCP Сервер Mapfolio - це сервер Model Context Protocol (MCP), який дозволяє AI-асистентам та іншим клієнтам, сумісним з MCP, взаємодіяти з даними та операціями Mapfolio. Він забезпечує програмний доступ до компаній, проектів, користувачів, профілів LinkedIn та адміністративних функцій.

Що таке MCP?

Model Context Protocol (MCP) - це відкритий протокол, який дозволяє AI-асистентам безпечно отримувати доступ до зовнішніх джерел даних та інструментів. MCP сервери надають можливості через стандартизований інтерфейс, дозволяючи AI-асистентам:

Запитувати та отримувати дані
Виконувати операції
Отримувати доступ до ресурсів
Інтегруватися з зовнішніми системами

Функції

MCP Сервер Mapfolio забезпечує комплексну функціональність:

Дані компаній

Пошук компаній з розширеними фільтрами
Отримання деталей компанії за ID
Отримання компаній за кантоном та початковою літерою
Отримання випадкових компаній для вибірки
Доступ до статистики відвідувань компаній

Управління проектами

Створення та управління проектами
Список та фільтрація проектів користувача
Оновлення деталей проекту
Видалення проектів
Додавання та видалення компаній з проектів

Профілі користувачів

Отримання інформації профілю користувача
Оновлення налаштувань профілю
Список проектів користувача
Управління API ключами

Інтеграція LinkedIn

Отримання даних профілю LinkedIn
Пошук профілів LinkedIn
Доступ до інформації про зв'язки
Перегляд історії версій профілю
Отримання даних компаній LinkedIn

Адміністративні операції

Список усіх користувачів (тільки адмін)
Створення нових користувачів (тільки адмін)
Управління API ключами (тільки адмін)
Доступ до статистики адмін-панелі

Статистика

Отримання агрегованої статистики компаній
Перегляд підрахунків на рівні кантонів
Доступ до підрахунків на основі літер
Отримання статистики комбінацій двох літер

Встановлення

Передумови

Node.js >= 20.0.0
npm >= 10.0.0
Доступ до екземпляра Supabase Mapfolio

Налаштування

Встановити залежності:

cd mcp-server
npm install

Налаштувати змінні середовища:

cp .env.example .env

Відредагуйте .env та налаштуйте:

# URL API Mapfolio (за замовчуванням: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Тип транспорту: 'stdio' (за замовчуванням) або 'http' для віддаленого доступу
MCP_TRANSPORT=stdio

# HTTP порт (використовується тільки коли MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Опціонально: За замовчуванням автентифікація (може бути надана через контекст MCP або HTTP заголовки)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here

Зібрати сервер:

npm run build

Використання

Запуск сервера

Локальна розробка (транспорт stdio)

MCP сервер використовує транспорт stdio за замовчуванням (стандартний протокол MCP):

npm start

Для розробки з автоматичним перезавантаженням:

npm run dev

HTTP транспорт (для віддаленого доступу)

Для запуску сервера з HTTP транспортом для локальних тестів:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Це запускає HTTP сервер на порту 3001, який приймає запити JSON-RPC 2.0 через HTTP POST.

Розгортання Vercel (Віддалений доступ)

MCP сервер автоматично доступний через HTTP при розгортанні на Vercel:

Endpoint: https://your-app.vercel.app/api/mcp
Протокол: JSON-RPC 2.0 через HTTP POST
Автентифікація: Через заголовок X-API-Key або заголовок Authorization: Bearer <token>

Приклад запиту:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Налаштування клієнта MCP

Claude Desktop

Локальне розгортання:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Налаштувати через налаштування MCP:

Команда: node
Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
Змінні середовища:
- MAPFOLIO_API_URL: https://mapfolio.app
- MAPFOLIO_API_KEY: Ваш API ключ (опціонально)

Автентифікація

Сервер підтримує два методи автентифікації:

Автентифікація API ключем

API ключі мають префікс mapf_ і можуть:

Бути встановлені через змінну середовища MAPFOLIO_API_KEY
Передаватися на запит через параметр apiKey у викликах інструментів

Автентифікація JWT токеном

JWT токени Supabase можуть:

Бути встановлені через змінну середовища MAPFOLIO_JWT_TOKEN
Передаватися на запит через параметр jwtToken у викликах інструментів

Пріоритет автентифікації

HTTP транспорт: Заголовки (X-API-Key або Authorization) мають пріоритет
Облікові дані на запит (apiKey або jwtToken в аргументах інструментів)
Змінні середовища (MAPFOLIO_API_KEY або MAPFOLIO_JWT_TOKEN)

Автентифікація HTTP транспорту

При використанні HTTP endpoint (/api/mcp), автентифікація надається через HTTP заголовки:

API ключ: X-API-Key: mapf_your_api_key
JWT токен: Authorization: Bearer your_jwt_token

Доступні інструменти

Сервер надає 30+ інструментів у 6 категоріях:

Інструменти компаній

search_companies - Пошук з фільтрами
get_company - Отримання компанії за ID
get_companies_by_canton_letter - Отримання за кантоном та літерою
get_random_companies - Отримання випадкових зразків
get_company_visits - Отримання статистики відвідувань

Інструменти проектів

create_project - Створення нового проекту
list_projects - Список проектів користувача
get_project - Отримання деталей проекту
update_project - Оновлення проекту
delete_project - Видалення проекту
add_companies_to_project - Додавання компаній
remove_companies_from_project - Видалення компаній

Інструменти користувача

get_user_profile - Отримання профілю
update_user_profile - Оновлення профілю
get_user_projects - Список проектів
get_user_api_keys - Список API ключів

Інструменти LinkedIn

get_linkedin_profile - Отримання профілю
search_linkedin_profiles - Пошук профілів
get_linkedin_connections - Отримання зв'язків
get_linkedin_profile_versions - Отримання історії версій
get_linkedin_companies - Отримання даних компаній

Інструменти адміна (Тільки адмін)

list_all_users - Список усіх користувачів
create_user - Створення користувача
get_user_details - Отримання деталей користувача
list_api_keys - Список усіх API ключів
create_api_key - Створення API ключа
revoke_api_key - Відкликання API ключа
get_admin_stats - Отримання статистики адміна

Інструменти статистики

get_company_stats - Отримання агрегованої статистики
get_canton_counts - Отримання підрахунків кантонів
get_letter_counts - Отримання підрахунків літер
get_two_letter_counts - Отримання підрахунків двох літер

Ресурси

Сервер надає доступ на основі ресурсів:

mapfolio://company/{id} - Дані компанії
mapfolio://project/{id} - Дані проекту
mapfolio://user/{id} - Профіль користувача
mapfolio://linkedin-profile/{id} - Профіль LinkedIn

Ресурси можуть включати автентифікацію через параметри запиту:

mapfolio://company/{id}?apiKey=mapf_...
mapfolio://company/{id}?jwtToken=...

Приклад використання

Пошук компаній

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Створення проекту

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Отримання деталей компанії

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Обробка помилок

Всі інструменти повертають помилки в узгодженому форматі:

{
  "error": "Повідомлення про помилку"
}

Типові сценарії помилок:

401 Неавторизовано: Недійсна або відсутня автентифікація
403 Заборонено: Недостатні дозволи
404 Не знайдено: Ресурс не знайдено
500 Внутрішня помилка сервера: Помилка на стороні сервера

Архітектура тільки API

MCP сервер використовує HTTP запити до mapfolio.app замість прямого доступу до бази даних. Це означає:

✅ Не потрібні облікові дані Supabase - Працює тільки з URL API та API ключем
✅ Легке розгортання Vercel - Розгорнути як serverless функцію
✅ Безпечно - Всі запити проходять через API Mapfolio з автентифікацією
✅ Масштабовано - Отримує переваги від обмеження швидкості та кешування API Mapfolio

Наразі доступно через API

✅ Пошук та отримання компаній
✅ Статистика компаній (підрахунки кантонів, підрахунки літер)
✅ Випадкові компанії
✅ Відвідування компаній

Незабаром (Потребує API endpoints)

⏳ Управління проектами (створення, список, оновлення, видалення)
⏳ Управління профілями користувачів
⏳ Доступ до профілів LinkedIn
⏳ Адміністративні операції

Ці функції повертатимуть корисні повідомлення про помилки до створення API endpoints.

Міркування безпеки

API ключі: Зберігайте безпечно, ніколи не комітьте в контроль версій
JWT токени: Токени закінчуються, обробляйте оновлення відповідно
Обмеження швидкості API: Поважає обмеження швидкості API Mapfolio
Тільки HTTPS: Завжди використовуйте HTTPS для API запитів
Адмін операції: Вимагають явної автентифікації адміна (коли endpoints доступні)

Розробка

Перевірка типів

npm run type-check

Збірка

npm run build

Режим розробки

npm run dev

Документація

Для повної документації дивіться README MCP Сервера.

Підтримка

Для проблем або питань:

GitHub Issues: [mapfolio repository]
Email: support@mapfolio.app

Ліцензія

MIT