How servoy/servoy-copilot works
1. Repository shape and packaging
- This is an Eclipse/OSGi-based product, not a standalone app.
- The top-level bundles/ directory contains multiple plug-ins, features/ defines the installable feature, and repository.site_aiplugin/ plus launch_target* support p2 packaging and PDE launch setup.
- The code is built and run inside the Eclipse runtime that Servoy uses for its developer environment.
2. Primary user-facing subsystem: com.servoy.eclipse.servoypilot
- This is the main Copilot plug-in.
- It provides the chat UI (chatview/parts), context menu actions, quick-fix UX, code mining, and editor-adjacent AI interactions.
- It also owns preference pages, system prompts, DTOs, and the domain services that inspect and manipulate Servoy project files.
3. AI assistant orchestration layer
- The ai/ package defines assistant types such as development, documentation, explain, query-builder, quick-fix, review, and unit-test assistants.
- SystemPrompts and the prompts/ package supply the prompt templates that shape each assistant’s behavior.
- ToolComposer and the various tools/* packages bind prompt-driven assistant requests to concrete capabilities exposed to the model.
4. Tooling boundary: assistants call tools, tools call Servoy services
- The tools/ packages are organized by capability: workspace, code context, documentation, test generation, component, core, and knowledge retrieval.
- These tool interfaces are the boundary between LLM-facing logic and Eclipse/Servoy operations.
- The tools delegate into services/, which contain the actual implementation for file reading, search, formatting, schema lookup, form inspection, unit test execution, and patch/previews.
5. Workspace and project access
- services/WorkspaceService, ProjectService, FilePathResolver, SearchService, FileStructureService, and CodeContextService form the repository’s “read the workspace” layer.
- This layer is responsible for finding Servoy assets, reading file content and structure, resolving identifiers, and extracting code chunks or contexts that can be sent to the AI.
- The architecture is centered on the Eclipse workspace as the source of truth for the developer’s current project.
6. Edit/preview/validation pipeline
- services/CodeEditingService, CompareEditorService, TargetService, and the preview managers in util/ manage proposed changes before they are applied.
- The plugin supports diff/preview workflows rather than blindly writing files.
- ServoyFileGuard and the related exception prevent invalid writes to protected Servoy file formats, creating a safety boundary around automated edits.
7. Servoy domain integration
- Several services are Servoy-specific: FormService, StyleService, RelationService, ValueListService, DatabaseSchemaService, BootstrapComponentService, and JSUnitRunnerService.
- These provide the AI with domain-aware knowledge about Servoy forms, relations, styles, components, and test execution.
- ServoyScriptResolver and related context services help convert workspace artifacts into semantic input for assistant reasoning.
8. MCP server subsystem
- com.servoy.eclipse.developer.mcp is a separate plug-in that exposes a Model Context Protocol server inside the Eclipse process.
- It includes server registration/factory logic, annotation-based tool discovery, a ToolExecutor, authentication via BearerTokenAuthenticationFilter, cache support, file format guards, and preference integration.
- This is the bridge for external MCP clients to invoke Servoy developer capabilities through a structured API.
9. LangChain4j integration boundary
- com.servoy.eclipse.servoypilot.langchain4j is a vendored support bundle containing LangChain4j and related jars.
- The main plug-in depends on this bundle for model integration, MCP support, and higher-level AI abstractions.
- The architecture deliberately keeps the AI framework isolated from Servoy-specific code so model/runtime changes are less invasive.
10. Knowledge base and prompt assets
- com.servoy.eclipse.servoypilot.knowledgebase packages rules, embeddings, and system prompts used to ground AI responses in Servoy-specific conventions.
- Startup and manager classes load these assets into caches/services like RulesCache and ServoyEmbeddingService.
- This subsystem is the repository’s knowledge layer: it transforms bundled documentation and embeddings into retrieval inputs for assistants.
11. UI and interaction surfaces
- The main plug-in includes an Eclipse view (ChatView), presenter logic, browser function wrappers, markdown parsing, and handlers for refreshing or resetting instructions.
- Context actions and quick-fix features integrate with the editor, selection state, code mining, and compare editors.
- The architecture is event-driven from the Eclipse UI: user actions produce context, the assistants generate suggestions, and the UI renders responses and change previews.
12. Test and validation structure
- There are focused unit tests under bundles/com.servoy.eclipse.developer.mcp/test and broader assistant/integration tests under bundles/com.servoy.eclipse.servoypilot.assistenttests.
- The testprompts/ and testworkflows/ directories document realistic AI workflow scenarios and expected behaviors.
- This indicates the repo validates both low-level tool/server behavior and end-to-end assistant workflows.
13. External/runtime assumptions
- The runtime is the Eclipse IDE/PDE environment, with Servoy developer artifacts available in the workspace.
- The AI layer depends on model providers configured through preferences and on the LangChain4j abstraction layer.
- The MCP server exposes a local developer-facing interface rather than a public cloud service.
14. High-level data flow
- User interaction in Eclipse triggers an assistant or tool request.
- The request is assembled from workspace context, file structure, domain knowledge, and prompt assets.
- LangChain4j/model providers generate a response or tool plan.
- Tool implementations inspect or modify Servoy resources, optionally generating previews/diffs and running validation/tests before changes are applied.
15. Diagram boundary suggestion
- For an architecture diagram, draw three major zones: the Eclipse/Servoy UI plug-in, the MCP/server and tool-execution layer, and the knowledge/model support bundles.
- Put the Servoy workspace/project as the system-of-record boundary beneath them, because most flows ultimately read from and write back to workspace files and developer artifacts.
Main entry points: ai Assistants · tools Assistant Tools · ToolExecutor.java Tool Executor · context Context Actions
Components 22
Servoy Pilot
Main Eclipse plug-in with chat UI, assistants, tools, and Servoy-aware services.
- Servoy Pilot · Main UI and assistant plug-in for Copilot-style interactions inside Eclipse.
bundles/com.servoy.eclipse.servoypilot - Chat View · Chat UI, presenter, browser bridge, and preview workflow for assistant interaction.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/chatview/parts/ChatView.java - Context Actions · Editor-adjacent quick fixes, code mining, selection tracking, and context menus.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/context - Assistants · Assistant variants and model-facing orchestration for development, docs, explain, review, quick-fix, query, and tests.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/ai - System Prompts · Prompt templates that shape assistant behavior and task-specific responses.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/prompts/SystemPrompts.java - Tool Composer · Binds assistant requests to tool sets and execution paths.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/util/ToolComposer.java - Assistant Tools · Capability-specific tool interfaces for workspace, code context, documentation, tests, components, core, and retrieval.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/tools - Workspace Services · Reads workspace and project structure, resolves paths, searches files, and extracts context.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/services - Edit Pipeline · Proposes, previews, compares, and validates edits before they are applied.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/services/CompareEditorService.java - Servoy Domain · Form, style, relation, value list, schema, component, and test execution services.
bundles/com.servoy.eclipse.servoypilot/src/com/servoy/eclipse/servoypilot/services/FormService.java
MCP Server
Separate plug-in exposing developer capabilities through Model Context Protocol.
- MCP Plugin · Separate plug-in that hosts the MCP server inside the Eclipse process.
bundles/com.servoy.eclipse.developer.mcp - Tool Executor · Executes annotated tools and routes MCP requests to service implementations.
bundles/com.servoy.eclipse.developer.mcp/src/com/servoy/eclipse/developer/mcp/ToolExecutor.java - Server Registry · Server definitions and factory/registry bootstrap for the different MCP surfaces.
bundles/com.servoy.eclipse.developer.mcp/src/com/servoy/eclipse/developer/mcp/servers - MCP Services · Workspace, project, code editing, preview, history, markdown, and test services used by MCP tools.
bundles/com.servoy.eclipse.developer.mcp/src/com/servoy/eclipse/developer/mcp/services - Auth + Guards · Bearer-token auth, resource cache, and protected-file guard logic for MCP access.
bundles/com.servoy.eclipse.developer.mcp/src/com/servoy/eclipse/developer/mcp/auth/BearerTokenAuthenticationFilter.java
Knowledge + Model
Bundled knowledge assets and vendored AI runtime support.
- Knowledge Base · Bundled rules, embeddings, and system-prompt assets that ground assistant behavior.
bundles/com.servoy.eclipse.servoypilot.knowledgebase - KB Runtime · Loads and caches rules and embeddings for retrieval and instruction grounding.
bundles/com.servoy.eclipse.servoypilot.knowledgebase/src/com/servoy/eclipse/knowledgebase/service/RulesCache.java - LangChain4j · Bundled LangChain4j libraries and MCP integration support used by the main plug-in.
bundles/com.servoy.eclipse.servoypilot.langchain4j
Packaging
Feature, repository, and launch-target support for PDE/p2 packaging.
- Feature · Installable feature definition for the Servoy Copilot product.
features/com.servoy.eclipse.servoypilot.feature - Update Site · Repository site metadata for packaging and installation.
repository.site_aiplugin - Launch Target · Launch-target and target-platform configuration for running inside Eclipse.
launch_target_aiplugin
Workspace Boundary
Eclipse workspace and Servoy project files as the system of record.
- Workspace · Servoy project files and developer artifacts that assistants and MCP services read and write.
Connections 23
- Chat View → Assistants: send requests · User interactions in the chat view invoke assistant workflows.
- Context Actions → Assistants: invoke assistants · Quick fixes, code mining, and context actions trigger assistant generation.
- Assistants → System Prompts: shape prompts · Assistant types are guided by system prompt templates.
- Assistants → Tool Composer: compose tools · Assistants are wired to concrete tool sets through the composer.
- Tool Composer → Assistant Tools: bind capabilities · The composer exposes the LLM-facing tool boundary.
- Assistant Tools → Workspace Services: read workspace · Workspace and code-context tools delegate to workspace access services.
- Assistant Tools → Servoy Domain: use domain · Servoy-specific tools delegate to domain-aware services.
- Assistant Tools → Edit Pipeline: preview edits · Editing-related tools route through compare/preview and validation services.
- Workspace Services → Workspace: source of truth · Workspace services read Servoy assets from the Eclipse workspace.
- Edit Pipeline → Workspace: write back · Validated changes are applied to workspace files and project artifacts.
- Context Actions → Chat View: render feedback · Editor events and assistant results are presented back in the UI.
- MCP Plugin → Server Registry: register servers · The MCP plug-in bootstraps server instances and discovery.
- Server Registry → Tool Executor: dispatch tools · Server definitions ultimately invoke the tool executor.
- Tool Executor → MCP Services: call services · MCP tool invocations are implemented by developer services.
- Tool Executor → Auth + Guards: enforce access · Authentication and file-guard boundaries protect server actions.
- MCP Services → Workspace: inspect project · MCP services also read and modify Servoy workspace resources.
- KB Runtime → Knowledge Base: load assets · The runtime reads bundled rules and embeddings.
- KB Runtime → Assistants: ground reasoning · Knowledge assets inform assistant responses and tool behavior.
- LangChain4j → Assistants: model runtime · LangChain4j provides the model integration layer used by assistants.
- LangChain4j → MCP Plugin: MCP support · Vendored LangChain4j libraries also support the MCP-side integration.
- Feature → Servoy Pilot: package · The installable feature includes the main plug-in bundle.
- Update Site → Feature: publish · The update site packages the feature for installation.
- Launch Target → Servoy Pilot: run in PDE · Launch-target configuration is used to run the plug-in inside Eclipse.