# Home **Source Path:** `index.md` **Canonical URL:** https://jarakube.eu/ **Markdown URL:** /index.md # Jaraco GmbH Jaraco GmbH is a software engineering company in Muenster, Germany. Originally founded as Jan Radon Software Engineering in 11/2011, we became Jan Radon Consulting GmbH in 08/2019, and were renamed to Jaraco GmbH in 02/2022. We help organizations turn unclear software, workflow, and automation needs into practical systems that teams can operate and extend. With 22+ completed projects, we deliver experienced engineering support. ## What We Do - **Software development** for internal tools, business systems, and digital workflows (Python, Kubernetes, and cloud-native technologies). - **Consulting** for technical clarity, project scoping, modernization planning, and implementation decisions. - **IT architecture** for reliable foundations that can grow with the organization. - **Linux and open-source consulting** for practical migrations and maintainable operations. - **Code review support** when review capacity blocks delivery. - **Technology assessment and partner selection** for organizations that need a realistic path from problem to implementation. ## Featured Focus Areas | Focus Area | Description | Key Benefit | |------------|-------------|-------------| | [Jarakube](/jarakube/jarakube.md) | Kubernetes-based platform for sovereign application, data, automation, and local AI services | Controlled, practical delivery | | [Start your PoC](/start-poc/start-poc.md) | Focused proof-of-concept engagement for manual work, unclear workflows, or software bottlenecks | Reduced uncertainty, clear next steps | | [Partner Network](/partner/partner.md) | Collaboration model for stable and practical AI and automation solutions | Sustainable, stable solutions | | [Pricing](/pricing/pricing.md) | How Jaraco scopes work and discusses pricing | Transparent, individualized approach | | [MCP Server](/mcp-server/mcp-server.md) | Structured access to website content for tools and agents | Programmatic access, automation-ready | ## Services | Service | Description | Focus Areas | |---------|-------------|-------------| | [Software Development](/services/software-development.md) | Custom software for internal tools and business systems | Python, Kubernetes, Cloud-Native | | [Consulting](/services/consulting.md) | Technical clarity and project scoping | Modernization, Implementation | | [IT Architecture](/services/it-architecture.md) | Reliable foundations for growth | Scalability, Maintainability | | [Linux consulting and migration](/services/linux-consulting.md) | Practical migrations and operations | Open Source, Maintainability | | [Code Review](/services/code-review.md) | Support when review capacity blocks delivery | Quality, Best Practices | | [Technical assessment and partner selection](/services/technology-assessment.md) | Realistic path from problem to implementation | Vendor Selection, Feasibility | ## Project Stories - [Fewer delays in daily operations](/stories/operations-workflow-automation.md) - [Modernising a business-critical platform](/stories/platform-modernisation.md) ## Contact - Email: info@jaraco.de - Phone: +49 176 85952637 - Imprint: /impressum.md - Privacy policy: /datenschutzerklaerung.md --- # Blog Overview **Source Path:** `blog.md` **Canonical URL:** https://jarakube.eu/blog.html **Markdown URL:** /blog.md # Blog Practical articles from Jaraco GmbH about software engineering, automation, architecture, Linux, AI-assisted delivery, and operational modernization. ## Articles - [Jaraco Bills -- An AI-Generated Invoice Management System](/blogs/jaraco-bills.md) - [A practical roadmap for workflow automation](/blogs/practical-automation-roadmap.md) - [Modernizing legacy systems without a big-bang rewrite](/blogs/modernize-without-big-bang.md) - [A Strong 2024 in Review: Three Standout Projects](/blogs/2024-project-highlights.md) - [Citizen Development - Efficiency Gain or Security Risk?](/blogs/citizen-development-effizienz-oder-risiko.md) - [From Data Silos to Knowledge Sources](/blogs/from-data-silos-to-knowledge-sources.md) - [From Data Chaos to Efficient Automation: What AI Really Needs](/blogs/from-data-chaos-to-efficient-automation.md) - [Agile but Silent? How Poor Communication Slows Agile Teams](/blogs/agile-but-silent-how-poor-communication-slows-teams.md) - [Keeping dependencies up to date without burning developer time](/blogs/keeping-dependencies-up-to-date-without-burning-developer-time.md) - [Jaraco Reader - A Mobile Linux Reader for Markdown with Mermaid and EPUB](/blogs/jaraco-reader.md) - [AI PR Autofix: A Practical Approach to Dependency Update Automation](/blogs/ai-pr-autofix.md) --- # Services Overview **Source Path:** `project.md` **Canonical URL:** https://jarakube.eu/project.html **Markdown URL:** /project.md # Services Jaraco GmbH supports organizations that need practical software delivery, clear architecture, automation, and technical guidance. This page is the Markdown overview for the service area. ## Service Pages - [Software Development](/services/software-development.md): Build digital tools and business software that make everyday work easier, faster, and more reliable. - [Consulting](/services/consulting.md): Turn unclear software, process, or automation initiatives into realistic next steps. - [IT Architecture](/services/it-architecture.md): Design foundations behind software and automation so systems stay reliable as teams and operations become more complex. - [Linux consulting and migration](/services/linux-consulting.md): Move servers, desktops, and processes toward Linux and open-source software in a practical way. - [Code Review](/services/code-review.md): Add professional review capacity for programming languages, backend services, and internal tools. - [Technical assessment and partner selection](/services/technology-assessment.md): Analyze processes, assess technical options, and identify suitable implementation partners. --- # Stories Overview **Source Path:** `story.md` **Canonical URL:** https://jarakube.eu/story.html **Markdown URL:** /story.md # Project Stories Short project examples showing how software, architecture, and automation can improve day-to-day operations. ## Stories - [Fewer delays in daily operations](/stories/operations-workflow-automation.md): An operations team reduced repetitive coordination work that slowed approvals and service requests. - [Modernising a business-critical platform](/stories/platform-modernisation.md): A staged modernization path for an older internal platform that still mattered to daily work. --- # Imprint **Source Path:** `impressum.md` **Canonical URL:** https://jarakube.eu/impressum.html **Markdown URL:** /impressum.md # Imprint Information according to Section 2 DDG. ## Jaraco GmbH Friedrich-Ebert-Str. 137 48153 Muenster Germany Managing Director: Jan Radon Shareholder: Jan Radon ## Contact Phone: +49 176 85952637 Email: info@jaraco.de VAT ID: DE326248102 ## Commercial Register Entry Register court: Amtsgericht Muenster Registration number: HRB 18133 ## Responsible For Content Responsible according to Section 18 MStV: Jan Radon ## Privacy When contacting Jaraco GmbH using the details above, the privacy policy applies: /datenschutzerklaerung.md --- # Privacy Policy **Source Path:** `datenschutzerklaerung.md` **Canonical URL:** https://jarakube.eu/datenschutzerklaerung.html **Markdown URL:** /datenschutzerklaerung.md # Privacy Policy Status: October 2024. This Markdown page summarizes how personal data is handled on the Jaraco GmbH website. The HTML page contains localized browser-facing text; this Markdown route gives AI agents a clean text representation. ## Controller Jaraco GmbH Friedrich-Ebert-Str. 137 48153 Muenster Germany Phone: +49 176 85952637 Email: datenschutz@jaraco.de ## Personal Data Personal data is information relating to an identified or identifiable natural person, such as name, address, phone number, or email address. ## Website Access Data When the website is visited, technical data can be transmitted to the server for operational reasons. This can include IP address, date and time of access, browser type and version, operating system, referring page, requested page, access status, and transferred data volume. This information is used to display the website correctly and to maintain stability and security. ## Contact When a person contacts Jaraco GmbH by email, post, or telephone, the voluntarily supplied data is stored to process the request. Data is deleted when it is no longer required unless statutory retention obligations apply. ## Cookies And Analytics The website may use cookies and analytics functions to improve usability and understand usage. Browser settings can be used to restrict or delete cookies. ## Rights Data subjects have rights under the GDPR, including access, rectification, erasure, restriction of processing, data portability, objection, withdrawal of consent, and the right to lodge a complaint with a data protection supervisory authority. ## Related Legal Page Imprint: /impressum.md --- # Service: Code-Review **Source Path:** `services/code-review.md` **Canonical URL:** https://jarakube.eu/services/code-review.html **Markdown URL:** /services/code-review.md # Code Review We offer professional code review for common programming languages, backend services, and internal tools when review capacity becomes a delivery bottleneck. ## What we review - Backend services and APIs - Internal business tools and automation code - Changes in common programming languages used in product and platform teams - Generated or AI-assisted code before it reaches production workflows ## Why companies use this service Code review is often where delivery slows down. Teams need fast feedback, but they also need experienced judgement on maintainability, correctness, security, and operational risk. The rise of generated code has made that tension more visible. More code can be produced quickly, but that does not remove the need for careful review. In many teams it increases the need for reviewers who can identify unclear assumptions, fragile implementation details, and avoidable long-term complexity. ## Benefits for teams and organisations - Shorter review queues when internal senior capacity is limited - More consistent feedback on maintainability, reliability, and architecture quality - Earlier detection of risks in generated code, integrations, and operational tooling - Better support for developers who need practical, reviewable guidance instead of generic comments - Reduced pressure on lead engineers and principal developers during high-delivery phases ## Experience and perspective Our review work is informed by years of software engineering across different roles, domains, and industries. That includes implementation, architecture, consulting, operations-facing work, and delivery in environments with different technical and business constraints. This helps us review code in context, not just against abstract style rules. We focus on whether the change is understandable, dependable, and realistic to operate and extend over time. ## Let’s reduce review bottlenecks If code reviews are slowing delivery, we can support your team with professional external review capacity and pragmatic technical feedback. --- # Service: Consulting **Source Path:** `services/consulting.md` **Canonical URL:** https://jarakube.eu/services/consulting.html **Markdown URL:** /services/consulting.md # Consulting We help decision makers turn unclear software, process, or automation initiatives into realistic next steps. ## What we help with - Assessing software, workflow, and automation opportunities - Defining realistic automation priorities - Clarifying requirements between business and implementation teams - Supporting change during growth, restructuring, or operational pressure ## Typical support Our consulting work is practical and business-aware. We help organisations make better decisions before budgets are committed and before teams lose time on the wrong solution. ## How we work We focus on clear recommendations, visible tradeoffs, and measures that can actually be implemented. Advice is only useful when it creates better outcomes in daily operations. --- # Service: It-Architecture **Source Path:** `services/it-architecture.md` **Canonical URL:** https://jarakube.eu/services/it-architecture.html **Markdown URL:** /services/it-architecture.md # IT Architecture We design the foundations behind software and automation so systems stay reliable as teams and internal operations become more complex. ## What we design - System structures for growing organisations - Integrations between tools, platforms, and data sources - Reliable foundations for business-critical automation - Improvement paths for software that has become difficult to change ## Typical support We help when software no longer fits the organisation, when automation depends on fragile workarounds, or when important business processes need more dependable foundations. ## How we work We keep architecture close to business reality. The aim is not complexity for its own sake, but structures that reduce risk, improve clarity, and support stable growth. --- # Service: Linux-Consulting **Source Path:** `services/linux-consulting.md` **Canonical URL:** https://jarakube.eu/services/linux-consulting.html **Markdown URL:** /services/linux-consulting.md # Linux consulting and migration We support companies that want to move servers, desktops, and internal processes to Linux and open-source software in a practical and maintainable way. ## What we support - Migration of servers and desktop environments to Linux - Evaluation and introduction of suitable open-source alternatives - Transition planning for internal tools, workflows, and operating models - Practical support for teams during rollout, adaptation, and handover ## Why companies choose this path Many organisations want to reduce software lock-in, use hardware for longer, and gain more control over their operating environment. A Linux and open-source strategy can help lower dependency on individual vendors while improving transparency and flexibility. ## Benefits for teams and organisations - Longer and more efficient use of existing hardware - More control over operating systems, software choices, and update cycles - Better alignment with open standards and interoperable tooling - Reduced dependency on closed vendor ecosystems where that matters strategically - A clearer basis for stable, maintainable internal infrastructure ## How we work We treat migration as an operational and organisational change, not just a technical swap. The goal is to create a realistic transition path that fits the systems you already run, the people who depend on them, and the processes that need to keep working every day. --- # Service: Software-Development **Source Path:** `services/software-development.md` **Canonical URL:** https://jarakube.eu/services/software-development.html **Markdown URL:** /services/software-development.md # Software Development We build digital tools and business software that make everyday work easier, faster, and more reliable. ## What we deliver - Business applications and internal platforms - Custom workflow and process software - Automation for recurring manual processes - Modernisation of outdated software and workflows ## Typical support We are brought in when companies want to replace spreadsheets, manual coordination, or fragmented tools with software that supports real business processes. ## How we work We focus on practical outcomes, clear interfaces, and maintainable implementation. The goal is software that supports staff, saves time, and remains dependable as the business grows. --- # Service: Technology-Assessment **Source Path:** `services/technology-assessment.md` **Canonical URL:** https://jarakube.eu/services/technology-assessment.html **Markdown URL:** /services/technology-assessment.md # Technical assessment and partner selection We analyse your existing processes as a whole and support you with a well-founded technical assessment. Based on that, we identify and introduce suitable partners who can support the development and implementation of the best solution. ## What we support - End-to-end analysis of existing processes and system landscapes - Technical assessment of requirements, options, and dependencies - Identification of suitable delivery partners for your initiative - Support during selection, alignment, and handover ## What matters to us We act fully independently in both technology choices and partner selection. Our focus is solely on the best possible solution for your business. ## How we work As a neutral technical sparring partner, we support you across all project phases, from the first analysis through concept work to successful delivery. --- # Story: Operations Workflow Automation **Source Path:** `stories/operations-workflow-automation.md` **Canonical URL:** https://jarakube.eu/stories/operations-workflow-automation.html **Markdown URL:** /stories/operations-workflow-automation.md # Fewer delays in daily operations An operations team wanted to reduce repetitive coordination work that was slowing down approvals and service requests. ## Situation Requests moved through email threads and ad hoc messages, which made ownership unclear and status tracking unreliable. ## What we changed We introduced a business-focused workflow application with clear steps, status visibility, and automation for routine notifications and escalations. ## Result The team gained a calmer process, better turnaround times, and less manual follow-up work. --- # Story: Platform Modernisation **Source Path:** `stories/platform-modernisation.md` **Canonical URL:** https://jarakube.eu/stories/platform-modernisation.html **Markdown URL:** /stories/platform-modernisation.md # Modernising a business-critical platform A company relied on an older internal platform that still mattered to daily work but had become difficult to extend safely. ## Situation Each change carried risk, documentation was thin, and the team needed a clearer technical direction before investing further. ## What we changed We clarified the architecture, reduced unnecessary complexity, and created a practical roadmap for staged improvements without interrupting day-to-day operations. ## Result The platform became easier to maintain and the business gained a more realistic basis for future automation and growth. --- # Blog: Jaraco Bills **Source Path:** `blogs/jaraco-bills.md` **Canonical URL:** https://jarakube.eu/blogs/jaraco-bills.html **Markdown URL:** /blogs/jaraco-bills.md # Jaraco Bills -- An AI-Generated Invoice Management System In recent weeks, we developed an exciting prototype with AI assistance: **Jaraco Bills**. Our goal was to improve and redesign one of our business processes using modern prompt-driven development and AI technologies. ## From Idea to Application -- With Prompt Engineering We started with a specific challenge: We needed an e-invoicing tool that works simply for us -- without unnecessary complexity, but with the necessary features to make our invoice data analyzable with AI. However, what we found was either **too bloated**, **too expensive**, or **so minimalistic** that it didn't meet our requirements. So we made a decision: **We would build our own tool. With the help of GenAI.** Thus, **Jaraco Bills** was born -- an AI-generated frontend and backend that allowed us to evaluate the new tools and possibilities offered by GenAI. The project demonstrates how modern prompt-driven development and AI technologies can together create a practical system. The **frontend was developed with bold.new** -- exclusively through **prompt engineering**. In designing the UI, our focus was on supporting our own workflow. We wanted software that ideally reflects our process and is easy for our employees to use. Another goal was to **make invoice data analyzable with AI** -- for this, a **chatbot** was integrated that can communicate with a **self-hosted LLM**. Of course, the application should be modern and work **reliably and user-friendly on as many devices as possible**. The backend was created with the help of **Claude Code (Anthropic)** based on a **Spring Boot Kotlin backend template** that contains our code guidelines and architectural specifications. ## What We Learned ### The Importance of a Good Base Project The base project is crucial. It not only provides the technical framework (e.g., logging, error handling, structure, code-first), but also the context in which the AI can work. Using a minimalistic, well-documented base project has the advantage that the generated service aligns with existing services that contain code guidelines and best practices. This makes it easier for developers to understand and further develop the generated solution. ### Code Review & Git Synchronization AI-generated code also needs reviews -- not just for syntax, but also for architecture, security, and maintainability. Using Git allows us to cleanly track the AI's changes and manually correct or improve them. ### Prompt Engineering with Care A recurring pain point: **context size**. Especially with extensive code, prompts must be designed to remain **token-efficient**. This means: relevant imports, minimal but understandable descriptions, focus on individual functions. In particular, **refactoring generated code** often reached the limits of bold.new. For example, renaming variables was often not performed correctly. This is particularly problematic when using **TypeScript** and **JSON**, as such errors often only become apparent during testing or runtime. ### Meaningful Tests Good code is only half the battle -- we also need meaningful tests. The question arises: **How do you automatically test AI-generated code?** Here, too, the right setup is crucial: realistic test data, clear expectations, and a focus on central logic paths. ## Next Steps - **Evaluate AI-assisted testing** -- Can Claude & Co. also support us in test generation? What other tools are available, and how do we integrate them meaningfully into the development process with GenAI? - **Refine the base project** -- The more robust the template, the better the results. Can better results be achieved through **hidden prompts**? - **Build deployment pipelines** -- From generation to rollout: automated and traceable. For this, we are evaluating, among other things: **separate DevOps repo vs. K8s templates in the project**, as well as **Helm or Kustomize?** - **Improve context handling** -- e.g., through **code splitting** or **RAG (Retrieval-Augmented Generation)**, so that large projects also fit into AI context windows. - **Add missing functionality** -- such as the **integration of Keycloak** for role-based authentication and the **provision of an MCP server** to connect the invoicing functionality and provide structured data for **simple interaction via the LLM**. ## Conclusion & Call to Action **Jaraco Bills** is more than just a showcase for us. It is practical proof that **prompt-driven development, AI, and DevOps** can work successfully together. We are at the beginning of an exciting development! If you are interested in **adapting software to your processes** -- instead of adapting your processes to the software: **Contact us** for an individual, free initial consultation -- or test **Jaraco Bills** yourself! Inquiries to info@jaraco.de. --- # Blog: Practical Automation Roadmap **Source Path:** `blogs/practical-automation-roadmap.md` **Canonical URL:** https://jarakube.eu/blogs/practical-automation-roadmap.html **Markdown URL:** /blogs/practical-automation-roadmap.md # A practical roadmap for workflow automation Automation does not need to start with a large programme. Most teams get better results by starting with one workflow that creates immediate operational value. ## Start where manual effort is visible Pick a process where teams copy information across systems, chase updates by email, or repeat the same status tasks every week. ## Define one measurable improvement Set a clear first objective such as shorter response time, fewer handoffs, or fewer manual data transfers. Keep the scope narrow enough to deliver quickly. ## Build around existing tools first Use current systems as the baseline and automate the steps between them. This reduces friction and helps teams adopt the change without disruption. ## Decide based on outcomes After the first workflow is running, review what improved and where limits remain. Then decide whether to scale, redesign, or stop before investing further. --- # Blog: Modernize Without Big Bang **Source Path:** `blogs/modernize-without-big-bang.md` **Canonical URL:** https://jarakube.eu/blogs/modernize-without-big-bang.html **Markdown URL:** /blogs/modernize-without-big-bang.md # Modernizing legacy systems without a big-bang rewrite Replacing a platform all at once is high risk for most organizations. A staged modernization path is usually faster, safer, and easier to govern. ## Separate critical flows first Identify business-critical workflows and isolate them from low-impact components. This keeps migration effort focused where reliability matters most. ## Introduce integration boundaries Use clear APIs or event contracts between old and new components. Strong boundaries reduce coupling and make incremental rollout possible. ## Deliver in short cycles Ship small production-ready increments with explicit rollback options. Frequent delivery exposes risks earlier and helps teams align technical and business decisions. ## Keep operations in the loop Modernization succeeds when support and operations teams are included from day one. Monitoring, ownership, and runbooks should evolve with each increment. --- # Blog: 2024 Project Highlights **Source Path:** `blogs/2024-project-highlights.md` **Canonical URL:** https://jarakube.eu/blogs/2024-project-highlights.html **Markdown URL:** /blogs/2024-project-highlights.md # A Strong 2024 in Review: Three Standout Projects In 2024, we helped clients across banking, energy, and insurance modernize critical systems while keeping day-to-day operations stable. This recap highlights three projects where architecture, delivery discipline, and close collaboration produced measurable progress. ## Project 1: Cloud Migration in Banking ### Challenge A banking client asked us to migrate a core platform with more than 30 services to an on-prem OpenShift cloud. The legacy landscape and existing deployment process had to remain fully operational throughout the migration, while feature work continued in parallel. ### Our Approach We started with a detailed assessment of the legacy services and deployment flow, then defined a phased migration plan with the client. The priority was predictable cutovers, minimal disruption, and clear ownership between teams during each transition step. ### Outcome After 2.5 years of close collaboration, all services were migrated successfully. We also modernized development and deployment workflows, upgraded technical foundations, and delivered a stable, scalable platform for around 130,000 users. ### What Comes Next With the migration completed, our engagement in this stream has concluded. We thank the client team for the strong partnership and wish them continued success in their digital transformation. ## Project 2: Post-Merger IT Integration in Energy ### Challenge Following a merger, an energy client needed to consolidate heterogeneous IT systems. A major risk was a set of long-running interfaces that had limited documentation and had historically been maintained by a single expert who had retired. ### Our Approach Our engineers reconstructed interface behavior and history, stabilized operations, documented key processes, and implemented targeted adjustments to prepare systems for migration into the group landscape. ### Outcome The interfaces were migrated without compromising operational stability. This created an important foundation for broader IT consolidation and modernization. ### What Comes Next In 2025, we continue supporting modernization of legacy components with the goal of building a scalable, future-ready software landscape. ## Project 3: Process Optimization in Insurance ### Challenge An insurance client aimed to increase delivery efficiency and long-term resilience by introducing standardized CI/CD pipelines, stronger quality controls, modern event-driven integration, and practical AI usage in development. ### Our Approach We supported implementation of CI/CD pipelines, advised on scalable event-streaming architecture, optimized engineering workflows, and delivered proof-of-concepts for quality and productivity improvements. ### Outcome The client established consistent pipelines and launched initial scalable event-streaming solutions. Engineering and operations became more efficient, and service coupling was reduced. ### What Comes Next In 2025, we will deepen process improvements, expand event-streaming adoption, and increase applied AI support in development and testing. ## Conclusion These projects reflect our commitment to sustainable outcomes, not just technical delivery. We appreciate our clients' trust and the results we achieved together. ## Your Project, Our Expertise If you face similar challenges, we can support you from strategy through implementation. Contact us to discuss your goals. --- # Blog: Citizen Development Effizienz Oder Risiko **Source Path:** `blogs/citizen-development-effizienz-oder-risiko.md` **Canonical URL:** https://jarakube.eu/blogs/citizen-development-effizienz-oder-risiko.html **Markdown URL:** /blogs/citizen-development-effizienz-oder-risiko.md # Citizen Development - Efficiency Gain or Security Risk? Citizen Development describes the practice of employees outside the IT department building their own applications and automations with little or no programming experience. This is enabled by low-code and no-code platforms that offer drag-and-drop components. The goal is simple: business teams can implement ideas faster because the people closest to the process know best what is needed. ## Benefits and challenges Citizen Development can accelerate business outcomes, but it requires clear guardrails. ### Benefits - Faster innovation with shorter time-to-market - Reduced workload for IT teams on smaller solutions - Lower development effort and reduced external costs - Higher motivation through ownership in business departments ### Challenges - Shadow IT without central governance and security controls - Limited scalability and maintainability of many solutions - Fragmented IT landscapes without shared standards - Error-prone implementations when development knowledge is missing ## Where it already works in practice Citizen Development is already established across industries: - Insurance teams build applications for customer support and process automation. - Manufacturing and logistics teams digitize production workflows, optimize material flows, and create custom dashboards. ## Conclusion: use the potential responsibly Citizen Development can speed up digital transformation, strengthen innovation, and reduce costs. To make that sustainable, organizations need governance, training, and close collaboration with IT. ### What successful implementation needs - Clear policies for tools, platforms, and integration standards - Training on methods, security, and practical best practices - Strong IT collaboration for architecture, support, and scaling - Quality assurance through reviews and testing - Early assessment of long-term technical sustainability ## How we support you If you want to establish Citizen Development in your organization, we can support you from strategy to implementation and help you avoid typical risks early. --- # Blog: From Data Silos To Knowledge Sources **Source Path:** `blogs/from-data-silos-to-knowledge-sources.md` **Canonical URL:** https://jarakube.eu/blogs/from-data-silos-to-knowledge-sources.html **Markdown URL:** /blogs/from-data-silos-to-knowledge-sources.md # From Data Silos to Knowledge Sources Every day, companies create large volumes of data from invoices, emails, CRM systems, time tracking, and support tickets. Most of that data stays spread across disconnected tools, which turns valuable knowledge into isolated fragments. ## Data lake and data mesh as the foundation To unlock this potential, organizations need a clear data architecture. - A data lake centralizes structured and unstructured data in raw form. - A data mesh assigns domain ownership, so business teams manage their own data products with clear responsibility and quality. Combined, both models provide reliable and current data for AI workloads. ## LLMs and SLMs: broad capability plus precision LLMs are strong general-purpose language models that support writing, summarization, contextual email handling, and code or report generation. SLMs are specialized models trained for specific domains where accuracy is critical, such as technical diagnostics, internal knowledge systems, or clinical documentation. Using both together gives companies flexibility and precision at the same time. ## Agentic AI: from reading information to executing work AI agents use LLMs and SLMs to retrieve company data and complete tasks autonomously. - Invoice matching against ERP purchase orders and payment terms - Automated customer support responses grounded in CRM and wiki data - Project controlling with early risk signals from budget and milestone data - Onboarding support tailored to each role across HR and internal tools This turns AI from a passive assistant into an operational teammate. ## Local hosting or external hosting Local hosting offers stronger data sovereignty, compliance control, model customization, and often lower latency for internal workflows. External cloud hosting is faster to start and easier to scale, but can add privacy concerns, lock-in risk, and less control over adaptation. For sensitive use cases, local deployment is often the more sustainable strategy. ## Conclusion Organizations that combine local AI models, robust data architecture, and agent-based automation gain faster decisions, better efficiency, and a real innovation advantage. If you want to consolidate data sources and deploy practical AI agents, jaraco gmbh can support your team from architecture to implementation. --- # Blog: From Data Chaos To Efficient Automation **Source Path:** `blogs/from-data-chaos-to-efficient-automation.md` **Canonical URL:** https://jarakube.eu/blogs/from-data-chaos-to-efficient-automation.html **Markdown URL:** /blogs/from-data-chaos-to-efficient-automation.md # From Data Chaos to Efficient Automation: What AI Really Needs Artificial intelligence promises a lot, especially for process automation. Many companies expect AI to just work, detect complex patterns, and optimize workflows automatically. In practice, this often misses one key reality: even agentic AI needs a reliable foundation. ## The expectation: order from data chaos Most organizations have large amounts of data across multiple systems, formats, and quality levels. The common expectation is that AI will analyze this chaos, create structure, and make better decisions. This can work, but only if the data is accessible, consistent, and structured enough to support meaningful interpretation. ## Agentic AI needs context Agentic AI goes beyond rule-based automation. It is expected to detect, prioritize, and execute actions with minimal supervision. For that to happen, the system must understand what to do, why to do it, and when to do it. If data is incomplete, contradictory, or lacking context, even advanced models become unreliable. ## Not every process needs AI Another common misconception is that every workflow should be AI-driven. In many cases, clear process design, simple automation tools, and rule-based workflows already deliver strong efficiency gains. AI is most valuable where conventional automation reaches its limits, such as unstructured information, complex decision paths, or adaptive operations. ## Data quality is the decisive factor Successful AI automation starts with disciplined data management. Companies should focus on: - Structured data formats and clean source systems - Complete and maintained records without critical gaps - Consistent field names, values, and classifications - Up-to-date datasets for operational decision-making - Clear business context behind each data point - Reliable access through APIs or centralized data platforms Without this foundation, AI becomes expensive experimentation instead of productive automation. ## Conclusion AI-based automation is not plug-and-play. It is a strategic initiative that starts with data quality, process clarity, and realistic use-case selection. If you want AI to deliver measurable results in your organization, jaraco can help you assess your current data landscape and define the right path to implementation. --- # Blog: Agile But Silent How Poor Communication Slows Teams **Source Path:** `blogs/agile-but-silent-how-poor-communication-slows-teams.md` **Canonical URL:** https://jarakube.eu/blogs/agile-but-silent-how-poor-communication-slows-teams.html **Markdown URL:** /blogs/agile-but-silent-how-poor-communication-slows-teams.md # Agile but Silent? How Poor Communication Slows Agile Teams Agile methods promise faster decisions and better ownership, but without clear communication they often create hidden friction and costly delays. ## The quiet risk inside agile teams Many teams run stand-ups, retrospectives, and board updates, yet still avoid discussing uncertainty, overlaps, or blocked work. Critical issues stay unspoken until they become delivery problems. ## Self-organization is not self-isolation A common misunderstanding is that self-organization means everyone should handle everything alone. In reality, teams need explicit communication habits so questions, doubts, and trade-offs appear early. In international teams, this challenge can be even stronger. Direct and indirect communication styles differ, so feedback is sometimes misread as conflict or ignored as optional. ## Why communication breaks down - Unclear expectations about what should be shared and when - Cultural differences in communication and feedback style - Rituals that became routine and no longer create real dialogue - Operational overload that leaves no room for reflection ## Practical ways out of the communication trap ## 1) Define transparent communication rules Clarify what belongs in stand-ups, what should go to async channels, and what must be escalated quickly. Clear rules reduce hesitation. ## 2) Favor mentoring over micromanagement New or reserved team members benefit from trusted contacts who listen, coach, and encourage discussion before risks escalate. ## 3) Build psychological safety Teams perform better when mistakes, uncertainty, and disagreement can be expressed without penalty. Leaders shape this environment every day. ## 4) Make cultural patterns visible Short workshops on communication styles help teams interpret behavior better and avoid false assumptions in cross-cultural collaboration. ## 5) Add communication rituals for unresolved issues A weekly red-flag session gives everyone space to raise open concerns without immediate judgment and with shared ownership for next steps. ## Conclusion Communication is not a side topic in agile work. It is the operating system behind feedback, speed, and trust. If your team wants to improve collaboration and delivery reliability, jaraco can help you assess communication patterns and implement practical improvements. --- # Blog: Keeping Dependencies Up To Date Without Burning Developer Time **Source Path:** `blogs/keeping-dependencies-up-to-date-without-burning-developer-time.md` **Canonical URL:** https://jarakube.eu/blogs/keeping-dependencies-up-to-date-without-burning-developer-time.html **Markdown URL:** /blogs/keeping-dependencies-up-to-date-without-burning-developer-time.md # Keeping dependencies up to date without burning developer time Dependency updates are critical, but manual follow-up can consume more time than most teams expect. ## The hidden work starts after the PR Dependabot opens pull requests reliably, but the real effort starts after that: triage, fixing builds, adapting code, rerunning tests, and merging safely. ## A controlled automation approach Our `ai-pr-autofix` workflow is designed for repeatable maintenance work: - discovers and prioritizes open Dependabot pull requests - runs builds and tests deterministically - attempts controlled AI-based fixes when needed - documents every step with comments, labels, and policies ## Strong tests make automation safe This is not blind full automation. It is controlled automation that depends on test quality. When tests are strong, automation becomes a reliable scaling lever for security and maintenance. ## What teams gain - less manual triage effort - faster security and compatibility fixes - fewer context switches - more time for product and architecture work Dependency maintenance does not disappear, but it can be significantly accelerated. If you want to build fully automated maintenance pipelines like this, jaraco can help. --- # Blog: Jaraco Reader **Source Path:** `blogs/jaraco-reader.md` **Canonical URL:** https://jarakube.eu/blogs/jaraco-reader.html **Markdown URL:** /blogs/jaraco-reader.md # Jaraco Reader – A Mobile Linux Reader for Markdown with Mermaid and EPUB Anyone who reads on Linux knows the problem: Many Markdown and EPUB readers work really well on the desktop, but they quickly become cumbersome on mobile devices. This is exactly why we developed `jaraco-reader`. The idea was clear: A reader that runs cleanly on postmarketOS, renders Markdown documents including Mermaid diagrams, and makes EPUB books easily readable without forcing desktop workflows on smartphones. ## Why This Project Came to Be Existing readers are often optimized for desktop use: - Large window logic instead of touch-first operation - Unclear navigation on smaller displays - Weak support for technical Markdown content with diagrams `jaraco-reader` was therefore built as a pragmatic mobile solution. The goal was not a theoretical showcase, but a tool that allows you to actually read technical documents and books in everyday life. The core motivation in one sentence: This reader project was developed because existing Markdown and EPUB readers work excellently in desktop mode, but not as well on mobile devices. That's why we built `jaraco-reader` to make Markdown documents with Mermaid diagrams and EPUB books significantly easier to read. ## Project Overview: How `jaraco-reader` Works The application is based on GTK3 + WebKit2GTK 4.1 and uses Python as the runtime. This combines native app control with robust HTML/CSS rendering. What the reader specifically does: - EPUB content is unpacked, chapters are merged, and displayed as a continuous reading page. - Markdown is converted to HTML, including fenced code blocks, tables, and content structure. - Mermaid blocks are automatically detected and rendered as diagrams. - Images and relative assets are resolved correctly. - Reading position and font size are saved per book and restored when reopened. ## Important Features for Mobile Use To make the reader truly practical on a smartphone, simple, direct interactions were deliberately implemented: - Edge buttons for quick page forward/backward - Go-to-page dialog for direct jumps - Zoom in/out for adjustable readability - Recent list (up to 5 books) at startup - Tap on empty view opens the file dialog - Stable use in portrait and landscape This creates exactly the difference that many desktop-centric readers lack: short paths, clear touch operation, and reliable behavior on small displays. ## Technical Core in Brief The pipeline can be described compactly as follows: 1. Open file (`.epub`, `.md`, `.markdown`) 2. Normalize content (EPUB parsing or Markdown rendering) 3. Load HTML in `WebKit2.WebView` 4. Periodically capture scroll position and save as fraction 5. Reproduce position + zoom when reopened Additionally, EPUB content is stored in `~/.cache/jaraco-reader/` so that assets are cleanly available locally. States like `recent`, `last_book`, `fraction`, and `font_size` are stored in `~/.config/jaraco-reader/positions.json`. ## Why This Fits Well with postmarketOS postmarketOS gives us a real Alpine Linux system on the smartphone. This means: - Traceable packaging with `APKBUILD` + `abuild` - Direct installation and testing on the device - No proprietary special platform for a simple reader `jaraco-reader` thus remains deliberately close to classic Linux development: transparent, packageable, and maintainable. ## Conclusion `jaraco-reader` emerged from a concrete pain point: Desktop readers are strong, but mobile readability of technical content is often weak. With GTK, WebKit2GTK, Markdown rendering, and Mermaid support, the project delivers exactly the features that are missing on mobile Linux devices. For us, the central result is not just "another reader," but a practical tool that makes Markdown documents with diagrams and EPUB books significantly easier to read on postmarketOS. ## Why Custom Software Matters Many applications today are very generic. They cover everything somehow, but in everyday use, they often do too much at once or too little at crucial points. This is exactly where friction losses arise: more clicks, more compromises, less focus. Specific tools that support exactly your workflow are achievable today. If you face similar problems and wonder if there isn't a more tailored solution: Contact us. We'll be happy to support you. ## Appendix: Relevant Commands - `./app/jaraco-reader /path/to/book.epub` Starts the reader directly with an EPUB file. - `./app/jaraco-reader /path/to/doc.md` Opens a Markdown document with HTML rendering and Mermaid support. - `abuild -F` Builds the APK package from `APKBUILD`. - `apk add --allow-untrusted /home/user/packages/projects/aarch64/jaraco-reader-.apk` Installs the built package on the device. --- # Blog: Ai Pr Autofix **Source Path:** `blogs/ai-pr-autofix.md` **Canonical URL:** https://jarakube.eu/blogs/ai-pr-autofix.html **Markdown URL:** /blogs/ai-pr-autofix.md # AI PR Autofix: A Practical Approach to Dependency Update Automation > Date: February 19, 2026 ## Why Dependency Updates Remain a Challenging Engineering Problem Modern software systems rely on large, fast-moving package ecosystems. Security advisories, bug fixes, and performance improvements appear continuously. The actual problem today is rarely generating pull requests—tools like Dependabot handle that. The core challenge is reliable technical assessment: Is an update truly safe and correct in the specific target system? Many teams face bottlenecks here: - Builds break due to API changes, - Transitive dependencies alter behavior, - Manual prioritization consumes time across multiple repositories, - Frequent context switching reduces productivity. This creates a conflict: Ignoring updates increases risk, while manual processing increases costs. ## What This Project Solves `ai-pr-autofix` is a GitHub Action that reduces operational overhead for dependency maintenance while preserving clear governance signals. The action combines four components: 1. Discovery and prioritization of open Dependabot PRs. 2. Deterministic build/test validation per PR. 3. Optional AI-assisted repair for build failures. 4. Structured feedback via comments, labels, and merge policy. Technically, it uses GitHub CLI for PR operations and GitHub Copilot CLI for fix-oriented AI steps, encapsulated in a composite action. ## Architecture and Execution Model The action supports three modes: - `discover`: Find and prioritize PRs, generate matrix output for parallel jobs. - `process`: Process individual PRs (checkout, build, optional fix, reporting). - `all`: Sequential discovery and processing in the same job. This makes the system suitable for both small repositories (simple `all` mode) and larger environments with parallel processing. ### Prioritization PRs are enriched with metadata (e.g., SemVer bump type, security label) and sorted using configurable priority rules. This creates an explicit, reproducible queue instead of ad-hoc triage. ### Build-First Principle Each PR is first validated with the project-specific build/test command. On success, it is directly marked as verified. ### AI Fix Loop For build failures with AI enabled, a limited repair loop starts: - Prompt generation with upgrade context and focused error extracts, - Copilot invocation with restricted tools, - Rebuild/test, - Commit/push only after successful validation. If all attempts fail, the PR is cleanly marked for manual review. ### Governance Transparency and control are maintained through: - Clear labels (`ai-verified`, `ai-fixed`, `ai-needs-review`), - Documenting PR comments, - Conservative auto-merge rules (e.g., no auto-merge for security and major updates). ## Why Good Tests Are the Critical Success Factor Automated repair is only as good as the validation that secures it. A "green" build with weak test coverage is not a reliable quality signal. Thus, the practical benefit of this method depends directly on test quality: - Unit tests for local correctness, - Integration tests at system boundaries, - Contract and end-to-end tests for real interactions, - Reproducible CI execution. From a technical perspective, tests are the measuring instrument of automation. If the instrument is imprecise, the risk of misjudgment increases. If it is precise, a large portion of maintenance work can be safely automated. ## Economic Benefits Dependency maintenance is unavoidable but rarely differentiating. Manual update processing often incurs high opportunity costs, especially for experienced developers. Controlled automation shifts this cost structure: - Less manual effort per update, - Shorter remediation times for security and compatibility issues, - Fewer context switches, - More capacity for product and platform development. The benefit comes not only from time savings but also from reduced risk with more up-to-date software. ## Current Technical Enhancements Recent improvements focus on robust operability: - Shell-compatible build execution for realistic CI command chains, - Copilot token only required when AI fixes are enabled, - More robust version handling for complex version strings, - Safer Copilot execution via argument-based subprocess calls, - Targeted tests for central control paths. ## Conclusion Keeping dependencies up to date is a systemic issue, not just a tool feature. Dependabot solves discovery and PR generation, but validation and remediation remain the real scaling barriers. `ai-pr-autofix` addresses this gap with build-first validation, limited AI repair attempts, and clear policy governance in standard GitHub workflows. The approach delivers the greatest impact in teams with high test maturity. There, update automation can measurably improve both reliability and cost efficiency without replacing necessary human oversight. ## Call to Action Interested in a practical test in your repositories? Contact us for trial access. --- # Consulting **Source Path:** `consulting/consulting.md` **Canonical URL:** https://jarakube.eu/consulting/consulting.html **Markdown URL:** /consulting/consulting.md # Engineering for software products and platforms. jaraco combines software engineering, architecture and hands-on technical consulting to help teams turn complex systems into maintainable products and platforms. ## Platform Engineering We help software companies design, modernize and operate cloud and Kubernetes platforms that enable product teams instead of slowing them down. ### Areas we can support - Kubernetes - Cloud Architecture - Developer Platforms - CI/CD - GitOps - Observability - Reliability - Developer Experience - Security - Sovereign Cloud ## Software Engineering jaraco provides software engineering for maintainable products, backend services, integrations, modernization work and architecture decisions that need to stay practical under real delivery pressure. ## Automation & AI We support workflow automation, AI integration, data and application integration, and local or sovereign AI approaches where control, privacy or operational ownership matter. ## Assess -> Design -> Implement -> Enable - **Assess:** Understand architecture, organization, constraints and actual bottlenecks. - **Design:** Define pragmatic target architecture and priorities. - **Implement:** Work hands-on with the client team. - **Enable:** Transfer knowledge so the client remains in control. ## First step If cloud, Kubernetes, delivery, automation or software complexity is slowing the team down, start with a focused technical conversation. [Explore the Platform Assessment](../platform-assessment/platform-assessment.html) --- # Platform-Assessment **Source Path:** `platform-assessment/platform-assessment.md` **Canonical URL:** https://jarakube.eu/platform-assessment/platform-assessment.html **Markdown URL:** /platform-assessment/platform-assessment.md # Know what to fix before rebuilding your platform. Get an independent technical view of your cloud and platform environment - and a prioritized roadmap for what should happen next. ## Assessment areas ### Architecture - Cloud and Kubernetes architecture - Networking - Workloads - Dependencies - Scalability ### Software Delivery - CI/CD - GitOps - Deployments - Environments - Automation ### Operations & Reliability - Observability - Monitoring, logging and tracing - Alerting - Resilience ### Security - Access - Secrets - Workload security - Operational responsibilities ### Efficiency - Resource usage - Cloud costs - Operational overhead - Platform complexity ### Developer Experience - Self-service - Workflows - Platform interfaces - Ownership - Bottlenecks ### Operating Model - Responsibilities - Knowledge concentration - Team interfaces - Operational ownership ## Deliverables - Current-State Assessment - Risk Map - Quick Wins - Target Architecture - Prioritized Roadmap The Platform Assessment stands on its own. You can implement the recommendations with your internal team, with another partner, or together with jaraco. [Discuss an Assessment](mailto:info@jaraco.de?subject=Discuss%20a%20Platform%20Assessment) --- # Founder **Source Path:** `founder/founder.md` **Canonical URL:** https://jarakube.eu/founder/founder.html **Markdown URL:** /founder/founder.md # Jan Radon, Founder of Jaraco GmbH Jan Radon is the founder and managing director of Jaraco GmbH. He works as a software engineer, architect and technical consultant for companies that need reliable software platforms, pragmatic modernization and hands-on engineering leadership. ## What Jan brings into consulting - Platform Engineering with Kubernetes, OpenShift, Docker, Helm, GitOps, Flux and ArgoCD - Cloud and infrastructure architecture across Azure, AWS, Google Cloud and on-premise platforms - Microservice architecture with Java, Spring Boot, Kotlin, Kafka, RabbitMQ and API design - DevOps and CI/CD with GitHub Actions, GitLab CI/CD, Jenkins, Maven and Gradle - Observability and operations with Prometheus, Grafana, Dynatrace, OpenTelemetry and Azure Insights - Distributed storage and systems work with Ceph, Rook, S3, RADOS, RBD and CephFS - Technical leadership, team coaching, code reviews, quality practices and agile delivery - Practical use of GenAI and coding agents in software development, documentation and enablement ## Experience that shapes Jaraco services Jan has worked across enterprise software, insurance, banking, energy, telecommunications, tourism, logistics and industrial projects. His work often sits where product delivery, platform operation and software architecture meet. Recent work includes Ceph and Kubernetes storage engineering, API gateway architecture in banking, DevOps and Kafka platform work in insurance, OpenShift migration consulting, cloud data pipelines, microservice modernization and international team enablement. This experience is the foundation for Jaraco services such as Platform Assessment, platform modernization, developer platform design, API and integration architecture, DevOps enablement, cloud cost and reliability analysis, and practical proof-of-concept delivery. ## Typical project examples ### Platform Assessment and modernization Review Kubernetes, OpenShift or cloud environments, identify reliability and delivery bottlenecks, and turn findings into a prioritized roadmap. ### Developer platform and CI/CD Design GitHub Actions, GitLab CI/CD, Helm charts, GitOps flows and quality gates so product teams can release more safely with less manual coordination. ### API and microservice architecture Support API product design, versioning, documentation, monitoring and service architecture for teams that need clear ownership and stable interfaces. ### Observability and operations Improve monitoring, alerting, telemetry and incident analysis so teams understand production behavior and can operate systems with confidence. ### GenAI in engineering workflows Introduce Copilot, coding agents and MCP-enabled workflows where they improve delivery, documentation, onboarding or testing without hiding engineering judgment. ## Working style Jan combines architecture work with implementation. That means decisions are tested against real code, pipelines, operations and team constraints. The goal is not a slide deck; the goal is a platform and operating model that engineers can own. [Talk to Jan Radon](mailto:jan.radon@jaraco.de?subject=Talk%20to%20Jan%20Radon) --- # Partner **Source Path:** `partner/partner.md` **Canonical URL:** https://jarakube.eu/partner/partner.html **Markdown URL:** /partner/partner.md # Build better AI and automation solutions together We are building a strong partner network to support clients with sustainable, stable, and well-designed AI and automation solutions. ## What we are looking for - Specialists in AI engineering and applied machine learning - Experts in automation, integration, and workflow platforms - Technology partners with reliable delivery standards - Consultants and implementation teams who share a practical business focus ## Why partnership matters Clients benefit when strong specialists work together instead of trying to force every need into one narrow delivery model. A good partner network helps us cover the right expertise while keeping solutions maintainable and dependable. ## What we value We are looking for partners who care about clarity, realistic expectations, stable delivery, and solutions that clients can actually operate over time. ## How to start If you want to explore a partnership with Jaraco GmbH, get in touch. We are interested in long-term relationships that improve client outcomes and create better AI and software projects together. --- # Start-Poc **Source Path:** `start-poc/start-poc.md` **Canonical URL:** https://jarakube.eu/start-poc/start-poc.html **Markdown URL:** /start-poc/start-poc.md # Start with a practical proof of concept Turn manual work, unclear workflows, or software bottlenecks into a focused first solution with Jaraco GmbH. ## Why start with a PoC A proof of concept helps reduce uncertainty before larger investments are made. It creates a realistic basis for decisions, technical planning, and internal alignment. ## Typical situations - Manual work is consuming too much time - Teams are switching between too many tools - An automation idea exists, but nobody has turned it into a practical first step - You want to test an AI-supported workflow without committing to a large programme immediately - You already use tools like Copilot to summarise or transform text for another system and are asking why that still has to be done manually ## What you get - A structured first conversation about your use case - A realistic scope for a first implementation - A proof of concept focused on one useful business outcome - Clear next-step recommendations after the PoC ## Why Jaraco We combine consulting, implementation, and architecture. That means your proof of concept is not just a discussion document, but a practical first step toward dependable software or automation. If your team is already using AI informally, for example to prepare summaries, reformat information, or translate content for another system, that is often a strong sign that a focused proof of concept makes sense. It usually means there is already a real workflow worth automating properly. ## Let’s define the first useful step You do not need a full specification to begin. If you have a business problem, a manual process, or a rough automation idea, we can help shape it into a realistic proof of concept. --- # Jarakube **Source Path:** `jarakube/jarakube.md` **Canonical URL:** https://jarakube.eu/jarakube/jarakube.html **Markdown URL:** /jarakube/jarakube.md # Jarakube: a sovereign Kubernetes platform for practical delivery Jarakube is Jaraco's Kubernetes-based development and operations platform for teams that want to connect applications, data, automation, and local AI services without giving up control of their environment. ## What Jarakube is for - Connect existing business systems, internal services, and new software components in one controlled platform - Create a reliable basis for automation, integration, and AI-supported workflows - Keep sensitive business data in your own infrastructure or in a European hosting environment - Reduce dependency on large non-European cloud platforms where that matters operationally or legally ## Core building blocks - Kubernetes as the operational base for modular workloads and controlled rollout processes - Open-source components for storage, networking, observability, and platform operations - A structured information layer that makes data easier to find, govern, and reuse across services - Local or tightly controlled AI services for internal assistants, document workflows, and process automation - Integration paths for existing systems such as ERP, CRM, databases, document storage, and production-related software ## What problems it addresses Many small and mid-sized companies already have data and software in place, but the pieces do not work together cleanly enough for dependable automation. Information is scattered, manual transfers remain common, and AI ideas stall because data access, governance, and infrastructure are not ready. Jarakube creates a practical platform layer that helps teams connect those pieces step by step. New data can become available quickly across the system, responsibilities can be made clearer, and new services can be introduced without rebuilding the whole landscape at once. ## How deployment works - Run on dedicated on-premise hardware for full local control - Run in a European datacentre when local hosting is not the right fit - Start with a focused integration or workflow instead of a full transformation programme - Expand incrementally as new use cases, data products, and automation services prove their value ## Where it fits best Jarakube is designed for organisations that need more than a simple hosting setup. It fits when software delivery, data usage, automation, and AI need to be combined in one maintainable system with clear ownership and realistic operating models. It is especially relevant for companies that want to modernise existing IT, prepare secure internal AI use, or build a more dependable platform for integration-heavy operational work. ## Built for small and mid-sized companies Jarakube is aimed at companies that see the value of AI, automation, and central data access, but do not want to build a large internal platform team first. Typical environments include industrial companies, craft businesses, agencies, consultancies, service providers, retailers, and teams with ERP, CRM, Jira, Confluence, databases, file servers, or sensitive customer data. The offer is intentionally practical: customers do not buy Kubernetes or local LLMs as abstract technology. They start with concrete process improvements such as document automation, internal knowledge search, reporting, support automation, or better data flow between existing systems. ## Operating models Jarakube can be introduced in the operating model that fits the customer's risk profile and IT capacity: - Hybrid: sensitive data stays local or in a controlled customer environment, while operation, maintenance, or scaling tasks are supported by Jaraco or a partner - Partner-hosted: the platform runs with a European IT partner when the customer does not want to operate infrastructure - Fully on-premise: data, models, workflows, and applications stay inside the customer's own network - Jarakube Complete: a preconfigured local system with hardware, Kubernetes, CEPH storage, local AI components, data catalogue, and initial workflows For small and mid-sized companies, the usual starting points are hybrid operation, partner hosting, or Jarakube Complete. A fully on-premise model remains available for organisations with especially high control and security requirements. ## Packages and use cases Jarakube is packaged around understandable business outcomes: - Starter: from 499 € per month for a first hybrid or hosted setup with one use-case bundle and basic data catalogue - Business: from 899 € to 1,499 € per month for multiple data sources, two to three use cases, monitoring, and managed service - Control: from 1,499 € to 2,999 € per month for dedicated operation, stronger governance, local LLMs, individual integrations, and optional SLA agreements - Complete: local control without building the infrastructure yourself Common use-case bundles include document automation, internal knowledge AI, reporting and insights, support automation, and system integration between ERP, CRM, databases, and file shares. This keeps the entry point understandable for smaller teams and allows the platform to grow as additional processes prove their value. ## Jarakube Complete Local For small and mid-sized companies that already run services locally and want to keep data on their own premises, Jarakube can be delivered as a local complete system. **Jarakube Complete Local starts from 17,500 € one-time plus from 999 € per month.** The minimal local setup is designed around: - 3 storage nodes with 6 CEPH OSDs - 4 additional compute nodes for workloads, automation, and redundancy - 1 on-premise GPU node for local AI workloads - Additional network devices, cabling, adapters, and setup material - A preconfigured Kubernetes platform with monitoring and operating documentation The monthly fee covers the managed platform layer around the local installation: Kubernetes and storage updates, monitoring, alerting, security maintenance, backup and recovery checks, remote support, documentation updates, and continuous Jarakube platform improvements. The hardware stays under your control; Jarakube keeps the platform maintainable. Prices are orientation values. The final offer depends on current hardware market prices, availability, storage capacity, GPU class, warranty, support level, and integration scope. ## First step If you want to assess whether Jarakube fits your environment, we can start with a scoped discussion around your existing systems, data flows, operational constraints, and the first use case worth implementing. ## Slack support and community For Jarakube support and general questions, we now offer the Slack channel `#jarakube`. If you want to join the wider community, get in touch and send us a brief email explaining why you would like to join `#community`. We are glad you joined, and we look forward to building the community together. --- # Pricing **Source Path:** `pricing/pricing.md` **Canonical URL:** https://jarakube.eu/pricing/pricing.html **Markdown URL:** /pricing/pricing.md # Pricing The first contact meeting is free of charge and intended to discuss your situation, goals, and possible ways of working together. ## How we scope work Based on that conversation, we prepare a practical plan to clarify scope, expected effort, and the type of support required. ## What affects pricing - Technical context and delivery complexity - Scope, duration, and urgency - Collaboration model and expected responsibilities - How much implementation, coordination, or advisory support is needed ## Typical ways of working - Short advisory support to clarify direction and next steps - Focused delivery support for a specific implementation phase - Longer collaboration when teams need continuity across planning and delivery ## Why pricing is discussed individually Each engagement depends on individual requirements, technical context, and project scope. Pricing is therefore discussed individually rather than using fixed package prices that would not reflect the real work. ## Next step If you already have a concrete project in mind or want to compare different ways of working together, get in touch. We can usually clarify the first realistic setup quickly. --- # Mcp-Server **Source Path:** `mcp-server/mcp-server.md` **Canonical URL:** https://jarakube.eu/mcp-server/mcp-server.html **Markdown URL:** /mcp-server/mcp-server.md # Jaraco Website MCP Server The Jaraco Website MCP Server provides programmatic access to all website content including blog posts, services, and categories. It enables AI agents and other clients to read content and draft emails for different services. ## Overview The MCP (Model Context Protocol) server exposes the Jaraco website content as structured resources that can be accessed by AI agents, chatbots, or other applications. The server provides **read-only access** to all content and includes a tool for drafting service-specific emails. **Registry Information:** - **Registry Name:** `io.github.jrse/jaraco_website` - **Published Version:** `1.0.1` - **PyPI Package:** `jaraco-website-mcp-server` - **Registry URL:** https://registry.modelcontextprotocol.io ## Features - **Read Blog Posts**: Access all blog posts in multiple languages - **Read Services**: Access all service descriptions and details - **Browse Categories**: Explore content organized by categories - **Read Jarakube**: Access Jaraco's Kubernetes platform information - **Draft Emails**: Generate service-specific or Jarakube email templates with appropriate default text ## Available Resources The MCP server exposes resources with the following URI patterns. Additionally, the following files are available for direct access: ### Direct File Resources | File | URI | Description | |------|-----|-------------| | `llms.txt` | `https://jarakube.eu/llms.txt` | Summary of LLMs and models used or recommended by Jaraco | | `llms-full.txt` | `https://jarakube.eu/llms-full.txt` | Full list of LLMs and models used or recommended by Jaraco | ### Resource Types | Type | URI Pattern | Description | |------|-------------|-------------| | Blog Posts (English) | `resource://jaraco/blog_posts/{slug}` | Individual blog posts in English | ### Resource Types | Type | URI Pattern | Description | |------|-------------|-------------| | Blog Posts (English) | `resource://jaraco/blog_posts/{slug}` | Individual blog posts in English | | Blog Posts (Localized) | `resource://jaraco/blog_posts/{slug}/{language}` | Blog posts in specific language | | Services (English) | `resource://jaraco/services/{slug}` | Service descriptions in English | | Services (Localized) | `resource://jaraco/services/{slug}/{language}` | Service descriptions in specific language | | Categories | `resource://jaraco/categories/{slug}` | Content categories | | Jarakube Platform (English) | `resource://jaraco/jarakube/platform` | Jaraco's Kubernetes platform information | | Jarakube Platform (Localized) | `resource://jaraco/jarakube/platform/{language}` | Jarakube platform information in specific language | ### Supported Languages All content is available in the following languages: - English (`en`) - German (`de`) - French (`fr`) - Spanish (`es`) - Dutch (`nl`) **Note**: For localized content, use the `{slug}/{language}` pattern. For English content, you can use either `{slug}` or `{slug}/en`. ## Connecting to the MCP Server ### Prerequisites 1. Python 3.10 or higher (required for MCP SDK v2) 2. MCP client library for your programming language ### Connection Information - **Server Address**: `https://jarakube.eu/mcp` - **Server Name**: `jaraco-website` - **Version**: `1.0.1` - **MCP SDK**: v2.2.0+ - **Registry Name**: `io.github.jrse/jaraco_website` ### Example Connection (Python) ```python from mcp.client import Client async def connect_to_mcp(): # Connect to the MCP server using Streamable HTTP transport client = Client("jaraco-website", url="https://jarakube.eu/mcp") await client.connect() # List all resources resources = await client.list_resources() # Read a specific blog post (English) post = await client.read_resource("resource://jaraco/blog_posts/from-data-chaos-to-efficient-automation") # Read a localized blog post post_de = await client.read_resource("resource://jaraco/blog_posts/from-data-chaos-to-efficient-automation/de") # Draft an email for a service email = await client.call_tool( "draft_email", { "service_slug": "software-development", "language": "en", "sender_name": "John Doe", "sender_email": "john@example.com", "custom_text": "I need help with a custom web application." } ) await client.disconnect() ``` **Note**: The MCP SDK v2 client automatically handles the Streamable HTTP transport. The endpoint is `/mcp` by default. ## Using the MCP Server ### Listing Resources The server provides a `list_website_resources` tool to list available resources: ```python # List all available resources resources = await client.call_tool( "list_website_resources" ) # List resources of a specific type blog_posts = await client.call_tool( "list_website_resources", {"resource_type": "blog_posts"} ) services = await client.call_tool( "list_website_resources", {"resource_type": "services"} ) categories = await client.call_tool( "list_website_resources", {"resource_type": "categories"} ) jarakube = await client.call_tool( "list_website_resources", {"resource_type": "jarakube"} ) ``` **Note**: The `list_website_resources` tool returns resources with full MCP URIs like `resource://jaraco/blog_posts/slug`. ### Reading Resources To read a specific resource, use the full resource URI: ```python # Read a blog post (English) post = await client.read_resource("resource://jaraco/blog_posts/from-data-chaos-to-efficient-automation") # Read a blog post in German post_de = await client.read_resource("resource://jaraco/blog_posts/from-data-chaos-to-efficient-automation/de") # Read a service (English) service = await client.read_resource("resource://jaraco/services/software-development") # Read a service in French service_fr = await client.read_resource("resource://jaraco/services/software-development/fr") # Read a category category = await client.read_resource("resource://jaraco/categories/platform-engineering") # Read Jarakube platform (English) jarakube = await client.read_resource("resource://jaraco/jarakube/platform") # Read Jarakube platform in Spanish jarakube_es = await client.read_resource("resource://jaraco/jarakube/platform/es") ``` ### Drafting Emails The `draft_email` tool generates service-specific or Jarakube email templates. It supports the following parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `service_slug` | string | Yes | - | The service identifier (e.g., "software-development") or "jarakube" for Jarakube platform | | `language` | string | No | "en" | Language for the email template | | `recipient` | string | No | "info@jaraco.de" | Recipient email address | | `subject` | string | No | Auto-generated | Custom email subject | | `custom_text` | string | No | "" | Additional text to include in the email | | `sender_name` | string | No | "" | Sender's name | | `sender_email` | string | No | "" | Sender's email address | | `sender_phone` | string | No | "" | Sender's phone number | **Example**: ```python # Draft email for a service email = await client.call_tool( "draft_email", { "service_slug": "software-development", "language": "en", "recipient": "info@jaraco.de", "sender_name": "Jane Smith", "sender_email": "jane@company.com", "sender_phone": "+1234567890", "custom_text": "We are looking to develop a custom web application for our e-commerce platform. We need expertise in React, Node.js, and database design." } ) # Draft email for Jarakube platform jarakube_email = await client.call_tool( "draft_email", { "service_slug": "jarakube", "language": "en", "sender_name": "John Doe", "sender_email": "john@example.com", "custom_text": "I need help with Jarakube deployment and configuration." } ) ``` **Response Format**: ```json { "subject": "Inquiry: Software Development Services", "body": "Dear Jaraco Team,\n\nWe are looking to develop a custom web application for our e-commerce platform. We need expertise in React, Node.js, and database design.\n\n[Additional template content...]\n\n---\nJaraco GmbH\nSoftware Engineering · Münster\nPhone: +49 176 85952637\nEmail: info@jaraco.de\nWebsite: https://jarakube.eu", "to": ["info@jaraco.de"], "cc": [], "bcc": [], "headers": { "From": "Jane Smith ", "Reply-To": "jane@company.com" } } ``` ## Available Services The following services are available through the MCP server: | Service Slug | Description | |--------------|-------------| | `software-development` | Custom software development services | | `consulting` | IT consulting and advisory services | | `it-architecture` | IT architecture design and review | | `linux-consulting` | Linux system consulting | | `code-review` | Code review and quality assessment | | `technology-assessment` | Technology stack evaluation | ## Available Categories Content is organized into the following categories: | Category Slug | Description | |---------------|-------------| | `platform-engineering` | Cloud, Kubernetes, delivery and reliability work for software companies | | `platform-assessment` | Focused assessment for architecture, organization, constraints and bottlenecks | | `practical-poc` | First practical solutions for automation, AI use cases and software bottlenecks | | `jarakube` | The sovereign Kubernetes platform by jaraco | | `company-founder` | jaraco's engineering roots, founder profile and company direction | ## API Reference ### list_website_resources Tool List available Jaraco website resources, optionally filtered by type. **Parameters:** - `resource_type` (optional): Filter by resource type. Supported values: `services`, `blog_posts`, `categories`, `jarakube` **Request**: ```json { "name": "list_website_resources", "arguments": { "resource_type": "services" } } ``` **Response**: ```json { "content": [ { "type": "text", "text": "[{\"uri\": \"resource://jaraco/services/software-development\", \"name\": \"Software Development\", \"description\": \"We build digital tools...\", \"mimeType\": \"text/markdown\"}, ...]", "mimeType": "application/json" } ], "isError": false } ``` The response contains an array of resources with: - `uri`: Full MCP resource URI (e.g., `resource://jaraco/services/software-development`) - `name`: Resource name/title - `description`: Resource description - `mimeType`: MIME type (always `text/markdown`) ### read_resource Read a specific resource by its full MCP URI. **Request**: ```json { "uri": "resource://jaraco/services/software-development" } ``` **Response**: ```json { "contents": [ { "type": "text", "text": "# Software Development\n\nWe build digital tools and business software that make everyday work easier, faster, and more reliable.", "mimeType": "text/markdown" } ], "resourceTemplate": null } ``` ### draft_email Tool Generate a service-specific or Jarakube email template. **Parameters:** - `service_slug` (required): Service identifier (e.g., "software-development") or "jarakube" for Jarakube platform - `language` (optional, default: "en"): Language for the email template - `recipient` (optional, default: "info@jaraco.de"): Recipient email address - `subject` (optional): Custom email subject - `custom_text` (optional): Additional text to include in the email - `sender_name` (optional): Sender's name - `sender_email` (optional): Sender's email address - `sender_phone` (optional): Sender's phone number **Request**: ```json { "name": "draft_email", "arguments": { "service_slug": "software-development", "language": "en", "recipient": "info@jaraco.de", "sender_name": "John Doe", "sender_email": "john@example.com", "custom_text": "I need help with..." } } ``` **Response**: ```json { "content": [ { "type": "text", "text": "{\"subject\": \"Inquiry: Software Development Services\", \"body\": \"Dear Jaraco Team,\\n\\nI need help with...\\n\\n---\\nJaraco GmbH\\nSoftware Engineering · Münster\\nPhone: +49 176 85952637\\nEmail: info@jaraco.de\", \"to\": [\"info@jaraco.de\"], \"headers\": {\"From\": \"John Doe \", \"Reply-To\": \"john@example.com\"}}", "mimeType": "application/json" } ], "isError": false } ``` The response is a JSON object with: - `subject`: Email subject - `body`: Email body text - `to`: List of recipient email addresses - `cc`: List of CC email addresses (empty by default) - `bcc`: List of BCC email addresses (empty by default) - `headers`: Email headers including From and Reply-To ## Security - The MCP server provides **read-only access** to content - No authentication is required by default (can be added if needed) - All inputs are validated before processing - Rate limiting is configured to prevent abuse ## Support For questions or issues with the MCP server: - **Email**: info@jaraco.de - **Website**: https://jarakube.eu - **GitHub**: https://github.com/jaracogmbh/jarakube-jaraco-app ## MCP Registry This server is published to the official MCP Registry: - **Registry Name:** `io.github.jrse/jaraco_website` - **Registry URL:** https://registry.modelcontextprotocol.io - **Search:** https://registry.modelcontextprotocol.io/v0.1/servers?search=jaraco ## Version History - **1.0.1**: Updated documentation, published to MCP Registry - **1.0.0**: Initial release with blog posts, services, categories, and email drafting --- # Mcp Server Implementation **Source Path:** `MCP-SERVER-IMPLEMENTATION.md` **Canonical URL:** https://jarakube.eu/MCP-SERVER-IMPLEMENTATION.md **Markdown URL:** /MCP-SERVER-IMPLEMENTATION.md # MCP Server Implementation for Jaraco Website ## Summary This document provides a complete overview of the MCP (Model Context Protocol) server implementation for the Jaraco website, as proposed in **ADR-001**. The implementation enables AI agents and other clients to programmatically access website content (blog posts, services, categories) with read-only access and provides a tool for drafting service-specific emails. ## 📋 Architecture Decision Record - **File**: `docs/adr/ADR-001-mcp-server-integration.md` - **Status**: Proposed and Implemented - **Decision**: Implement MCP server with read-only access to content and email drafting capability ## 🏗️ Implementation Structure ``` jarasite-website/ ├── mcp_server/ # MCP Server Module │ ├── __init__.py # Package initialization │ ├── server.py # Main MCP server implementation │ ├── content_loader.py # Content loading and caching │ ├── email_templates.py # Email template definitions │ ├── config.py # Server configuration │ ├── requirements.txt # Python dependencies │ ├── Dockerfile # Docker configuration │ └── README.md # Module documentation │ ├── mcp-server/ # MCP Documentation Pages │ ├── mcp-server.json # Manifest for generation │ ├── mcp-server.md # English documentation │ ├── mcp-server.de.md # German documentation │ ├── mcp-server.fr.md # French documentation │ ├── mcp-server.es.md # Spanish documentation │ └── mcp-server.nl.md # Dutch documentation │ ├── scripts/ │ ├── generate-static-pages.py # Updated to include MCP docs │ └── generate-mcp-docs.py # MCP documentation generator │ └── docs/adr/ ├── ADR-001-mcp-server-integration.md # Detailed ADR └── ADR-001-IMPLEMENTATION-SUMMARY.md # Implementation summary ``` ## ✅ Implemented Features ### 1. MCP Server Core (`mcp_server/server.py`) - ✅ Full MCP protocol implementation - ✅ Resource listing (`list_resources`) - ✅ Resource reading (`read_resource`) - ✅ Tool execution (`call_tool`) - ✅ URI validation and parsing - ✅ Error handling - ✅ Rate limiting configuration - ✅ CORS support ### 2. Content Loading (`mcp_server/content_loader.py`) - ✅ Blog post loading with multi-language support - ✅ Service loading with multi-language support - ✅ Category management and derivation - ✅ Content caching for performance - ✅ Metadata extraction from markdown - ✅ Localized content resolution ### 3. Email Templates (`mcp_server/email_templates.py`) - ✅ Service-specific templates for all 6 services: - `software-development` - `consulting` - `it-architecture` - `linux-consulting` - `code-review` - `technology-assessment` - ✅ Templates in all 5 languages (EN, DE, FR, ES, NL) - ✅ Template formatting with custom text insertion - ✅ Sender information support - ✅ Recipient configuration - ✅ Proper email headers generation - ✅ Default fallback templates ### 4. Configuration (`mcp_server/config.py`) - ✅ Environment variable support - ✅ Default configuration values - ✅ Configuration validation - ✅ Cache settings - ✅ Logging configuration - ✅ Rate limiting settings ### 5. Documentation - ✅ Comprehensive English documentation (`mcp-server.md`) - ✅ German documentation (`mcp-server.de.md`) - ✅ French documentation (`mcp-server.fr.md`) - ✅ Spanish documentation (`mcp-server.es.md`) - ✅ Dutch documentation (`mcp-server.nl.md`) - ✅ API reference in all languages - ✅ Usage examples (Python, JavaScript) - ✅ Integration examples - ✅ Configuration guide - ✅ Docker setup instructions ### 6. Build Integration - ✅ MCP documentation generation script (`scripts/generate-mcp-docs.py`) - ✅ Integration with existing build pipeline - ✅ Automatic sitemap updates - ✅ Theme support for documentation pages ## 📊 Resource Types ### Available Resources | Type | URI Pattern | Description | Languages | |------|-------------|-------------|-----------| | Blog Posts | `blog_posts/{slug}[.{lang}]` | Individual blog posts | EN, DE, FR, ES, NL | | Services | `services/{slug}[.{lang}]` | Service descriptions | EN, DE, FR, ES, NL | | Categories | `categories/{slug}` | Content categories | EN, DE, FR, ES, NL | ### Service Slugs - `software-development` - Custom software development - `consulting` - IT consulting - `it-architecture` - IT architecture design - `linux-consulting` - Linux consulting - `code-review` - Code review services - `technology-assessment` - Technology evaluation ### Category Slugs - `software-engineering` - Software development and engineering - `consulting` - Consulting services - `linux` - Linux and infrastructure - `automation` - Automation and workflow improvement ## 🔧 Tools ### `draft_email` Tool **Purpose**: Generate service-specific email templates with appropriate default text. **Parameters**: ```json { "service_slug": "software-development", // Required "language": "en", // Optional (default: "en") "recipient": "info@jaraco.de", // Optional (default: "info@jaraco.de") "subject": "Custom subject", // Optional (auto-generated) "custom_text": "Additional details...", // Optional "sender_name": "John Doe", // Optional "sender_email": "john@example.com", // Optional "sender_phone": "+1234567890" // Optional } ``` **Response**: ```json { "subject": "Inquiry: Software Development Services", "body": "Dear Jaraco Team,...", "to": ["info@jaraco.de"], "cc": [], "bcc": [], "headers": { "From": "John Doe ", "Reply-To": "john@example.com" } } ``` ## 🚀 Usage ### Running the Server #### Development ```bash # Install dependencies pip install -r mcp_server/requirements.txt # Run server python -m mcp_server.server ``` #### Docker ```bash # Build image docker build -t jaraco-mcp-server -f mcp_server/Dockerfile . # Run container docker run -p 8081:8081 -v $(pwd):/app jaraco-mcp-server ``` #### Docker Compose ```yaml services: mcp-server: build: context: . dockerfile: mcp_server/Dockerfile ports: - "8081:8081" volumes: - .:/app environment: - MCP_PORT=8081 - CONTENT_ROOT=/app ``` ### Client Examples #### Python ```python from mcp.client import Client async def main(): client = Client("jaraco-website", url="http://localhost:8081") await client.connect() # List resources resources = await client.list_resources() # Read a blog post post = await client.read_resource("blog_posts/from-data-chaos-to-efficient-automation") # Draft an email email = await client.call_tool( "draft_email", { "service_slug": "software-development", "language": "en", "sender_name": "John Doe", "custom_text": "I need help with..." } ) await client.disconnect() ``` #### JavaScript ```javascript const { Client } = require('@modelcontextprotocol/sdk'); async function main() { const client = new Client('jaraco-website', { url: 'http://localhost:8081' }); await client.connect(); const resources = await client.listResources(); const post = await client.readResource('blog_posts/from-data-chaos-to-efficient-automation'); const email = await client.callTool('draft_email', { service_slug: 'software-development', language: 'en' }); await client.disconnect(); } ``` ## 🛡️ Security - ✅ **Read-Only Access**: All resource access is read-only - ✅ **No Authentication**: Initial implementation is open (can add auth later) - ✅ **Input Validation**: All URIs and parameters are validated - ✅ **Rate Limiting**: Configurable to prevent abuse - ✅ **Docker Security**: Runs as non-root user in container - ✅ **CORS**: Configurable CORS headers ## 📝 Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `MCP_HOST` | `0.0.0.0` | Host to bind to | | `MCP_PORT` | `8081` | Port to listen on | | `CONTENT_ROOT` | Project root | Root directory for website content | | `CACHE_ENABLED` | `true` | Enable content caching | | `CACHE_TTL` | `300` | Cache time-to-live in seconds | | `LOG_LEVEL` | `INFO` | Logging level | | `RATE_LIMIT_REQUESTS` | `100` | Maximum requests per period | | `RATE_LIMIT_PERIOD` | `60` | Rate limit period in seconds | | `CORS_ORIGINS` | `*` | Allowed CORS origins | ## 🔄 Build Process ### Full Build with MCP Docs ```bash # Generate themed shells python3 scripts/generate-themed-shells.py # Update indexes python3 scripts/update-services-index.py python3 scripts/update-stories-index.py # Validate content python3 scripts/validate-content-manifests.py # Generate static pages (includes MCP docs) python3 scripts/generate-static-pages.py # Generate content indexes python3 scripts/generate-content-indexes.py # Update SEO python3 scripts/update-seo.py ``` ### Regenerate MCP Docs Only ```bash python3 scripts/generate-mcp-docs.py ``` ## 📊 Success Criteria ✅ MCP server can be started and responds to requests ✅ All blog posts, services, and categories are accessible via MCP ✅ Email drafts can be generated for all services in all languages ✅ Documentation pages are generated for all languages ✅ Build integration is complete ✅ Performance is acceptable (caching implemented) ✅ Security considerations addressed ## 🎯 Next Steps ### To Complete 1. Add comprehensive test suite (`tests/test_mcp_server.py`) 2. Update main README with MCP server section 3. Optionally add MCP server service to `docker-compose.yml` 4. Optionally add nginx proxy configuration ### To Deploy 1. Build Docker image 2. Deploy to server 3. Update documentation pages 4. Monitor and iterate ## 📚 Documentation - **ADR**: `docs/adr/ADR-001-mcp-server-integration.md` - **Implementation Summary**: `docs/adr/ADR-001-IMPLEMENTATION-SUMMARY.md` - **MCP Server README**: `mcp_server/README.md` - **User Documentation**: `mcp-server/mcp-server.{lang}.md` - **This File**: `MCP-SERVER-IMPLEMENTATION.md` ## 🔗 References - [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Jaraco Website README](README.md) ## 📞 Support - **Email**: info@jaraco.de - **Website**: https://jaraco-gmbh.de - **GitHub**: https://github.com/jaracogmbh/jaraco-website --- **Version**: 1.0.0 **Last Updated**: 2026-09-21 **Status**: Implementation Complete ✅ --- # Integration Summary **Source Path:** `INTEGRATION-SUMMARY.md` **Canonical URL:** https://jarakube.eu/INTEGRATION-SUMMARY.md **Markdown URL:** /INTEGRATION-SUMMARY.md # Jaraco Website MCP Server - Complete Integration Summary ## ✅ Implementation Complete The MCP (Model Context Protocol) server has been **fully implemented and integrated** into the Jaraco website infrastructure. This document provides a comprehensive summary of all changes made. --- ## 🎯 Objectives Achieved All requirements from the original request have been fulfilled: 1. ✅ **MCP Server Implemented**: Exposes blog posts, services, and categories 2. ✅ **Read-Only Access**: All content access is read-only 3. ✅ **Email Drafting Tool**: Generates service-specific emails with appropriate default text 4. ✅ **Documentation Page**: Created `mcp-server/` with multi-language documentation 5. ✅ **Docker Integration**: MCP server runs in the same container as the website 6. ✅ **Kubernetes Integration**: MCP port exposed through auth proxy and VirtualService 7. ✅ **GitHub Actions**: Build pipeline updated to include MCP server --- ## 📁 Files Created ### MCP Server Module (`mcp_server/`) - `__init__.py` - Package initialization - `server.py` - Main MCP server (MCP SDK v2 with MCPServer) - `content_loader.py` - Content loading and caching - `email_templates.py` - Email templates in all 5 languages - `config.py` - Server configuration - `requirements.txt` - Dependencies (mcp>=2.2.0,<3) - `Dockerfile` - Container configuration (Python 3.11+) - `README.md` - Comprehensive documentation ### MCP Documentation (`mcp-server/`) - `mcp-server.json` - Manifest for generation - `mcp-server.md` - English documentation - `mcp-server.de.md` - German documentation - `mcp-server.fr.md` - French documentation - `mcp-server.es.md` - Spanish documentation - `mcp-server.nl.md` - Dutch documentation ### Build Scripts (`scripts/`) - `generate-mcp-docs.py` - Generates MCP documentation HTML pages - Updated `generate-static-pages.py` - Includes MCP docs generation ### Documentation (`docs/`) - `adr/ADR-001-mcp-server-integration.md` - Architecture Decision Record - `adr/ADR-001-IMPLEMENTATION-SUMMARY.md` - Implementation details - `adr/MCP-V2-MIGRATION-NOTES.md` - v2 migration guide - `DEPLOYMENT-INTEGRATION.md` - Deployment configuration guide ### Root Files - `docker-entrypoint.sh` - Multi-process container entrypoint - `INTEGRATION-SUMMARY.md` - This file --- ## 🔧 Files Modified ### Website Core - `Dockerfile` - Added Python 3.11, MCP SDK, and entrypoint - `docker-compose.yml` - Added MCP port and environment variables - `nginx.conf` - Added MCP upstream and proxy configuration ### GitHub Actions - `.github/workflows/build-website.yml` - Added MCP docs generation and SonarQube sources ### Kubernetes (OpsRepo) - `clusters/jarakube-jaraco/jarasite-website-dev/deployment.yaml` - Added MCP port and env vars - `clusters/jarakube-jaraco/jarasite-website-dev/jarasite-website-dev-service.yaml` - Added MCP port - `clusters/jarakube-jaraco/jarasite-website-dev/jarasite-website-dev-auth-proxy-deployment.yaml` - Added MCP port - `clusters/jarakube-jaraco/jarasite-website-dev/jarasite-website-dev-auth-proxy-service.yaml` - Added MCP port - `clusters/jarakube-jaraco/jarasite-website-dev/jarasite-website-dev-auth-proxy-configmap.yaml` - Added MCP proxy config - `clusters/jarakube-jaraco/jarasite-website-dev/jarasite-website-dev-virtualservice.yaml` - Added MCP routing --- ## 🚀 Features Implemented ### 1. Resource Access - **Blog Posts**: `blog_posts/{slug}[.{language}]` - **Services**: `services/{slug}[.{language}]` - **Categories**: `categories/{slug}` - **Multi-Language**: EN, DE, FR, ES, NL - **Caching**: Configurable for performance ### 2. Email Drafting Tool - **Service-Specific Templates**: All 6 services covered - **All 5 Languages**: EN, DE, FR, ES, NL - **Custom Text Insertion**: Support for additional user text - **Sender Information**: Name, email, phone - **Proper Headers**: From, Reply-To, etc. ### 3. MCP SDK v2 - **MCPServer Class**: Replaced FastMCP - **Streamable HTTP Transport**: Recommended for v2 - **Decorators**: Unchanged API - **Synchronous Tools**: Run in worker threads - **Asynchronous Tools**: Fully supported ### 4. Documentation - **Multi-Language**: All 5 languages - **API Reference**: Complete endpoint documentation - **Usage Examples**: Python, JavaScript, MCP CLI - **Integration Examples**: AI agents, chatbots - **Configuration Guide**: Environment variables, Docker, etc. --- ## 🌐 Access Points ### Local Development ```bash # Start services docker compose up --build # Website http://localhost:8080 # MCP Server (direct) http://localhost:8081/mcp # MCP Server (via nginx) http://localhost:8080/mcp ``` ### Dev Environment (Kubernetes) ``` # Website https://jarasite-website-dev.jarakube.eu # MCP Server https://jarasite-website-dev.jarakube.eu/mcp ``` ### Demo Environment (Kubernetes) ``` # Website https://jaraco-demo.jarakube.eu # MCP Server https://jaraco-demo.jarakube.eu/mcp ``` --- ## 📊 Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Internet / Ingress │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Istio VirtualService │ │ ┌─────────────────────┐ ┌───────────────────────────────────┐ │ │ │ / -> port 80 │ │ /mcp -> port 8081 │ │ │ │ (Website) │ │ (MCP Server) │ │ │ └─────────┬───────────┘ └──────────────┬─────────────────────┘ │ └────────────┼──────────────────────────────────┼──────────────────┘ │ │ ▼ ▼ ┌─────────────────────────┐ ┌─────────────────────────────┐ │ Auth Proxy (port 80) │ │ Auth Proxy (port 8081) │ │ ┌─────────────────────┐ │ │ ┌─────────────────────────┐ │ │ │ Basic Auth │ │ │ │ Basic Auth │ │ │ │ + Proxy to 8080 │ │ │ │ + Proxy to 8081/mcp │ │ │ └─────────┬───────────┘ │ │ └──────────────┬───────────┘ │ └────────────┼─────────────┘ └────────────────┼─────────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Main Website Container │ │ ┌─────────────────────┐ ┌───────────────────────────────────┐ │ │ │ nginx (port 8080) │ │ MCP Server (port 8081) │ │ │ │ - Static files │ │ - MCP SDK v2 │ │ │ │ - HTML/CSS/JS │ │ - Streamable HTTP transport │ │ │ │ - Blog posts │ │ - Resource access │ │ │ │ - Services │ │ - Email drafting │ │ │ │ - Stories │ │ - All languages │ │ │ └─────────────────────┘ └───────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 🔒 Security 1. **Authentication**: MCP server protected by basic auth (same as website) 2. **Network Isolation**: Runs in same container as nginx 3. **Read-Only**: All resource access is read-only 4. **Rate Limiting**: Configurable via nginx or MCP settings 5. **TLS**: All external traffic through Istio with TLS 6. **Non-Root**: Container runs as non-root user --- ## 📝 Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `MCP_HOST` | `0.0.0.0` | Host to bind | | `MCP_PORT` | `8081` | Port to listen | | `CONTENT_ROOT` | `/usr/share/nginx/html` | Content directory | | `LOG_LEVEL` | `INFO` | Logging level | | `CACHE_ENABLED` | `true` | Enable caching | | `CACHE_TTL` | `300` | Cache TTL (seconds) | ### Kubernetes Ports | Service | Port | Target Port | Protocol | |---------|------|-------------|-----------| | Website | 80 | 8080 | HTTP | | MCP | 8081 | 8081 | HTTP | --- ## 🧪 Testing ### Local Testing ```bash # Build and run docker compose up --build # Test website curl http://localhost:8080 # Test MCP server directly curl http://localhost:8081/mcp -X POST \ -H "Content-Type: application/json" \ -d '{"method": "list_resources"}' # Test MCP via nginx curl http://localhost:8080/mcp -X POST \ -H "Content-Type: application/json" \ -d '{"method": "list_resources"}' # Test with MCP CLI mcp dev mcp_server.server ``` ### Python Client Test ```python from mcp.client import Client async def test(): client = Client("jaraco-website", url="http://localhost:8081/mcp") await client.connect() # List resources resources = await client.list_resources() print(f"Found {len(resources)} resources") # Read a blog post post = await client.read_resource("blog_posts/from-data-chaos-to-efficient-automation") print(post) # Draft an email email = await client.call_tool( "draft_email", { "service_slug": "software-development", "language": "en", "sender_name": "Test User" } ) print(email) await client.disconnect() ``` --- ## 🚀 Deployment ### Deploy to Dev ```bash # Push to develop branch git push origin develop # This will trigger GitHub Actions workflow # Which will build and push the Docker image # And trigger the opsrepo workflow ``` ### Manual Deployment ```bash # Build Docker image docker build -t jaraco-website . # Run container docker run -p 8080:8080 -p 8081:8081 jaraco-website ``` --- ## 📚 Documentation ### Key Documents - [ADR-001: MCP Server Integration](docs/adr/ADR-001-mcp-server-integration.md) - [Implementation Summary](docs/adr/ADR-001-IMPLEMENTATION-SUMMARY.md) - [v2 Migration Notes](docs/adr/MCP-V2-MIGRATION-NOTES.md) - [Deployment Integration](docs/DEPLOYMENT-INTEGRATION.md) - [MCP Server README](mcp_server/README.md) ### User Documentation - [MCP Server Docs (EN)](mcp-server/mcp-server.md) - [MCP Server Docs (DE)](mcp-server/mcp-server.de.md) - [MCP Server Docs (FR)](mcp-server/mcp-server.fr.md) - [MCP Server Docs (ES)](mcp-server/mcp-server.es.md) - [MCP Server Docs (NL)](mcp-server/mcp-server.nl.md) --- ## ✅ Checklist - All Tasks Complete ### MCP Server Implementation - [x] MCP server module created - [x] Resource access implemented (blog posts, services, categories) - [x] Email drafting tool implemented - [x] Multi-language support (EN, DE, FR, ES, NL) - [x] Caching implemented - [x] Input validation added - [x] Error handling added ### v2 Migration - [x] Updated to MCP SDK v2.2.0 - [x] Migrated from FastMCP to MCPServer - [x] Moved transport settings to run() - [x] Using Streamable HTTP transport - [x] Updated all imports - [x] Tested v2 functionality ### Docker Integration - [x] Updated Dockerfile with Python 3.11 - [x] Added MCP SDK installation - [x] Created docker-entrypoint.sh - [x] Configured multi-process container - [x] Exposed port 8081 - [x] Updated docker-compose.yml ### nginx Integration - [x] Added MCP upstream - [x] Added MCP proxy configuration - [x] Added WebSocket support - [x] Configured proper headers ### GitHub Actions - [x] Updated build-website.yml - [x] Added MCP docs generation - [x] Updated SonarQube sources ### Kubernetes - [x] Updated deployment.yaml - [x] Updated service.yaml - [x] Updated auth-proxy-deployment.yaml - [x] Updated auth-proxy-service.yaml - [x] Updated auth-proxy-configmap.yaml - [x] Updated virtualservice.yaml ### Documentation - [x] Created ADR document - [x] Created implementation summary - [x] Created migration notes - [x] Created deployment guide - [x] Created user documentation (5 languages) - [x] Updated README files --- ## 🎉 Summary The **Jaraco Website MCP Server** is now **fully implemented and integrated** into the deployment pipeline. All requirements have been met: 1. ✅ **MCP Server** exposes blog posts, services, and categories with read-only access 2. ✅ **Email Drafting** tool generates service-specific emails with appropriate default text 3. ✅ **Documentation Page** created in all 5 languages describing how to use it 4. ✅ **Docker Integration** - MCP server runs automatically when container starts 5. ✅ **Kubernetes Integration** - MCP port exposed through auth proxy and VirtualService 6. ✅ **GitHub Actions** - Build pipeline updated to include MCP server **The MCP server is ready for deployment and use!** 🚀 --- ## 🔗 Quick Links - **MCP SDK v2**: https://github.com/modelcontextprotocol/python-sdk - **MCP Specification**: https://github.com/modelcontextprotocol/specification - **Jaraco Website**: https://jaraco-gmbh.de - **Dev Environment**: https://jarasite-website-dev.jarakube.eu - **Demo Environment**: https://jaraco-demo.jarakube.eu --- **Last Updated**: 2026-09-21 **Status**: ✅ Complete and Ready for Deployment **Version**: 1.0.0 ---