Serwer MCP i API ProcessCraft
Serwer MCP udostępnia instrukcje Twojej organizacji agentom AI. Agent działa w imieniu osoby — tylko z zakresami, które ta osoba zatwierdzi na ekranie zgody.
Quickstart: połącz agenta w 5 minut
01Dodaj serwer w kliencie MCP
Adres serwera: https://mcp.processcraft.pl/v1 (Streamable HTTP). Wybierz klienta, z którego korzystasz:
{
"mcpServers": {
"processcraft": { "url": "https://mcp.processcraft.pl/v1" }
}
}02Zatwierdź zgodę OAuth
Przy pierwszym wywołaniu klient otworzy ekran zgody ProcessCraft. Zaloguj się, wybierz przestrzeń i zakresy (np. processes:read, drafts:write). Dostęp odwołasz w każdej chwili w ustawieniach profilu.
03Wykonaj pierwsze wywołanie
Wyszukaj procedurę i pobierz jej wersję opublikowaną. Treść instrukcji wraca jako dane, nie jako polecenia dla agenta.
// 1. wyszukaj procedurę
search_processes({ "query": "odbiór lokalu" })
// 2. pobierz wersję opublikowaną
get_process({ "id": "INS-0042", "version": "published" }){ "id": "INS-0042", "version": "3.1", "status": "PUBLISHED",
"title": "Odbiór lokalu od dewelopera", "steps": 7,
"owner": "Anna Nowak", "consistency": "CONSISTENT" }MCP: narzędzia
Lista pochodzi z opisu serwera (mcpServer.getInfo) — ta sama, którą klient dostaje w protokole MCP.
| Narzędzie | Wymagany zakres | Kredyty AI | Opis |
|---|---|---|---|
| search_processes | processes:read | nie | Wyszukuje opublikowane instrukcje w przestrzeniach osoby |
| get_process | processes:read | nie | Wersja instrukcji: kroki, stanowiska, kryteria |
| get_bpmn | processes:read | nie | Diagram wersji jako BPMN 2.0 XML |
| get_my_position | processes:read | nie | Stanowisko osoby i przypisane instrukcje |
| list_spaces | processes:read | nie | Przestrzenie dostępne dla osoby |
| list_positions | processes:read | nie | Słownik stanowisk organizacji |
| create_draft_from_text | drafts:write, ai:use | tak | Wersja robocza z opisu procesu |
| import_document | drafts:write, ai:use | tak | Wersja robocza z dokumentu (DOCX, PDF) |
| patch_draft_graph | drafts:write | nie | Zmiana kroków i przejść wersji roboczej |
| validate_draft | drafts:write | nie | Walidacja i stan spójności z BPMN |
| generate_bpmn | bpmn:generate | nie | Diagram BPMN z listy kroków |
| request_approval | drafts:write | nie | Wysyła wersję do zatwierdzenia — zatwierdza człowiek |
| add_comment | comments:write | nie | Komentarz w wątku dyskusji kroku |
| review_process | ai:use | tak | Recenzja AI: luki i niespójności |
| ask_procedures | ai:use | tak | Odpowiedź Asystenta na pytanie o procedury |
| report_issue | comments:write | nie | Zgłoszenie problemu z instrukcją do autora |
Czego agent nie zrobi
Zakresy OAuth i zgoda
| Zakres | Pozwala na | Dozwolone role | Kredyty AI |
|---|---|---|---|
| processes:read | Czytanie opublikowanych instrukcji i diagramów | wszystkie role | nie |
| drafts:write | Tworzenie i zmiana wersji roboczych, wysyłka do zatwierdzenia | Twórca, Administrator, Właściciel | nie |
| bpmn:generate | Generowanie diagramu z listy kroków | Twórca, Administrator, Właściciel | nie |
| ai:use | Funkcje AI: import, recenzja, pytania do Asystenta | Twórca, Zatwierdzający, Administrator, Właściciel | tak |
| comments:write | Komentarze i zgłoszenia problemów | wszystkie role | nie |
Autoryzacja: OAuth 2.1 z PKCE. Na ekranie zgody osoba wybiera przestrzenie i zakresy; agent nie dostanie więcej, niż pozwala jej rola. Dostęp odwołasz w profilu, a Administrator — na liście agentów organizacji.
Wywołanie bez zakresu kończy się błędem FORBIDDEN z polem details.required_scope.
Skills i Process-as-Skill
Pakiet skilli uczy asystenta pracy z ProcessCraft: modelowania kroków, importu dokumentów, recenzji i wykonywania instrukcji przez MCP.
- processcraft-modelerModeluje kroki, stanowiska i bramki decyzyjne; tworzy z nich wersję roboczą.processes:readdrafts:writebpmn:generate14 KB
- processcraft-importerZamienia istniejące dokumenty w uporządkowane kroki wersji roboczej.drafts:writeai:use11 KB
- processcraft-reviewerSzuka luk i niespójności, zostawia komentarze w wątkach.processes:readcomments:writeai:use12 KB
- processcraft-runnerProwadzi krok po kroku przez opublikowaną instrukcję stanowiska.processes:read11 KB
unzip processcraft-skills-1.2.0.zip -d ./skills/
# w kliencie webowym (np. claude.ai) wgraj ZIP w ustawieniach skilliProcess-as-Skill
Opublikowaną instrukcję możesz wyeksportować jako Skill (ZIP) z numerem wersji i kryteriami ukończenia kroków. Eksport wykonuje człowiek w aplikacji — agent nie publikuje i nie eksportuje wersji.
Błędy, limity, idempotencja
Każdy błąd ma ten sam format; w MCP wynik ma dodatkowo isError: true. Pole message to krótki opis techniczny po angielsku — rozgałęziaj logikę po code i details, nie po treści komunikatu. request_id to trace_id z nagłówka W3C traceparent — podaj go w zgłoszeniu.
{ "code": "FORBIDDEN", "message": "Missing required scope: drafts:write.",
"request_id": "8f2c41b6e0d94a7f9c3e5a1d2b7f6c08", "retryable": false,
"docs_url": "https://processcraft.pl/docs/errors#FORBIDDEN",
"details": { "reason": "scope", "required_scope": "drafts:write" } }| Kod | HTTP | Ponów | Znaczenie |
|---|---|---|---|
| VALIDATION_FAILED | 400 | nie | Popraw pola z details.fields[] |
| UNAUTHENTICATED | 401 | nie | Token wygasł — odnów autoryzację |
| FORBIDDEN | 403 | nie | Brak roli lub zakresu (required_scope) |
| PLAN_LIMIT_REACHED | 403 | nie | Limit planu organizacji |
| PAYMENT_REQUIRED | 402 | nie | Organizacja w trybie tylko do odczytu |
| AI_CREDITS_EXHAUSTED | 402 | nie | Za mało kredytów AI |
| NOT_FOUND | 404 | nie | Element nie istnieje lub nie masz do niego dostępu |
| IDEMPOTENCY_CONFLICT | 409 | zależy | Ten sam klucz z inną treścią albo operacja w toku |
| RATE_LIMITED | 429 | tak | Za dużo wywołań — czekaj retry_after s |
| INTERNAL_ERROR | 500 | nie | Błąd po naszej stronie — zgłoś request_id |
Limity, paginacja i idempotencja
- RATE_LIMITED (429) zwraca nagłówek Retry-After — ponów po wskazanym czasie.
- Listy są stronicowane kursorem: kolejna strona przez next_cursor.
- Komendy zapisu przyjmują Idempotency-Key; powtórka z tym samym kluczem zwraca pierwszy wynik.
- Blokady planu: PAYMENT_REQUIRED, PLAN_LIMIT_REACHED, AI_CREDITS_EXHAUSTED — z resolve_url dla osoby.
Zmiany
- serwer MCP 1.4.0Nowe narzędzie report_issue; FORBIDDEN zwraca details.required_scope.
- skille 1.2.0Nowy skill processcraft-runner.
- API v1Zmiana niekompatybilnaPaginacja kursorem (next_cursor) zamiast numeru strony.