Modules
The agents area is split into small modules along a core/adapter seam: -core
modules carry the domain and ports (light, no storage/HTTP), their siblings
carry the implementations.
core/ — runtime & gateway
| Module | Purpose |
|---|---|
mc-agent-runtime-core | The runtime's core: agent and session domain, the ports around it (chat, tools, token counting, memory strategies, repositories) and the use cases — turn loop, prompt assembly, tool dispatch. Free of storage, HTTP and templating. |
mc-agent-runtime | The adapters: file and in-memory repositories, the local in-process runtime, the Pebble prompt renderer, the tokenizer-backed token counters. |
mc-agent-memory-strategies | The memory strategies — keep everything, window, summarizing window, auto-compact. Swap this module to change memory behaviour. |
mc-llm-gateway-core | The gateway's core: chat/streaming types and the ports (LlmChat, LlmGateway, LlmConfigRepository) — light enough to be a compile dependency of anything. |
mc-llm-gateway | The gateway implementation: provider adapters, routing, retry/throttle decorators. |
mc-message-repository-core | Conversations, participants and messages as plain domain types, their ports, and the ConversationService use case. |
mc-message-repository | File-backed and in-memory implementations of those ports. |
mc-credentials | User credentials store: OAuth2 tokens + API keys, encrypted at rest, with auto-refresh and a vendor OAuth handler SPI. |
core/ — protocol
| Module | Purpose |
|---|---|
mc-agent-protocol | The protocol vocabulary: Response, Item, Conversation, events and commands — pure types, zero runtime dependencies. |
mc-agent-protocol-mc-runtime | The protocol surface implemented against the Mindconnect runtime. |
mc-agent-protocol-openai | The same surface implemented against the real OpenAI Responses + Conversations API. |
core/ — tools
| Module | Purpose |
|---|---|
mc-agent-tool-spi | What a tool is: Tool, ToolFactory, MultiToolProvider, ToolRegistry, ToolEnvironment + the ServiceLoader registry — see creating a tool. |
mc-agent-tools | Lightweight built-ins: filesystem, workspace, bash. |
mc-agent-tools-code | code_execute — snippets in disposable docker/podman containers. |
mc-agent-tools-document | PDF/Word/text tools via Tika + PDFBox + POI. |
mc-agent-tools-web | HTTP fetch, web search, HTML-to-Markdown. |
mc-agent-tools-web-browser | Headless-Chromium fetching (Playwright) for JS-rendered sites — separate module because of the ~150 MB Chromium download. |
mc-agent-tools-workflow | Persisted workflows as agent tools — one tool per workflow, parameters from its input schema. |
mcp/ — MCP servers as registered tools
| Module | Purpose |
|---|---|
mc-mcp-gateway-core | Ports and types: McpGateway, McpRegistryAdmin, McpCatalog, McpServerRegistration, McpTarget, McpServerId. |
mc-mcp-gateway-local | The in-process gateway: registrations on disk, discovery cache, Docker MCP catalog. |
mc-mcp-proxy | One server over stdio or streamable HTTP, on the official MCP Java SDK. |
mc-agent-tools-mcp | The MultiToolProvider that exposes every registered server's tools as agent tools. |
mc-mcp-gateway-admin-ui-rest | The MCP Servers screen, embedded by the admin UI. |
vectorstore/ — the knowledge layer
| Module | Purpose |
|---|---|
mc-vector-store | Vector-store SPI + built-in file-persisted memory backend |
mc-vector-store-pgvector | pgvector backend (one table per store, HNSW index) |
mc-vector-store-tools | The knowledge tool group: vector_upsert/search/delete_file/ingest_file |
mc-file-store-core | The file store's ports: FileStore, StoredFile, the FileStoreBackend SPI |
mc-file-store | The filesystem backend |
See vector store & file store.
adapter/ — the ports on Postgres
| Module | Purpose |
|---|---|
postgres/mc-llm-gateway-pg | LlmConfigRepository on Postgres. |
postgres/mc-message-repository-pg | ConversationRepository and MessageRepository on Postgres. |
postgres/mc-agent-runtime-pg | The runtime's seven repository ports on Postgres — definitions, sessions, traces, todo lists, summaries, working memory, workspace files. |
postgres/mc-file-store-pg | FileStore on Postgres — uploads as bytea rows; also the postgres backend of the SPI. |
All of them build on common/mc-jdbc, a tiny JDBC helper (JSONB document
tables, typed rows, transactions — no ORM). See Persistence.
springstarter/ — Spring Boot starters
| Module | Purpose |
|---|---|
mc-agent-starter-runtime | Builds the runtime for a Spring Boot application from the same features the embedded builder installs, configured from the mindconnect.* properties, and exports its beans; the persistence starters supply the Persistence, the namespace starter the scope. |
mc-agent-starter-file | File persistence, the default: every repository port, the LLM-config store and the file store under mindconnect.data.base-dir. |
mc-agent-starter-postgres | mindconnect.persistence=postgres: every port from one pooled DataSource, tables created on start. |
An app has both on the classpath; the property picks. The runtime's own
Spring wiring (DefaultAgentRuntimeConfig) still lives in mc-agent-runtime
and is imported by the apps — moving it into a starter of its own is the
next step.
builder/ & demo/ — embedding
| Module | Purpose |
|---|---|
mc-agent-runtime-builder | Spring-free AgentRuntimeBuilder facade for embedding the runtime in any Java program; every capability module (tools, vector stores, file store, workflows) is optional. |
mc-agent-runtime-feature-core | The CoreFeature every builder installs: the LLM layer, conversations and messages, agent definitions and sessions. AgentRuntimeBuilder.of(persistence) with it alone is the smallest runtime that chats. |
mc-agent-runtime-feature-skills, -tools, -workflows, -file-upload, -transcription, -subagents, -taskqueue | Optional features, one Maven module each, registered as services so installFromClasspath() finds them: stored skills, the tool registry over the mc-agent-tools-* modules, persisted workflows, files attached to a chat, speech to text, delegation to sub-agents, the configured task queue. See Embedding the runtime. |
mc-agent-runtime-feature-namespace | The namespace of the current call instead of one for the runtime's life: a thread-bound scope, every repository routed to the namespace's adapter, tasks that carry their scope. Installed explicitly by a host that binds the scope — the Spring starter does. |
mc-agent-simple-demo | Runnable embedding examples: a minimal chat, and a chat with an attached file searched through the session's vector store. |
server/ — deployable Spring Boot services
| Module | Purpose |
|---|---|
mc-agent-api-rest | The REST controllers and DTOs as a library (no Boot main) |
mc-agent-api-app | Agent server (REST, streaming via SSE) — embeds mc-agent-api-rest |
mc-agent-admin-ui-rest | The Admin UI itself as an embeddable library: controllers serving UiNode JSON under /admin/api/**, pages, components, SPA assets |
mc-agent-admin-ui-app | Admin UI Spring Boot application |
client/
| Module | Purpose |
|---|---|
mc-agent-cli | Terminal REPL client — wires the whole platform in a single JVM (CLI docs) |