Przegląd

Serwer MCP Mapfolio to serwer Model Context Protocol (MCP), który umożliwia asystentom AI i innym klientom zgodnym z MCP interakcję z danymi i operacjami Mapfolio. Zapewnia programowy dostęp do firm, projektów, użytkowników, profili LinkedIn i funkcji administracyjnych.

Czym jest MCP?

Model Context Protocol (MCP) to otwarty protokół, który umożliwia asystentom AI bezpieczny dostęp do zewnętrznych źródeł danych i narzędzi. Serwery MCP udostępniają możliwości poprzez ustandaryzowany interfejs, umożliwiając asystentom AI:

Wykonywanie zapytań i pobieranie danych
Wykonywanie operacji
Dostęp do zasobów
Integrację z systemami zewnętrznymi

Funkcje

Serwer MCP Mapfolio zapewnia kompleksową funkcjonalność:

Dane Firm

Wyszukiwanie firm za pomocą zaawansowanych filtrów
Pobieranie szczegółów firmy według ID
Pobieranie firm według kantonu i początkowej litery
Pobieranie losowych firm do próbkowania
Dostęp do statystyk odwiedzin firm

Zarządzanie Projektami

Tworzenie i zarządzanie projektami
Listowanie i filtrowanie projektów użytkownika
Aktualizacja szczegółów projektu
Usuwanie projektów
Dodawanie i usuwanie firm z projektów

Profile Użytkowników

Pobieranie informacji o profilu użytkownika
Aktualizacja ustawień profilu
Listowanie projektów użytkownika
Zarządzanie kluczami API

Integracja LinkedIn

Pobieranie danych profilu LinkedIn
Wyszukiwanie profili LinkedIn
Dostęp do informacji o połączeniach
Przeglądanie historii wersji profilu
Pobieranie danych firm LinkedIn

Operacje Administracyjne

Listowanie wszystkich użytkowników (tylko admin)
Tworzenie nowych użytkowników (tylko admin)
Zarządzanie kluczami API (tylko admin)
Dostęp do statystyk panelu administracyjnego

Statystyki

Pobieranie zagregowanych statystyk firm
Przeglądanie liczebności na poziomie kantonu
Dostęp do liczebności opartych na literach
Pobieranie statystyk kombinacji dwóch liter

Instalacja

Wymagania Wstępne

Node.js >= 20.0.0
npm >= 10.0.0
Dostęp do instancji Supabase Mapfolio

Konfiguracja

Zainstaluj zależności:

cd mcp-server
npm install

Skonfiguruj zmienne środowiskowe:

cp .env.example .env

Edytuj .env i skonfiguruj:

# URL API Mapfolio (domyślnie: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Typ transportu: 'stdio' (domyślnie) lub 'http' dla dostępu zdalnego
MCP_TRANSPORT=stdio

# Port HTTP (używany tylko gdy MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Opcjonalne: Domyślne uwierzytelnianie (może być dostarczone przez kontekst MCP lub nagłówki HTTP)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here

Zbuduj serwer:

npm run build

Użycie

Uruchamianie Serwera

Rozwój Lokalny (transport stdio)

Serwer MCP używa transportu stdio domyślnie (standardowy protokół MCP):

npm start

Dla rozwoju z automatycznym przeładowaniem:

npm run dev

Transport HTTP (dla dostępu zdalnego)

Aby uruchomić serwer z transportem HTTP do testów lokalnych:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

To uruchamia serwer HTTP na porcie 3001, który akceptuje żądania JSON-RPC 2.0 przez HTTP POST.

Wdrożenie Vercel (Dostęp Zdalny)

Serwer MCP jest automatycznie dostępny przez HTTP po wdrożeniu na Vercel:

Endpoint: https://your-app.vercel.app/api/mcp
Protokół: JSON-RPC 2.0 przez HTTP POST
Uwierzytelnianie: Przez nagłówek X-API-Key lub nagłówek Authorization: Bearer <token>

Przykładowe żądanie:

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
  }'

Konfiguracja Klienta MCP

Claude Desktop

Wdrożenie lokalne:

{
  "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

Skonfiguruj przez ustawienia MCP:

Polecenie: node
Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
Zmienne środowiskowe:
- MAPFOLIO_API_URL: https://mapfolio.app
- MAPFOLIO_API_KEY: Twój klucz API (opcjonalne)

Uwierzytelnianie

Serwer obsługuje dwie metody uwierzytelniania:

Uwierzytelnianie Kluczem API

Klucze API mają prefiks mapf_ i mogą:

Być ustawione przez zmienną środowiskową MAPFOLIO_API_KEY
Być przekazywane na żądanie przez parametr apiKey w wywołaniach narzędzi

Uwierzytelnianie Tokenem JWT

Tokeny JWT Supabase mogą:

Być ustawione przez zmienną środowiskową MAPFOLIO_JWT_TOKEN
Być przekazywane na żądanie przez parametr jwtToken w wywołaniach narzędzi

Priorytet Uwierzytelniania

Transport HTTP: Nagłówki (X-API-Key lub Authorization) mają pierwszeństwo
Dane uwierzytelniające na żądanie (apiKey lub jwtToken w argumentach narzędzi)
Zmienne środowiskowe (MAPFOLIO_API_KEY lub MAPFOLIO_JWT_TOKEN)

Uwierzytelnianie Transportu HTTP

Podczas używania endpointu HTTP (/api/mcp), uwierzytelnianie jest dostarczane przez nagłówki HTTP:

Klucz API: X-API-Key: mapf_your_api_key
Token JWT: Authorization: Bearer your_jwt_token

Dostępne Narzędzia

Serwer zapewnia 30+ narzędzi w 6 kategoriach:

Narzędzia Firm

search_companies - Wyszukiwanie z filtrami
get_company - Pobieranie firmy według ID
get_companies_by_canton_letter - Pobieranie według kantonu i litery
get_random_companies - Pobieranie losowych próbek
get_company_visits - Pobieranie statystyk odwiedzin

Narzędzia Projektów

create_project - Tworzenie nowego projektu
list_projects - Listowanie projektów użytkownika
get_project - Pobieranie szczegółów projektu
update_project - Aktualizacja projektu
delete_project - Usuwanie projektu
add_companies_to_project - Dodawanie firm
remove_companies_from_project - Usuwanie firm

Narzędzia Użytkownika

get_user_profile - Pobieranie profilu
update_user_profile - Aktualizacja profilu
get_user_projects - Listowanie projektów
get_user_api_keys - Listowanie kluczy API

Narzędzia LinkedIn

get_linkedin_profile - Pobieranie profilu
search_linkedin_profiles - Wyszukiwanie profili
get_linkedin_connections - Pobieranie połączeń
get_linkedin_profile_versions - Pobieranie historii wersji
get_linkedin_companies - Pobieranie danych firm

Narzędzia Admin (Tylko Admin)

list_all_users - Listowanie wszystkich użytkowników
create_user - Tworzenie użytkownika
get_user_details - Pobieranie szczegółów użytkownika
list_api_keys - Listowanie wszystkich kluczy API
create_api_key - Tworzenie klucza API
revoke_api_key - Cofanie klucza API
get_admin_stats - Pobieranie statystyk admin

Narzędzia Statystyk

get_company_stats - Pobieranie zagregowanych statystyk
get_canton_counts - Pobieranie liczebności kantonów
get_letter_counts - Pobieranie liczebności liter
get_two_letter_counts - Pobieranie liczebności dwóch liter

Zasoby

Serwer zapewnia dostęp oparty na zasobach:

mapfolio://company/{id} - Dane firmy
mapfolio://project/{id} - Dane projektu
mapfolio://user/{id} - Profil użytkownika
mapfolio://linkedin-profile/{id} - Profil LinkedIn

Zasoby mogą zawierać uwierzytelnianie przez parametry zapytania:

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

Przykład Użycia

Wyszukiwanie Firm

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

Tworzenie Projektu

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

Pobieranie Szczegółów Firmy

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

Obsługa Błędów

Wszystkie narzędzia zwracają błędy w spójnym formacie:

{
  "error": "Komunikat błędu"
}

Typowe scenariusze błędów:

401 Nieautoryzowany: Nieprawidłowe lub brakujące uwierzytelnianie
403 Zabroniony: Niewystarczające uprawnienia
404 Nie Znaleziono: Zasób nie znaleziony
500 Wewnętrzny Błąd Serwera: Błąd po stronie serwera

Architektura Tylko API

Serwer MCP używa żądań HTTP do mapfolio.app zamiast bezpośredniego dostępu do bazy danych. Oznacza to:

✅ Nie są potrzebne dane uwierzytelniające Supabase - Działa tylko z URL API i kluczem API
✅ Łatwe wdrożenie Vercel - Wdróż jako funkcja serverless
✅ Bezpieczne - Wszystkie żądania przechodzą przez API Mapfolio z uwierzytelnianiem
✅ Skalowalne - Korzyści z ograniczania szybkości i buforowania API Mapfolio

Obecnie Dostępne przez API

✅ Wyszukiwanie i pobieranie firm
✅ Statystyki firm (liczebności kantonów, liczebności liter)
✅ Losowe firmy
✅ Odwiedziny firm

Wkrótce (Wymaga Endpointów API)

⏳ Zarządzanie projektami (tworzenie, listowanie, aktualizacja, usuwanie)
⏳ Zarządzanie profilami użytkowników
⏳ Dostęp do profili LinkedIn
⏳ Operacje administracyjne

Te funkcje będą zwracać pomocne komunikaty błędów, dopóki nie zostaną utworzone endpointy API.

Rozważania Bezpieczeństwa

Klucze API: Przechowuj bezpiecznie, nigdy nie commituj do kontroli wersji
Tokeny JWT: Tokeny wygasają, obsługuj odświeżanie odpowiednio
Ograniczanie Szybkości API: Szanuje limity szybkości API Mapfolio
Tylko HTTPS: Zawsze używaj HTTPS dla żądań API
Operacje Admin: Wymagają jawnego uwierzytelniania admin (gdy endpointy są dostępne)

Rozwój

Sprawdzanie Typów

npm run type-check

Budowanie

npm run build

Tryb Rozwoju

npm run dev

Dokumentacja

Aby uzyskać pełną dokumentację, zobacz README Serwera MCP.

Wsparcie

W przypadku problemów lub pytań:

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

Licencja

MIT