MCP Documentation Server

MCP (Model Context Protocol) server for generating technical documentation with diagrams.

📢 Status: Serwer MCP jest obecnie testowany w pracy.

Language / Język: English | Polski

---

English

📢 Status: The MCP server is currently being tested in production at work.

🚀 Quick Start

# 1. Start Docker containers
docker compose up -d

# 2. Use MCP client with your own prompt
python3 scripts/mcp_client.py -f examples/prompts/prompt.txt

# 3. Or use in Cursor - open conversation and use MCP tools

📦 Installation via npx

You can install and run the server directly via npx without cloning the repository:

# Latest version from main branch
npx github:lukaszzychal/mcp-doc-generator

# Specific version (tag)
npx github:lukaszzychal/mcp-doc-generator#v0.1.3

# Specific branch
npx github:lukaszzychal/mcp-doc-generator#feat/test-npx-installation

Requirements:

• Node.js >= 14.0.0 (for npx)
• Docker and Docker Compose (automatically managed by wrapper)
• Docker daemon must be running

No local Python, Graphviz, Pandoc, or other tools required! Everything runs in Docker containers.

For detailed instructions, see NPX_INSTALLATION.md.

📦 Stable Release

Latest stable version: v0.1.3

For production use, we recommend using a tagged release:

# Clone specific version
git clone --branch v0.1.3 https://github.com/lukaszzychal/mcp-doc-generator.git

# Or checkout tag in existing repo
git checkout v0.1.3

Available releases:

• v0.1.3 - npx installation support, Cursor rules
• v0.1.2 - CI/CD optimizations, Docker caching improvements
• v0.1.1 - Previous stable release
• v0.1.0 - Initial release

Note: The main branch contains the latest development version. For production, use a tagged release.

Alternative: Distroless Image (Smaller & More Secure)

For a smaller, more secure image (~300-500MB smaller):

docker compose -f docker-compose.distroless.yml up -d

See DOCKER_BUILD_OPTIMIZATION.md for details.

📚 Documentation

• USAGE_GUIDE.md - Complete usage guide (locally and with Cursor)
• QUICKSTART.md - Quick start in 5 minutes
• CURSOR_NPX_SETUP.md - Cursor configuration guide (npx and Docker)
• NPX_INSTALLATION.md - Installation via npx
• PROJECT_STRUCTURE.md - Project structure
• TEST_RESULTS_MCP.md - Test results for all tools
• DOCKER_CONTAINERS_EXPLAINED.md - Docker containers usage explained

🛠️ Available Tools

1. generate_c4_diagram - C4 architecture diagrams (context, container, component, code)
2. generate_uml_diagram - UML diagrams (class, component, deployment, package, activity, usecase)
3. generate_sequence_diagram - PlantUML sequence diagrams
4. generate_flowchart - Mermaid flowcharts
5. generate_mermaid_sequence - Mermaid sequence diagrams
6. generate_gantt - Gantt charts
7. generate_dependency_graph - Graphviz dependency graphs
8. generate_cloud_diagram - draw.io cloud architecture diagrams
9. export_to_pdf - Markdown to PDF export
10. export_to_docx - Markdown to DOCX export
11. create_document_from_template - Documents from templates (ADR, API Spec, C4, Microservices)

📁 Project Structure

MCPServer/
├── src/              # MCP server source code
├── scripts/          # Helper scripts (mcp_client.py, install.sh, generate_examples.py)
├── tests/            # Tests and test files
├── docs/             # Project documentation
├── examples/         # Usage examples
└── output/           # Output directory (mounted in Docker)

Details: PROJECT_STRUCTURE.md

💡 Usage Examples

Locally (without Cursor)

# From file
python3 scripts/mcp_client.py -f examples/prompts/prompt.txt

# From command line
python3 scripts/mcp_client.py -p "Generate C4 context diagram for e-commerce. Save as output/diagram.png"

# From stdin
cat prompt.txt | python3 scripts/mcp_client.py

With Cursor

Two installation methods are available:

Method 1: Docker (Recommended for Production)

1. Start containers: docker compose up -d
2. Configure Cursor MCP settings:

   {
     "mcpServers": {
       "Documentation": {
         "command": "docker",
         "args": [
           "exec",
           "-i",
           "mcp-documentation-server",
           "sh",
           "-c",
           "cd /app/src && PYTHONPATH=/app/src python server.py"
         ],
         "env": {
           "PYTHONPATH": "/app/src"
         }
       }
     }
   }

3. Restart Cursor
4. Use MCP tools in conversation, e.g.:
   • "Generate C4 Context Diagram for e-commerce system"
   • "Create UML Class Diagram with User and Order classes"

Method 2: npx (Recommended - Automatic Docker Management)

1. Make sure Docker is installed and running
2. Configure Cursor MCP settings:

   {
     "mcpServers": {
       "mcp-doc-generator": {
         "command": "npx",
         "args": [
           "github:lukaszzychal/mcp-doc-generator#v0.1.3"
         ]
       }
     }
   }

3. Restart Cursor
4. The wrapper automatically manages Docker containers - no manual setup needed!
5. Use MCP tools in conversation

See CURSOR_NPX_SETUP.md for detailed configuration instructions.

🧪 Tests

# Tests for all MCP tools
python3 tests/test_mcp_local.py

# Cursor integration test
./tests/test_mcp_cursor_integration.sh

📖 More Information

• Usage guide - Detailed instructions
• Quick start - Installation and configuration
• Test results - Status of all tools
• Examples - Usage examples for each tool

🔧 Requirements

For npx Installation (Recommended)

• Node.js >= 14.0.0 (for npx)
• Docker and Docker Compose (automatically managed)
• Docker daemon must be running

For Direct Docker Installation

• Docker and Docker Compose
• Manual container management

Optional

• Cursor (for IDE integration)

📝 License

See LICENSE

---

Polski

MCP (Model Context Protocol) server do generowania dokumentacji technicznej z diagramami.

📢 Status: Serwer MCP jest obecnie testowany w pracy.

🚀 Szybki Start

# 1. Uruchom kontenery Docker
docker compose up -d

# 2. Użyj klienta MCP z własnym promptem
python3 scripts/mcp_client.py -f examples/prompts/prompt.txt

# 3. Lub użyj w Cursor - otwórz konwersację i użyj narzędzi MCP

📦 Instalacja przez npx

Możesz zainstalować i uruchomić serwer bezpośrednio przez npx bez klonowania repozytorium:

# Najnowsza wersja z gałęzi main
npx github:lukaszzychal/mcp-doc-generator

# Konkretna wersja (tag)
npx github:lukaszzychal/mcp-doc-generator#v0.1.3

# Konkretna gałąź
npx github:lukaszzychal/mcp-doc-generator#feat/test-npx-installation

Wymagania:

• Node.js >= 14.0.0 (dla npx)
• Docker i Docker Compose (automatycznie zarządzane przez wrapper)
• Docker demon musi być uruchomiony

Nie trzeba instalować Pythona, Graphviz, Pandoc ani innych narzędzi lokalnie! Wszystko działa w kontenerach Docker.

Szczegółowe instrukcje: NPX_INSTALLATION.md.

📦 Stabilna Wersja

Najnowsza stabilna wersja: v0.1.3

Do użycia produkcyjnego zalecamy użycie tagowanej wersji:

# Sklonuj konkretną wersję
git clone --branch v0.1.3 https://github.com/lukaszzychal/mcp-doc-generator.git

# Lub przełącz się na tag w istniejącym repo
git checkout v0.1.3

Dostępne wydania:

• v0.1.3 - Wsparcie instalacji npx, reguły Cursor
• v0.1.2 - Optymalizacje CI/CD, ulepszenia cache Docker
• v0.1.1 - Poprzednia stabilna wersja
• v0.1.0 - Wersja początkowa

Uwaga: Branch main zawiera najnowszą wersję deweloperską. Do produkcji używaj tagowanej wersji.

Alternatywa: Obraz Distroless (Mniejszy i Bezpieczniejszy)

Dla mniejszego, bardziej bezpiecznego obrazu (~300-500MB mniej):

docker compose -f docker-compose.distroless.yml up -d

Zobacz DOCKER_BUILD_OPTIMIZATION.md dla szczegółów.

📚 Dokumentacja

• USAGE_GUIDE.md - Kompletny przewodnik użycia (lokalnie i z Cursor)
• QUICKSTART.md - Szybki start w 5 minut
• CURSOR_NPX_SETUP.md - Przewodnik konfiguracji Cursor (npx i Docker)
• NPX_INSTALLATION.md - Instalacja przez npx
• PROJECT_STRUCTURE.md - Struktura projektu
• TEST_RESULTS_MCP.md - Wyniki testów wszystkich narzędzi

🛠️ Dostępne Narzędzia

1. generate_c4_diagram - Diagramy architektury C4 (context, container, component, code)
2. generate_uml_diagram - Diagramy UML (class, component, deployment, package, activity, usecase)
3. generate_sequence_diagram - Diagramy sekwencji PlantUML
4. generate_flowchart - Flowchart Mermaid
5. generate_mermaid_sequence - Diagramy sekwencji Mermaid
6. generate_gantt - Wykresy Gantta
7. generate_dependency_graph - Grafy zależności Graphviz
8. generate_cloud_diagram - Diagramy architektury chmurowej draw.io
9. export_to_pdf - Eksport markdown do PDF
10. export_to_docx - Eksport markdown do DOCX
11. create_document_from_template - Dokumenty z szablonów (ADR, API Spec, C4, Microservices)

📁 Struktura Projektu

MCPServer/
├── src/              # Kod źródłowy serwera MCP
├── scripts/          # Skrypty pomocnicze (mcp_client.py, install.sh)
├── tests/            # Testy i pliki testowe
├── docs/             # Dokumentacja projektu
├── examples/         # Przykłady użycia
└── output/           # Katalog wyjściowy (zmountowany w Docker)

Szczegóły: PROJECT_STRUCTURE.md

💡 Przykłady Użycia

Lokalnie (bez Cursor)

# Z pliku
python3 scripts/mcp_client.py -f examples/prompts/prompt.txt

# Z linii komend
python3 scripts/mcp_client.py -p "Generate C4 context diagram for e-commerce. Save as output/diagram.png"

# Z stdin
cat prompt.txt | python3 scripts/mcp_client.py

Z Cursor

Dostępne są dwie metody instalacji:

Metoda 1: Docker (Zalecane dla produkcji)

1. Uruchom kontenery: docker compose up -d
2. Skonfiguruj ustawienia MCP w Cursor:

   {
     "mcpServers": {
       "Documentation": {
         "command": "docker",
         "args": [
           "exec",
           "-i",
           "mcp-documentation-server",
           "sh",
           "-c",
           "cd /app/src && PYTHONPATH=/app/src python server.py"
         ],
         "env": {
           "PYTHONPATH": "/app/src"
         }
       }
     }
   }

3. Zrestartuj Cursor
4. Użyj narzędzi MCP w konwersacji, np.:
   • "Wygeneruj C4 Context Diagram dla systemu e-commerce"
   • "Utwórz UML Class Diagram z klasami User i Order"

Metoda 2: npx (Zalecane - Automatyczne zarządzanie Dockerem)

1. Upewnij się, że Docker jest zainstalowany i uruchomiony
2. Skonfiguruj ustawienia MCP w Cursor:

   {
     "mcpServers": {
       "mcp-doc-generator": {
         "command": "npx",
         "args": [
           "github:lukaszzychal/mcp-doc-generator#v0.1.3"
         ]
       }
     }
   }

3. Zrestartuj Cursor
4. Wrapper automatycznie zarządza kontenerami Docker - brak ręcznej konfiguracji!
5. Użyj narzędzi MCP w konwersacji

Zobacz CURSOR_NPX_SETUP.md dla szczegółowych instrukcji konfiguracji.

🧪 Testy

# Testy wszystkich narzędzi MCP
python3 tests/test_mcp_local.py

# Test integracji z Cursor
./tests/test_mcp_cursor_integration.sh

# Podstawowe testy systemu
./scripts/test.sh

📖 Więcej Informacji

• Przewodnik użycia - Szczegółowe instrukcje
• Szybki start - Instalacja i konfiguracja
• Wyniki testów - Status wszystkich narzędzi
• Przykłady - Przykłady użycia każdego narzędzia

🔧 Wymagania

Dla instalacji npx (Zalecane)

• Node.js >= 14.0.0 (dla npx)
• Docker i Docker Compose (automatycznie zarządzane)
• Docker demon musi być uruchomiony

Dla bezpośredniej instalacji Docker

• Docker i Docker Compose
• Ręczne zarządzanie kontenerami

Opcjonalne

• Cursor (dla integracji z IDE)

📝 Licencja

Zobacz LICENSE