Spring AI LoomAgent
<div align="right"> <a href="README.zh-CN.md">中文</a> | English </div>Spring Boot AI Agent — an out-of-the-box solution that makes your app converse, remember, think, and act.
A Spring Boot auto-configuration library that injects RAG knowledge base, MCP tool calling, and Skill library into Spring AI applications with an out-of-the-box chat UI.
Spring Boot AI Agent — an out-of-the-box solution that makes your app converse, remember, think, and act.
6 Pillars: 💬 Chat · Knowledge · 📁 Files · 🔧 MCP · 🧠 Skill · 🛡 RBAC Platform: 🧠 Skill Market · Knowledge Market · 🎛 Admin Console Advanced: 🧩 Sub-tasks · ⏰ Scheduled tasks · 🖼 Multimodal — one dependency, batteries included.
market_skill_id is set; admin only edits / pulls (no creation); no version field. Skills call MCP via @tool_name. Frontend chat input supports / picker for precise skill selection.@ConditionalOnMissingBean, Flyway migrations, broad chat / embedding / vector-store supportAll tools follow the interface + default implementation pattern. Every component is registered with @ConditionalOnMissingBean, allowing consumers to replace any piece with a custom implementation.
| Tool | Interface | Methods | Default | Config Property |
|------|-----------|---------|---------|-----------------|
| Time | ITimeTool | 2 | ✅ enabled | time.enabled |
| File | IFileTool | 16 | ✅ enabled | file.enabled |
| Skill | ISkillTool | 3 | ✅ enabled | skill.enabled |
| Knowledge | IKnowledgeTool | 1 | ✅ enabled | knowledge.enabled |
| Sub-task | ISubTaskTool | 4 | ✅ enabled | subtask.enabled |
| Schedule | IScheduleTool | 4 | ✅ enabled | schedule.enabled |
| Git | IGitTool | 28 | ❌ disabled | git.enabled |
| Maven | IMavenTool | 6 | ❌ disabled | maven.enabled |
| Compile & Deploy | ICompileAndDeployTool | 1 | ✅ enabled | compile.enabled |
For full @Tool method signatures, parameter details, and configuration reference, see TOOLS.md.
File, Git, Maven, and Compile each have a standalone MCP server module — the core layer has no Spring dependency and can be deployed via jbang to any MCP-compatible agent (Claude Desktop, Cursor, etc.):
| MCP Server | Description | README |
|------------|-------------|--------|
| loom-file-mcp | File system operations — read, write, edit, search, directory browsing, delete (14 tools) | EN · 中文 |
| loom-git-mcp | Git operations via JGit — clone, commit, push, merge, rebase, and more (14 tools) | EN · 中文 |
| loom-maven-mcp | Maven build operations — execute, build, package, test, dependency tree, validate (6 tools) | EN · 中文 |
| loom-compile-mcp | End-to-end deploy pipeline — git clone → build → docker build → docker run → health check (1 tool) | EN · 中文 |
<dependency>
<groupId>io.github.wb04307201</groupId>
<artifactId>spring-ai-loom-agent-spring-boot-starter</artifactId>
<version>1.1.40</version>
</dependency>
The test application uses Alibaba's Qwen (DashScope) via Spring AI Alibaba. Swap the dependency and config for any other provider:
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
<version>1.1.2.3</version>
</dependency>
spring:
ai:
dashscope:
api-key: ${DASHSCOPE_API_KEY}
chat:
options:
model: qwen3.7-plus
multi_model: true
enable_thinking: true
Note: For document-based Q&A, ensure the model supports multimodal input (e.g.,
multi_model: true). Document content is injected via System Prompt.
Visit http://localhost:8080/spring/ai/loom
Click the + button next to the input field to upload images or documents. After uploading, type your question and send it.
PDF, DOCX, XLSX, PPTX, MD, TXT, HTML, CSV, RTF, and more.
Uploaded and generated files can get download links via MCP tool downloadFileUrl, or preview links via MCP tool viewFileUrl. Files and directories can be removed via MCP tool deleteFileOrDirectory (requires explicit I_CONFIRM_DELETE confirmation — token configurable via spring.ai.loom.agent.file.deleteConfirmToken, supports recursive directory removal, and cleans up temporary file_info records).
The "File" entry provides unified browsing, previewing, downloading, and deleting for all non-knowledge-base files (including tool uploads and git repositories).
The following example uses Qdrant as the vector store. Add the dependency:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-qdrant</artifactId>
</dependency>
Add configuration:
spring:
ai:
vectorstore:
qdrant:
host: localhost
port: 6334
collection-name: qwen-collection-name
Optional RAG configuration:
spring:
ai:
loom:
agent:
rag:
similarityThreshold: 0.50 # Similarity threshold, default 0.0
top-k: 4 # Top-k results, default 4
Taking the time MCP service as an example, add the dependency:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
Add configuration:
spring:
ai:
mcp:
client:
stdio:
servers-configuration: classpath:mcp-servers.json
mcp-servers.json:
{
"mcpServers": {
"time": {
"command": "uvx",
"args": [
"mcp-server-time",
"--local-timezone=Asia/Shanghai"
]
}
}
}
The MCP button opens a panel showing available services:
Add Chinese labels and descriptions for tools via configuration:
spring:
ai:
loom:
agent:
mcps:
- name: spring-ai-mcp-client - time
title: Time
description:
A Model Context Protocol service that provides time and timezone conversion functionality. This service enables
large language models to obtain current time information and perform timezone conversions using IANA timezone names,
with automatic system timezone detection.
tools:
- name: get_current_time
description: Get the current time in a specified timezone
- name: convert_time
description: Convert time between different time zones
Skills are prompt templates that the LLM uses for recurring workflows. The data is fully managed in the database (no more yml skills[] block) and lives in three tables:
| Table | Purpose |
|----------------|-----------------------------------------------------------------------------------------------|
| market_skill | Public Skill Market — every entry has only (author, name) unique constraint ( removed version); admin edits / pulls (cannot create) — |
| user_skill | A user's local copy of a skill (source = USER_CREATED / MARKET_PULLED / ROLE_GRANTED); remove blocked when market_skill_id is set; pull rejects overwriting same-name USER_CREATED |
| role_skill | Role → market_skill authorization (which skills a role unlocks for its users); setRoleKnowledges auto-syncs user_knowledge for all assigned users |
On first launch, the init migration seeds 6 system skills (stored directly in each user's user_skill with source=USER_CREATED, default_loaded=true) so every fresh install already has useful ones — including Monthly Event Report, HTTP Test, Deploy Project, Auto E2E, etc. Admins can edit / delete any of them at any time from the Skill Market admin page (no creation from admin).
PUT /spring/ai/loom/skill. The skill is stored in user_skill with source=USER_CREATED. Fully editable (name / desc / content / default-loaded).status=APPROVED directly (no approval flow). Same (author, name) re-submits UPSERT (overwrites content + status).user_skill row with source=MARKET_PULLED. Re-pull of same name UPSERTs (no error).USER_CREATED skill, pull is rejected (403) — use 「复制为我的技能」 first to copy as a new USER_CREATED.user_skill on every login with source=ROLE_GRANTED, locked=true. setRoleKnowledges auto-syncs new role grants. You cannot edit or delete it (it's pinned by the role).market_skill (admin no longer creates new skills — author is the one who publishes from chat UI)role_skill (auto-syncs to all assigned users)user_skill (pullers) and role_skill (role grants) — no orphans| Operation | USER_CREATED | MARKET_PULLED | ROLE_GRANTED |
|----------------------------------------|--------------|---------------|--------------|
| Edit name | ✗ (PK) | ✗ | ✗ |
| Edit description | ✅ | ✅ | ✗ |
| Edit content | ✅ | ✗ (re-pull) | ✗ |
| Edit default_loaded | ✅ | ✅ | ✗ |
| Delete | ✅ | ✅ | ✗ |
| Submit to market | ✅ (new ver.)| ✗ | ✗ |
Open the Skill Library button (🧠) — four tabs:
user_skill (plus admin's union view). Click a skill to see details, then 应用 (overwrite the textarea and auto-send to the model) or 复制 (overwrite the textarea, no send).APPROVED market skills and 拉取 them into your user_skill (rejects if you already have a same-name USER_CREATED).USER_CREATED skill to the market. status is direct APPROVED, no approval. no version number. two-stage click list item → right panel form.APPROVED after de-approval). Click list item → right panel with 「撤回共享（下架）」 button. Withdraw cascades to all user_skill and role_skill.Inside content you can reference MCP tools by @tool_name — the available tools come from the role-based mcps authorization, not from yml.
For the full REST API, see docs/API.md → §6 Skill Management.
Knowledge bases store documents for RAG retrieval. The knowledge space modal has four tabs:
Market workflow: submit → PENDING → admin approve → APPROVED → other users can subscribe. Role-based authorization can also auto-grant knowledge bases to users (similar to skills).
For the knowledge market REST API, see docs/API.md → §5.8 Knowledge Market.
The admin console is a sidebar-navigated single-page-app shell. After admin login, all admin pages share a fixed left sidebar:
| Section | Path | Purpose |
|-----------------|-------------------------------|--------------------------------------|
| 用户管理 | admin/console.html | User list + role assignment + batch content cleanup |
| 角色管理 | admin/roles.html | RBAC roles + grant MCP / Skill |
| Skill 市场 | admin/skills-market.html | Approve / reject / directly CRUD Skill |
| MCP 描述维护 | admin/mcps.html | Maintain Chinese descriptions for SDK MCP tools |
| 用量统计 | admin/stats.html | Monthly Token usage (year + month filter) |
| 返回主页 | / | Back to chat home page |
/spring/ai/loom/login.html; API calls 401.控制台 → 批量清理 button. The duplicate "清理内容" / "一键清理" buttons in user row / conversation row were consolidated.user_info.type = 'ADMIN'. Non-admin attempting admin URL is redirected back to chat home.Standard MoltPulse indexed agent.
Show off your Pulse Score in your GitHub README to build trust and rank higher.