Jan MCP

<p align="center"> <img src="docs/images/jan-kochanowski-coder-engraving.webp" alt="Jan Kochanowski jako skupiony coder w stylu starej ryciny" width="720" /> </p>

Od suchych bulletów do publikowalnych release notes. Po polsku.

Jan to repo-native MCP agent dla polskich zespołów technicznych. Bierze typowe GitHubowe notki, diffy i surowe bullet points, a oddaje gotowe changelogi, release notesy i opisy PR, które da się wkleić bez dalszego wygładzania.

• Zamienia bezosobowe, angielskie notki z GitHuba w naturalny polski komunikat dla zespołu.
• Trzyma się faktów i szablonów artefaktu zamiast pisać "od zera" jak ogólny chat.
• Działa w MCP i można go prototypować za darmo na NVIDIA_API_KEY.

Szybkie przejścia: Quickstart · Before / After · Core workflows · Benchmarki

Co robi Jan

Jan jest ustawiony pod jeden konkretny workflow: komunikację zmian w software delivery po polsku.

Najlepiej sprawdza się przy:

• release notesach i changelogach z GitHubowych bulletów
• opisach PR dla reviewerów
• porządkowaniu ticketów i issue do formy gotowej dla zespołu
• notatkach rolloutowych opartych o realny kontekst z repo

Nie jest pozycjonowany jako "najmądrzejszy model ogólny". Ma być lepszym narzędziem do codziennego publikowania zmian po polsku.

Before / After

Wejście z typowych, bezosobowych notek GitHuba:

- Added retry handling for checkout webhook delivery.
- Improved cache invalidation for product detail pages.
- Fixed duplicate analytics events on checkout success.

Typowy ogólny model	Jan MCP
Dodano obsługę ponownych prób dostarczenia webhooków checkoutu. Ulepszono unieważnianie pamięci podręcznej dla stron szczegółów produktu. Naprawiono zduplikowane zdarzenia analityczne po pomyślnym zakończeniu checkoutu.	Poprawiliśmy niezawodność checkoutu i uporządkowaliśmy kilka elementów wokół zakupu. System lepiej ponawia dostarczanie webhooków, strony produktów szybciej pokazują aktualne dane, a analityka po zakończonym checkoutcie nie dubluje już zdarzeń.

Różnica nie polega na "magii modelu". Jan jest po prostu ustawiony produktowo pod polskie release notesy i changelogi dla współpracowników, a nie pod ogólną konwersację.

Quickstart

git clone https://github.com/pdurlej/jan-subagent.git
cd jan-subagent
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
export NVIDIA_API_KEY="twoj-klucz"
.venv/bin/python -m jan.jan_subagent_opencode

Gotowy sample config dla klienta MCP jest w mcp_config.json.

Jeśli chcesz szybko sprawdzić runtime lokalnie:

python3 -m pytest -q
.venv/bin/python -m compileall -q jan
.venv/bin/python -m jan.jan_subagent_opencode

Get a free NVIDIA API key

Jan działa na Bieliku przez hosted endpointy NVIDIA NIM. Do prototypowania wystarczy darmowy dostęp z NVIDIA Developer Program.

1. Wejdź na build.nvidia.com.
2. Otwórz dowolny model lub endpoint i kliknij Get API Key.
3. Zaloguj się albo załóż konto w NVIDIA Developer Program.
4. Skopiuj klucz i ustaw lokalnie jako NVIDIA_API_KEY.

Oficjalne źródła:

• API Catalog Quickstart Guide
• Run NIM Anywhere

Przykładowy plik środowiskowy jest w .env.example.

Core workflows

Jan ma dziś najwięcej sensu jako zestaw nazwanych workflowów, a nie zbiór ogólnych promptów.

Release notes z surowych bulletów

compose_release_notes(
    raw_notes="""
    - Added retry handling for checkout webhook delivery.
    - Improved cache invalidation for product detail pages.
    - Fixed duplicate analytics events on checkout success.
    """,
    audience="customer",
)

Opis PR dla reviewera

write_pr_description(
    raw_notes="""
    checkout webhook retries
    product page cache invalidation
    analytics dedupe on success
    """,
    audience="reviewer",
)

Rewrite chaotycznego issue do formy zespołowej

rewrite_issue(
    raw_notes="""
    klient zgłasza, że po checkoutcie czasem są zdublowane eventy,
    trudno to odtworzyć, wygląda na problem po stronie success callback
    """,
    audience="internal",
    response_mode="review",
)

Notatka rolloutowa z review JSON

write_rollout_note(
    raw_notes="Rollout checkout webhook retry logic behind a feature flag.",
    audience="internal",
    response_mode="review",
)

response_mode="final" zwraca gotowy tekst do wklejenia. response_mode="review" zwraca JSON z final_text, source_trace i validator_report.

Dla kogo

Jan najlepiej pasuje do:

• polskich zespołów produktowo-inżynieryjnych
• leadów i senior engineerów piszących opisy PR
• release managerów składających changelog lub release notes
• zespołów, które chcą spójnej terminologii i szablonów bez ręcznego promptowania

Mniej sensu ma wtedy, gdy potrzebujesz ogólnego asystenta do wszystkiego albo miękkiej, relacyjnej komunikacji typu support reply czy statusowy mail.

Kiedy Jan jest lepszym wyborem niż model ogólny

Sytuacja	Lepszy wybór	Dlaczego
Release notes z suchych bulletów i commitów	Jan	Ma workflow, audience packs, policy pack i output gotowy do wklejenia.
Opis PR zgodny z template'em zespołu	Jan	Lepiej trzyma sekcje, fakty i terminologię z repo.
Porządkowanie issue pod zespół techniczny	Jan	Pracuje na named workflow, nie na improwizowanym promptcie.
Otwarta burza mózgów albo swobodny writing assistant	Ogólny model	Tu specjalizacja Jana daje mniej przewagi niż szeroka inteligencja ogólna.

Benchmark snapshot

Obecny pilot po refactorze paste-ready:

• GPT-5.4: 96.5%
• Jan: 94.0%
• raw Bielik: 93.1%

Najważniejszy sygnał: Jan nie wygrywa "większą inteligencją ogólną". Wygrywa tym, że daje lepszy workflow i bardziej publikowalny polski output niż surowy model.

Dalsze szczegóły:

• Workplace writing pilot
• Repo-native delivery benchmark v2
• Metodologia benchmarków

Advanced context

Jan potrafi pracować na więcej niż samym raw_notes.

• jan.yml trzyma glossary, do_not_translate, audience packs i validation policy.
• Workflow może korzystać z local git, GitHuba i Jiry, jeśli są dostępne kredensiale.
• review mode dodaje traceability i raport walidacyjny zamiast zgadywania.

Najważniejsze envy:

• NVIDIA_API_KEY
• GITHUB_TOKEN
• GITHUB_REPOSITORY
• JIRA_BASE_URL
• JIRA_EMAIL
• JIRA_API_TOKEN
• JAN_POLICY_FILE

Zobacz:

• jan.yml
• .env.example

Dalsza lektura

• Release notes v3.0.0
• Migration guide 3.0.0
• Contributor thread bootstrap

Dla contributorów

Jeśli chcesz pracować nad repo, benchmarkami albo planowaniem kolejnych pivotów:

• _bmad-output/project-context.md
• _bmad-output/planning-artifacts/jan-v3-prd.md
• _bmad-output/planning-artifacts/jan-v3-architecture.md
• scripts/test_delivery_benchmark.py
• scripts/run_delivery_benchmark.py

Kontakt

• GitHub Issues
• Repozytorium