Wwb04307201docs: comprehensive bilingual documentation update for MCP module

sql-forge-mcp

Spring AI MCP server for SQL Forge — exposes the SQL Forge backend API as AI-callable Tools, and exposes Amis page-building knowledge/templates as AI-readable Resources.

📖 This is the English version of README.md. For the canonical (Chinese) version, see README.md.

Module Constraints

This module holds no web entrypoints (no servlet / RouterFunction), and does not depend on the sql-forge-web module. All Amis previews use page.setContent() to inject self-contained HTML inside the Java process — no HTTP call to load the page goes through any business backend; the Amis SDK is fetched on-demand by the browser from the jsdelivr CDN.

MCP Three Primitives at a Glance

Per the MCP spec, capabilities are split into three primitives (Tools / Resources / Prompts):

Tools = RPC / actions (CRUD, validation, rendering, save)
Resources = read-only references (knowledge, templates, indexes — preferred for resident context)
Prompts = task templates (pre-built instructions with placeholders)

An AI Agent receives all three lists. Resources are pre-loaded if possible; Tools are invoked on demand.

1. Resources (5, passive read-only)

AI clients see these URIs at initialization and read content by URI. The schema-hints plus components/examples indexes are recommended to pre-load into context at conversation start; detailed schemas are expanded on demand via {type} / {name} templates.

URI	mimeType	Description
`amis://schema-hints`	`text/markdown`	Full Amis Schema cheat sheet (expressions / API idioms / CRUD patterns / pitfall list). Most recommended to keep resident
`amis://components`	`application/json`	Component catalog lightweight index (only `type / name / category / description`, no `keyProps`)
`amis://examples`	`application/json`	Example lightweight index (only `name / title / tags / description`)
`amis://components/{type}`	`application/json`	Full component spec by type (with `required` / `keyProps` / `minimalExample` / `docUrl`)
`amis://examples/{name}`	`application/json`	Full runnable JSON Schema by name

Resources are exposed by AmisMcpResources (spring-ai 1.1.x uses a programmatic List<McpServerFeatures.SyncResourceSpecification> Bean, not annotations).

2. Tools (29, on-demand actions)

Amis Actions (2)

Tool	Purpose
`validateAmisTemplate(context)`	Static validation: JSON syntax / required fields / component type / API format / nested recursion
`previewAmisTemplate(systemName, context)`	Real render via headless Chromium (self-contained HTML). If Chromium unavailable, degrades to `render.available=false + installHint`

Backend CRUD (13)

Tool	Purpose
`getSystems` / `getMetaDataDatabase` / `sqlForgeMetaDataTables` / `getMetaDataTableInfo` / `getMetaDataTree` / `listExecutorNames`	Metadata queries
`jsonSelect` / `jsonSelectPage` / `jsonInsert` / `jsonUpdate` / `jsonDelete`	JSON CRUD (by `tableName` + body)
`findTablesByName(systemName, keyword)`	Fuzzy table name search
`describeSchema(systemName, tableNamePattern?)`	One-shot full schema (db → tables → columns/PKs/FKs/indexes)
`countRows(systemName, tableName, whereJson?)`	Row count

Template CRUD + SQL Execution (12)

Tool	Purpose
`executeSQL(systemName, sql)`	Direct SQL execution (SELECT-only by default, controlled by `sql.forge.api.database.select-only`)
`executeSqlTemplate(systemName, id, params?)`	Execute SQL template (recommended)
`executeSqlTemplateSafely(systemName, id, params?)`	Same as above, but pre-validates template exists + params complete + refuses unbound-placeholder SQL
`saveSqlTemplate` / `getSqlTemplate` / `listSqlTemplates` / `deleteSqlTemplate`	SQL template CRUD
`amisTemplateSave` / `getAmisTemplate` / `listAmisTemplates` / `deleteAmisTemplate`	Amis template CRUD (persists to business backend)

Amis Agent Build Pipeline (One-shot)

The standard path: read knowledge → pick component → modify schema → validate → render → save:

1. resources/read  amis://schema-hints            (recommended resident)
2. resources/read  amis://components              (candidate list)
   └ resources/read  amis://components/{type}      (expand by type as needed)
3. resources/read  amis://examples                 (example index)
   └ resources/read  amis://examples/{name}        (full schema by name as template)
4. Modify schema (per hints section 7 mapping table)
5. tools/call      validateAmisTemplate(json)      (must pass first)
6. tools/call      previewAmisTemplate(systemName, json) (visual verification)
7. tools/call      amisTemplateSave(systemName, id, name, description, json)

3. Prompts (3, task templates)

Prompts are pre-built, placeholder-based instruction templates that AI clients can trigger as /slash-command. Three are preset:

Prompt	Args	Purpose
`create-amis-page`	`<systemName> <tableName> <pageTitle>`	Standard pipeline: probe table → read schema-hints → read component spec → adapt → validate → preview
`diagnose-render-error`	`<context> <errors>`	Feed failed preview errors back; have AI fix the schema and try again
`quick-crud-template`	`<systemName> <tableName> [withFilter]`	One-shot skeleton: read-only mode, minimum dialogue to generate the simplest CRUD

Design philosophy: enabling "one-line CRUD generation" comes from skeleton + templates + a diagnostic loop — not from dumping 50 Tools at the Agent.

Render Degradation

When Chromium is unavailable, previewAmisTemplate returns render.available=false with an installHint. Static validation results are unaffected.

Build & Run

# Build
mvn -pl sql-forge-mcp clean install -DskipTests

# Start MCP server
mvn -pl sql-forge-mcp spring-boot:run \
    -Dspring-boot.run.jvmArguments="-Dsql.forge.mcp.systems[0].name=Test \
        -Dsql.forge.mcp.systems[0].url=http://localhost:8081 \
        -Dsql.forge.mcp.systems[0].apiKey=test"

# Test
mvn -pl sql-forge-mcp test

Knowledge Resources

Hand-curated resource files live under src/main/resources/amis/:

catalog.json — 54 components metadata (grouped by category: crud / form / input / display / others)
examples.json — 17 complete runnable examples (crud-page / form-page / dialog-form / wizard / tabs / etc.)
schema-hints.md — Markdown cheat sheet

After modifying them, restart the MCP service for the changes to take effect — no Java recompile needed.

Refactor Notes (v1.7+)

The 6 Amis-knowledge Tools on SqlForgeMcpService (listAmisCategories / listAmisComponents / getAmisComponentSpec / listAmisExamples / getAmisExample / getAmisSchemaHints) have been migrated to MCP Resources, because these APIs are fundamentally "read-only reference data" rather than "actions". Moving them from Tools to Resources lets AI clients pre-load amis://schema-hints (the most-resident, highest-value Markdown cheat sheet) into the system prompt at init time, rather than requiring the model to actively invoke them.

Complete Agent Operation Pipeline

A full 11-step pipeline example (using MCP tools to build a USERS crud-page: probe → read knowledge → assemble → validate → save → render → modify → re-save → round-trip → delete) lives at the repository root: docs/agent-journey.md.

📖 The canonical (Chinese) version of this document is README.md.