{"id":43846537,"url":"https://github.com/lukaszzychal/mcp-doc-generator","last_synced_at":"2026-02-06T06:04:52.836Z","repository":{"id":326098623,"uuid":"1102826088","full_name":"lukaszzychal/mcp-doc-generator","owner":"lukaszzychal","description":"📊 MCP Server for automated technical documentation \u0026 architecture diagrams. Generate C4, UML, Mermaid \u0026 Graphviz diagrams. Export to PDF/DOCX with full Unicode support. 🇵🇱 Polish language ready.","archived":false,"fork":false,"pushed_at":"2025-12-03T19:58:00.000Z","size":896,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T19:56:21.234Z","etag":null,"topics":["adr","api-documentation","architecture","architecture-diagrams","c4-model","devtools","documentation-generator","docx","mcp","mermaid","pdf-generator","plantuml","polish","technical-writing","uml"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukaszzychal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-24T05:04:26.000Z","updated_at":"2025-12-03T19:57:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lukaszzychal/mcp-doc-generator","commit_stats":null,"previous_names":["lukaszzychal/mcp-doc-generator"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/lukaszzychal/mcp-doc-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszzychal%2Fmcp-doc-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszzychal%2Fmcp-doc-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszzychal%2Fmcp-doc-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszzychal%2Fmcp-doc-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukaszzychal","download_url":"https://codeload.github.com/lukaszzychal/mcp-doc-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszzychal%2Fmcp-doc-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29153163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","api-documentation","architecture","architecture-diagrams","c4-model","devtools","documentation-generator","docx","mcp","mermaid","pdf-generator","plantuml","polish","technical-writing","uml"],"created_at":"2026-02-06T06:04:51.950Z","updated_at":"2026-02-06T06:04:52.830Z","avatar_url":"https://github.com/lukaszzychal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Documentation Server\n\nMCP (Model Context Protocol) server for generating technical documentation with diagrams.\n\n\u003e **📢 Status:** Serwer MCP jest obecnie testowany w pracy.\n\n**Language / Język:** [English](#english) | [Polski](#polski)\n\n---\n\n\u003ca name=\"english\"\u003e\u003c/a\u003e\n# English\n\n\u003e **📢 Status:** The MCP server is currently being tested in production at work.\n\n## 🚀 Quick Start\n\n```bash\n# 1. Start Docker containers\ndocker compose up -d\n\n# 2. Use MCP client with your own prompt\npython3 scripts/mcp_client.py -f examples/prompts/prompt.txt\n\n# 3. Or use in Cursor - open conversation and use MCP tools\n```\n\n## 📦 Installation via npx\n\nYou can install and run the server directly via `npx` without cloning the repository:\n\n```bash\n# Latest version from main branch\nnpx github:lukaszzychal/mcp-doc-generator\n\n# Specific version (tag)\nnpx github:lukaszzychal/mcp-doc-generator#v0.1.7\n\n# Specific branch\nnpx github:lukaszzychal/mcp-doc-generator#feat/test-npx-installation\n```\n\n**Requirements:**\n- Node.js \u003e= 14.0.0 (for npx)\n- Docker and Docker Compose (automatically managed by wrapper)\n- Docker daemon must be running\n\n**No local Python, Graphviz, Pandoc, or other tools required!** Everything runs in Docker containers.\n\nFor detailed instructions, see [NPX_INSTALLATION.md](docs/NPX_INSTALLATION.md).\n\n### OpenAI Image Generation (Optional)\n\nTo use AI image generation tools (`generate_image_openai`, `generate_icon_openai`, `generate_illustration_openai`):\n\n1. **Set environment variable:**\n   ```bash\n   export OPENAI_API_KEY=sk-...\n   ```\n\n2. **Get API key:** [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n\n3. **Pricing:** $0.04-0.12 per image (see [ROADMAP.md](docs/ROADMAP.md) for details)\n\n**Note:** OpenAI tools are optional. All other tools work without API key. If API key is not configured, you'll receive a helpful error message with setup instructions.\n\n#### Automatic Polish Text Translation\n\nThe OpenAI image generation tools automatically detect and translate Polish words to English for better text rendering in generated images. DALL-E 3 has limited support for non-English text, especially with diacritics.\n\n##### Why PL→EN Translation is Required\n\n**DALL-E 3 Limitations:**\n- **Poor Polish text rendering**: DALL-E 3 struggles with Polish characters (ą, ć, ę, ł, ń, ó, ś, ź, ż), often producing misspellings like:\n  - \"Struktura\" → \"Strutira\" or \"STRUTIRA\"\n  - \"Elastyczny\" → \"Elastncy\" or \"ELASTNCY\"\n  - \"DOBRY KOD\" → \"DOBBRY KOD\" or \"GODE CODE\"\n- **Diacritics not supported**: Polish diacritics are frequently omitted or replaced with incorrect characters\n- **English-first training**: DALL-E 3 was primarily trained on English text, resulting in much better accuracy for English\n- **Text rendering quality**: English text in images is significantly more accurate and readable\n\n**Why We Don't Support Direct Polish:**\n1. **Technical limitation**: This is a DALL-E 3 model limitation, not a bug in our code\n2. **Quality assurance**: English text ensures professional, readable diagrams\n3. **User experience**: Automatic translation provides the best results without user intervention\n4. **Future-proof**: If OpenAI improves Polish support, we can easily adjust the translation logic\n\n**Our Solution:**\nInstead of fighting DALL-E 3's limitations, we automatically translate Polish to English before image generation, ensuring:\n- ✅ Accurate text rendering\n- ✅ Professional-looking diagrams\n- ✅ No manual translation needed\n- ✅ Seamless user experience (you can still use Polish prompts!)\n\n**How it works (Hybrid Approach):**\n1. **DALL-E 3 generates graphics without text** - Visual elements only (shapes, icons, colors)\n2. **Text labels are extracted** from your prompt automatically\n3. **PIL/Pillow adds text overlay** - Perfect text rendering with precise positioning\n4. **Result**: Beautiful graphics from DALL-E 3 + perfect text from PIL\n\n**Benefits:**\n- ✅ **100% accurate text** - No misspellings or errors\n- ✅ **Supports all languages** - Polish with diacritics works perfectly\n- ✅ **Professional quality** - Clean, readable labels\n- ✅ **Consistent results** - Same text every time\n\n**Technical details:**\n- Automatically detects Polish words and translates for prompt clarity\n- Extracts text labels (titles, acronyms, labels) from your prompt\n- Uses DejaVu Sans font (supports Polish characters)\n- Positions text intelligently (central labels, branch labels for mind maps)\n\n**Example:**\n- Input prompt: `\"Diagram z tytułem 'DOBRY KOD' pokazujący Struktura SOLID\"`\n- Enhanced prompt: `\"Diagram with title 'GOOD CODE' showing Structure SOLID\"` + instruction for English text rendering\n\nYou can use Polish in your prompts - the system will automatically handle translation for text that appears in the image.\n\n#### Usage Examples\n\n**In Cursor (Recommended):**\nSimply describe what you want in natural language:\n```\nWygeneruj ilustrację mapy myśli \"Zasady dobrego kodu\" z centralnym węzłem \n\"Dobry kod = prosty, elastyczny, odporny\" i 5 gałęziami: SOLID, DRY, KISS, GRASP, CUPID.\nZapisz jako output/mindmap.png\n```\n\nCursor automatically:\n1. Recognizes this is an illustration request\n2. Calls `generate_illustration_openai` via MCP protocol\n3. Translates Polish text to English automatically\n4. Generates the image\n\n**Using mcp_client.py:**\n```bash\n# Set API key\nexport OPENAI_API_KEY=sk-...\n\n# Generate illustration from prompt\npython3 scripts/mcp_client.py -p \"Wygeneruj ilustrację plakatu z zasadami programowania. Zapisz jako output/poster.png\"\n\n# Or from file\npython3 scripts/mcp_client.py -f prompt.txt\n```\n\n**No Python code needed!** Just describe what you want - the MCP server handles everything automatically.\n\n## 📦 Stable Release\n\n**Latest stable version:** [v0.1.7](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.7)\n\nFor production use, we recommend using a tagged release:\n\n```bash\n# Clone specific version\ngit clone --branch v0.1.7 https://github.com/lukaszzychal/mcp-doc-generator.git\n\n# Or checkout tag in existing repo\ngit checkout v0.1.7\n```\n\n**Available releases:**\n- [v0.1.7](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.7) - Update version to 0.1.7 and add contact information\n- [v0.1.6](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.6) - Fix npx installation (include Docker files)\n- [v0.1.5](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.5) - Docker-based automatic container management\n- [v0.1.4](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.4) - Commit message rules and validation hooks\n- [v0.1.3](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.3) - npx installation support, Cursor rules\n- [v0.1.2](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.2) - CI/CD optimizations, Docker caching improvements\n- [v0.1.1](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.1) - Previous stable release\n- [v0.1.0](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.0) - Initial release\n\n\u003e **Note:** The `main` branch contains the latest development version. For production, use a tagged release.\n\n### Alternative: Distroless Image (Smaller \u0026 More Secure)\n\nFor a smaller, more secure image (~300-500MB smaller):\n\n```bash\ndocker compose -f docker-compose.distroless.yml up -d\n```\n\nSee [DOCKER_BUILD_OPTIMIZATION.md](docs/DOCKER_BUILD_OPTIMIZATION.md) for details.\n\n## 📚 Documentation\n\n- **[USAGE_GUIDE.md](docs/USAGE_GUIDE.md)** - Complete usage guide (locally and with Cursor)\n- **[QUICKSTART.md](docs/QUICKSTART.md)** - Quick start in 5 minutes\n- **[CURSOR_NPX_SETUP.md](docs/CURSOR_NPX_SETUP.md)** - Cursor configuration guide (npx and Docker)\n- **[NPX_INSTALLATION.md](docs/NPX_INSTALLATION.md)** - Installation via npx\n- **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Project structure\n- **[TEST_RESULTS_MCP.md](docs/TEST_RESULTS_MCP.md)** - Test results for all tools\n- **[DOCKER_CONTAINERS_EXPLAINED.md](docs/DOCKER_CONTAINERS_EXPLAINED.md)** - Docker containers usage explained\n\n## 🛠️ Available Tools\n\n1. **generate_c4_diagram** - C4 architecture diagrams (context, container, component, code)\n2. **generate_uml_diagram** - UML diagrams (class, component, deployment, package, activity, usecase)\n3. **generate_sequence_diagram** - PlantUML sequence diagrams\n4. **generate_flowchart** - Mermaid flowcharts\n5. **generate_mermaid_sequence** - Mermaid sequence diagrams\n6. **generate_gantt** - Gantt charts\n7. **generate_dependency_graph** - Graphviz dependency graphs\n8. **generate_cloud_diagram** - draw.io cloud architecture diagrams\n9. **generate_image_openai** - AI image generation using DALL-E 3 (requires OPENAI_API_KEY)\n10. **generate_icon_openai** - AI icon generation using DALL-E 3 (requires OPENAI_API_KEY)\n11. **generate_illustration_openai** - AI illustration generation using DALL-E 3 (requires OPENAI_API_KEY)\n12. **export_to_pdf** - Markdown to PDF export\n13. **export_to_docx** - Markdown to DOCX export\n14. **create_document_from_template** - Documents from templates (ADR, API Spec, C4, Microservices)\n\n## 📁 Project Structure\n\n```\nMCPServer/\n├── src/              # MCP server source code\n├── scripts/          # Helper scripts (mcp_client.py, install.sh, generate_examples.py)\n├── tests/            # Tests and test files\n├── docs/             # Project documentation\n├── examples/         # Usage examples\n└── output/           # Output directory (mounted in Docker)\n```\n\nDetails: [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)\n\n## 💡 Usage Examples\n\n### Locally (without Cursor)\n\n```bash\n# From file\npython3 scripts/mcp_client.py -f examples/prompts/prompt.txt\n\n# From command line\npython3 scripts/mcp_client.py -p \"Generate C4 context diagram for e-commerce. Save as output/diagram.png\"\n\n# From stdin\ncat prompt.txt | python3 scripts/mcp_client.py\n```\n\n### With Cursor\n\nTwo installation methods are available:\n\n#### Method 1: Docker (Recommended for Production)\n\n1. Start containers: `docker compose up -d`\n2. Configure Cursor MCP settings:\n   ```json\n   {\n     \"mcpServers\": {\n       \"Documentation\": {\n         \"command\": \"docker\",\n         \"args\": [\n           \"exec\",\n           \"-i\",\n           \"mcp-documentation-server\",\n           \"sh\",\n           \"-c\",\n           \"cd /app/src \u0026\u0026 PYTHONPATH=/app/src python server.py\"\n         ],\n         \"env\": {\n           \"PYTHONPATH\": \"/app/src\"\n         }\n       }\n     }\n   }\n   ```\n3. Restart Cursor\n4. Use MCP tools in conversation, e.g.:\n   - \"Generate C4 Context Diagram for e-commerce system\"\n   - \"Create UML Class Diagram with User and Order classes\"\n\n#### Method 2: npx (Recommended - Automatic Docker Management)\n\n1. Make sure Docker is installed and running\n2. Configure Cursor MCP settings:\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-doc-generator\": {\n         \"command\": \"npx\",\n         \"args\": [\n           \"github:lukaszzychal/mcp-doc-generator#v0.1.7\"\n         ]\n       }\n     }\n   }\n   ```\n3. Restart Cursor\n4. The wrapper automatically manages Docker containers - no manual setup needed!\n5. Use MCP tools in conversation\n\n**See [CURSOR_NPX_SETUP.md](docs/CURSOR_NPX_SETUP.md) for detailed configuration instructions.**\n\n## 🧪 Tests\n\n```bash\n# Tests for all MCP tools\npython3 tests/test_mcp_local.py\n\n# Cursor integration test\n./tests/test_mcp_cursor_integration.sh\n```\n\n## 📖 More Information\n\n- [Usage guide](docs/USAGE_GUIDE.md) - Detailed instructions\n- [Quick start](docs/QUICKSTART.md) - Installation and configuration\n- [Test results](docs/TEST_RESULTS_MCP.md) - Status of all tools\n- [Examples](examples/example_usage.md) - Usage examples for each tool\n\n## 🔧 Requirements\n\n### For npx Installation (Recommended)\n- **Node.js** \u003e= 14.0.0 (for npx)\n- **Docker** and **Docker Compose** (automatically managed)\n- **Docker daemon** must be running\n\n### For Direct Docker Installation\n- **Docker** and **Docker Compose**\n- Manual container management\n\n### Optional\n- **Cursor** (for IDE integration)\n\n## 📝 License\n\nSee [LICENSE](LICENSE)\n\n## 💬 Community \u0026 Support\n\n- **Discussions:** [GitHub Discussions](https://github.com/lukaszzychal/mcp-doc-generator/discussions)\n- **Issues:** [GitHub Issues](https://github.com/lukaszzychal/mcp-doc-generator/issues)\n- **Contact:** lukasz.zychal.dev@gmail.com\n\n---\n\n\u003ca name=\"polski\"\u003e\u003c/a\u003e\n# Polski\n\nMCP (Model Context Protocol) server do generowania dokumentacji technicznej z diagramami.\n\n\u003e **📢 Status:** Serwer MCP jest obecnie testowany w pracy.\n\n## 🚀 Szybki Start\n\n```bash\n# 1. Uruchom kontenery Docker\ndocker compose up -d\n\n# 2. Użyj klienta MCP z własnym promptem\npython3 scripts/mcp_client.py -f examples/prompts/prompt.txt\n\n# 3. Lub użyj w Cursor - otwórz konwersację i użyj narzędzi MCP\n```\n\n## 📦 Instalacja przez npx\n\nMożesz zainstalować i uruchomić serwer bezpośrednio przez `npx` bez klonowania repozytorium:\n\n```bash\n# Najnowsza wersja z gałęzi main\nnpx github:lukaszzychal/mcp-doc-generator\n\n# Konkretna wersja (tag)\nnpx github:lukaszzychal/mcp-doc-generator#v0.1.7\n\n# Konkretna gałąź\nnpx github:lukaszzychal/mcp-doc-generator#feat/test-npx-installation\n```\n\n**Wymagania:**\n- Node.js \u003e= 14.0.0 (dla npx)\n- Docker i Docker Compose (automatycznie zarządzane przez wrapper)\n- Docker demon musi być uruchomiony\n\n**Nie trzeba instalować Pythona, Graphviz, Pandoc ani innych narzędzi lokalnie!** Wszystko działa w kontenerach Docker.\n\nSzczegółowe instrukcje: [NPX_INSTALLATION.md](docs/NPX_INSTALLATION.md).\n\n### Generowanie Obrazów OpenAI (Opcjonalne)\n\nAby używać narzędzi generowania obrazów AI (`generate_image_openai`, `generate_icon_openai`, `generate_illustration_openai`):\n\n1. **Ustaw zmienną środowiskową:**\n   ```bash\n   export OPENAI_API_KEY=sk-...\n   ```\n\n2. **Pobierz klucz API:** [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n\n3. **Cennik:** $0.04-0.12 za obraz (zobacz [ROADMAP.md](docs/ROADMAP.md) dla szczegółów)\n\n**Uwaga:** Narzędzia OpenAI są opcjonalne. Wszystkie inne narzędzia działają bez klucza API. Jeśli klucz API nie jest skonfigurowany, otrzymasz pomocny komunikat błędu z instrukcjami konfiguracji.\n\n#### Automatyczne Tłumaczenie Polskiego Tekstu\n\nNarzędzia generowania obrazów OpenAI automatycznie wykrywają i tłumaczą polskie słowa na angielski, aby zapewnić lepsze renderowanie tekstu w generowanych obrazach. DALL-E 3 ma ograniczone wsparcie dla tekstu w językach innych niż angielski, szczególnie dla znaków diakrytycznych.\n\n##### Dlaczego Mapowanie PL→EN jest Wymagane\n\n**Ograniczenia DALL-E 3:**\n- **Słabe renderowanie polskiego tekstu**: DALL-E 3 ma problemy z polskimi znakami (ą, ć, ę, ł, ń, ó, ś, ź, ż), często generując błędy ortograficzne jak:\n  - \"Struktura\" → \"Strutira\" lub \"STRUTIRA\"\n  - \"Elastyczny\" → \"Elastncy\" lub \"ELASTNCY\"\n  - \"DOBRY KOD\" → \"DOBBRY KOD\" lub \"GODE CODE\"\n- **Brak wsparcia dla znaków diakrytycznych**: Polskie znaki diakrytyczne są często pomijane lub zastępowane nieprawidłowymi znakami\n- **Trening głównie na angielskim**: DALL-E 3 był głównie trenowany na tekście angielskim, co daje znacznie lepszą dokładność dla angielskiego\n- **Jakość renderowania tekstu**: Tekst angielski w obrazach jest znacznie bardziej dokładny i czytelny\n\n**Dlaczego Nie Obsługujemy Bezpośrednio Polskiego:**\n1. **Ograniczenie techniczne**: To jest ograniczenie modelu DALL-E 3, a nie błąd w naszym kodzie\n2. **Zapewnienie jakości**: Tekst angielski zapewnia profesjonalne, czytelne diagramy\n3. **Doświadczenie użytkownika**: Automatyczne tłumaczenie zapewnia najlepsze wyniki bez interwencji użytkownika\n4. **Przyszłościowość**: Jeśli OpenAI poprawi wsparcie dla polskiego, możemy łatwo dostosować logikę tłumaczenia\n\n**Nasze Rozwiązanie:**\nZamiast walczyć z ograniczeniami DALL-E 3, automatycznie tłumaczymy polski na angielski przed generowaniem obrazu, zapewniając:\n- ✅ Dokładne renderowanie tekstu\n- ✅ Profesjonalnie wyglądające diagramy\n- ✅ Brak potrzeby ręcznego tłumaczenia\n- ✅ Płynne doświadczenie użytkownika (możesz nadal używać polskich promptów!)\n\n**Jak to działa (Podejście Hybrydowe):**\n1. **DALL-E 3 generuje grafikę bez tekstu** - Tylko elementy wizualne (kształty, ikony, kolory)\n2. **Etykiety tekstowe są wyodrębniane** z Twojego promptu automatycznie\n3. **PIL/Pillow dodaje nakładkę tekstową** - Doskonałe renderowanie tekstu z precyzyjnym pozycjonowaniem\n4. **Wynik**: Piękna grafika z DALL-E 3 + doskonały tekst z PIL\n\n**Zalety:**\n- ✅ **100% dokładny tekst** - Brak błędów ortograficznych\n- ✅ **Obsługuje wszystkie języki** - Polski z diakrytykami działa doskonale\n- ✅ **Profesjonalna jakość** - Czyste, czytelne etykiety\n- ✅ **Spójne wyniki** - Ten sam tekst za każdym razem\n\n**Szczegóły techniczne:**\n- Automatycznie wykrywa polskie słowa i tłumaczy dla jasności promptu\n- Wyodrębnia etykiety tekstowe (tytuły, akronimy, etykiety) z Twojego promptu\n- Używa czcionki DejaVu Sans (obsługuje polskie znaki)\n- Inteligentnie pozycjonuje tekst (etykiety centralne, etykiety gałęzi dla map myśli)\n\n**Przykład:**\n- Prompt wejściowy: `\"Diagram z tytułem 'DOBRY KOD' pokazujący Struktura SOLID\"`\n- Prompt ulepszony: `\"Diagram with title 'GOOD CODE' showing Structure SOLID\"` + instrukcja renderowania tekstu po angielsku\n\nMożesz używać polskiego w swoich promptach - system automatycznie obsłuży tłumaczenie dla tekstu, który pojawia się na obrazie.\n\n#### Przykłady Użycia\n\n**W Cursor (Zalecane):**\nPo prostu opisz co chcesz w języku naturalnym:\n```\nWygeneruj ilustrację mapy myśli \"Zasady dobrego kodu\" z centralnym węzłem \n\"Dobry kod = prosty, elastyczny, odporny\" i 5 gałęziami: SOLID, DRY, KISS, GRASP, CUPID.\nZapisz jako output/mindmap.png\n```\n\nCursor automatycznie:\n1. Rozpoznaje, że to prośba o ilustrację\n2. Wywołuje `generate_illustration_openai` przez protokół MCP\n3. Tłumaczy polski tekst na angielski automatycznie\n4. Generuje obraz\n\n**Używając mcp_client.py:**\n```bash\n# Ustaw klucz API\nexport OPENAI_API_KEY=sk-...\n\n# Wygeneruj ilustrację z promptu\npython3 scripts/mcp_client.py -p \"Wygeneruj ilustrację plakatu z zasadami programowania. Zapisz jako output/poster.png\"\n\n# Lub z pliku\npython3 scripts/mcp_client.py -f prompt.txt\n```\n\n**Nie trzeba pisać kodu Python!** Wystarczy opisać co chcesz - serwer MCP obsługuje wszystko automatycznie.\n\n## 📦 Stabilna Wersja\n\n**Najnowsza stabilna wersja:** [v0.1.7](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.7)\n\nDo użycia produkcyjnego zalecamy użycie tagowanej wersji:\n\n```bash\n# Sklonuj konkretną wersję\ngit clone --branch v0.1.7 https://github.com/lukaszzychal/mcp-doc-generator.git\n\n# Lub przełącz się na tag w istniejącym repo\ngit checkout v0.1.7\n```\n\n**Dostępne wydania:**\n- [v0.1.7](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.7) - Aktualizacja wersji do 0.1.7 i dodanie informacji kontaktowej\n- [v0.1.6](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.6) - Naprawa instalacji npx (zawiera pliki Docker)\n- [v0.1.5](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.5) - Automatyczne zarządzanie kontenerami Docker\n- [v0.1.4](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.4) - Reguły commitów i hooki walidacji\n- [v0.1.3](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.3) - Wsparcie instalacji npx, reguły Cursor\n- [v0.1.2](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.2) - Optymalizacje CI/CD, ulepszenia cache Docker\n- [v0.1.1](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.1) - Poprzednia stabilna wersja\n- [v0.1.0](https://github.com/lukaszzychal/mcp-doc-generator/releases/tag/v0.1.0) - Wersja początkowa\n\n\u003e **Uwaga:** Branch `main` zawiera najnowszą wersję deweloperską. Do produkcji używaj tagowanej wersji.\n\n### Alternatywa: Obraz Distroless (Mniejszy i Bezpieczniejszy)\n\nDla mniejszego, bardziej bezpiecznego obrazu (~300-500MB mniej):\n\n```bash\ndocker compose -f docker-compose.distroless.yml up -d\n```\n\nZobacz [DOCKER_BUILD_OPTIMIZATION.md](docs/DOCKER_BUILD_OPTIMIZATION.md) dla szczegółów.\n\n## 📚 Dokumentacja\n\n- **[USAGE_GUIDE.md](docs/USAGE_GUIDE.md)** - Kompletny przewodnik użycia (lokalnie i z Cursor)\n- **[QUICKSTART.md](docs/QUICKSTART.md)** - Szybki start w 5 minut\n- **[CURSOR_NPX_SETUP.md](docs/CURSOR_NPX_SETUP.md)** - Przewodnik konfiguracji Cursor (npx i Docker)\n- **[NPX_INSTALLATION.md](docs/NPX_INSTALLATION.md)** - Instalacja przez npx\n- **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - Struktura projektu\n- **[TEST_RESULTS_MCP.md](docs/TEST_RESULTS_MCP.md)** - Wyniki testów wszystkich narzędzi\n\n## 🛠️ Dostępne Narzędzia\n\n1. **generate_c4_diagram** - Diagramy architektury C4 (context, container, component, code)\n2. **generate_uml_diagram** - Diagramy UML (class, component, deployment, package, activity, usecase)\n3. **generate_sequence_diagram** - Diagramy sekwencji PlantUML\n4. **generate_flowchart** - Flowchart Mermaid\n5. **generate_mermaid_sequence** - Diagramy sekwencji Mermaid\n6. **generate_gantt** - Wykresy Gantta\n7. **generate_dependency_graph** - Grafy zależności Graphviz\n8. **generate_cloud_diagram** - Diagramy architektury chmurowej draw.io\n9. **export_to_pdf** - Eksport markdown do PDF\n10. **export_to_docx** - Eksport markdown do DOCX\n11. **create_document_from_template** - Dokumenty z szablonów (ADR, API Spec, C4, Microservices)\n\n## 📁 Struktura Projektu\n\n```\nMCPServer/\n├── src/              # Kod źródłowy serwera MCP\n├── scripts/          # Skrypty pomocnicze (mcp_client.py, install.sh)\n├── tests/            # Testy i pliki testowe\n├── docs/             # Dokumentacja projektu\n├── examples/         # Przykłady użycia\n└── output/           # Katalog wyjściowy (zmountowany w Docker)\n```\n\nSzczegóły: [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)\n\n## 💡 Przykłady Użycia\n\n### Lokalnie (bez Cursor)\n\n```bash\n# Z pliku\npython3 scripts/mcp_client.py -f examples/prompts/prompt.txt\n\n# Z linii komend\npython3 scripts/mcp_client.py -p \"Generate C4 context diagram for e-commerce. Save as output/diagram.png\"\n\n# Z stdin\ncat prompt.txt | python3 scripts/mcp_client.py\n```\n\n### Z Cursor\n\nDostępne są dwie metody instalacji:\n\n#### Metoda 1: Docker (Zalecane dla produkcji)\n\n1. Uruchom kontenery: `docker compose up -d`\n2. Skonfiguruj ustawienia MCP w Cursor:\n   ```json\n   {\n     \"mcpServers\": {\n       \"Documentation\": {\n         \"command\": \"docker\",\n         \"args\": [\n           \"exec\",\n           \"-i\",\n           \"mcp-documentation-server\",\n           \"sh\",\n           \"-c\",\n           \"cd /app/src \u0026\u0026 PYTHONPATH=/app/src python server.py\"\n         ],\n         \"env\": {\n           \"PYTHONPATH\": \"/app/src\"\n         }\n       }\n     }\n   }\n   ```\n3. Zrestartuj Cursor\n4. Użyj narzędzi MCP w konwersacji, np.:\n   - \"Wygeneruj C4 Context Diagram dla systemu e-commerce\"\n   - \"Utwórz UML Class Diagram z klasami User i Order\"\n\n#### Metoda 2: npx (Zalecane - Automatyczne zarządzanie Dockerem)\n\n1. Upewnij się, że Docker jest zainstalowany i uruchomiony\n2. Skonfiguruj ustawienia MCP w Cursor:\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-doc-generator\": {\n         \"command\": \"npx\",\n         \"args\": [\n           \"github:lukaszzychal/mcp-doc-generator#v0.1.7\"\n         ]\n       }\n     }\n   }\n   ```\n3. Zrestartuj Cursor\n4. Wrapper automatycznie zarządza kontenerami Docker - brak ręcznej konfiguracji!\n5. Użyj narzędzi MCP w konwersacji\n\n**Zobacz [CURSOR_NPX_SETUP.md](docs/CURSOR_NPX_SETUP.md) dla szczegółowych instrukcji konfiguracji.**\n\n## 🧪 Testy\n\n```bash\n# Testy wszystkich narzędzi MCP\npython3 tests/test_mcp_local.py\n\n# Test integracji z Cursor\n./tests/test_mcp_cursor_integration.sh\n\n# Podstawowe testy systemu\n./scripts/test.sh\n```\n\n## 📖 Więcej Informacji\n\n- [Przewodnik użycia](docs/USAGE_GUIDE.md) - Szczegółowe instrukcje\n- [Szybki start](docs/QUICKSTART.md) - Instalacja i konfiguracja\n- [Wyniki testów](docs/TEST_RESULTS_MCP.md) - Status wszystkich narzędzi\n- [Przykłady](examples/example_usage.md) - Przykłady użycia każdego narzędzia\n\n## 🔧 Wymagania\n\n### Dla instalacji npx (Zalecane)\n- **Node.js** \u003e= 14.0.0 (dla npx)\n- **Docker** i **Docker Compose** (automatycznie zarządzane)\n- **Docker demon** musi być uruchomiony\n\n### Dla bezpośredniej instalacji Docker\n- **Docker** i **Docker Compose**\n- Ręczne zarządzanie kontenerami\n\n### Opcjonalne\n- **Cursor** (dla integracji z IDE)\n\n## 📝 Licencja\n\nZobacz [LICENSE](LICENSE)\n\n## 💬 Społeczność i Wsparcie\n\n- **Dyskusje:** [GitHub Discussions](https://github.com/lukaszzychal/mcp-doc-generator/discussions)\n- **Zgłoszenia:** [GitHub Issues](https://github.com/lukaszzychal/mcp-doc-generator/issues)\n- **Kontakt:** lukasz.zychal.dev@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszzychal%2Fmcp-doc-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukaszzychal%2Fmcp-doc-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszzychal%2Fmcp-doc-generator/lists"}