feat(mcp): platform-mcp —— EIP4 MCP server 标准接入 Claude Code/Codex/OpenCode (G2)

- 新增 platform-mcp 模块(stdio MCP server,MCP Java SDK 1.1.0 / jackson2 路线)
- 注册 7 个 MCP 工具:eip4_auto_develop / list_page_recipes / validate_page_schema
  / list_components / access_check / list_entities / entity_attributes
  忠实转发 EIP4 REST,复用人审红线(产物恒 READY_FOR_HUMAN_REVIEW),不另开权限面
- 工具逻辑 TDD(Eip4McpTools 9 单测,注入 mock REST client)
- 真实 stdio JSON-RPC e2e:initialize 协商 + tools/list 返回 7 工具(schema 正确)
  + tools/call 链路(死端口优雅 isError)
- 坑:父 pom 为 amis 校验钉死 networknt 1.5.2,与 MCP 需要的 2.0.0(含 dialect.Dialects)
  冲突 → platform-mcp 显式覆盖 2.0.0(仅本模块)
- 文档:GAP 标记 G2 完成、平台 README + skills/README 加 MCP 接入说明

接入:claude mcp add eip4 -- java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url <env>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-22 14:37:02 +08:00
parent 5b06aeceff
commit 4a2080a4f6
10 changed files with 580 additions and 1 deletions

View File

@@ -0,0 +1,90 @@
package com.eip4.platform.mcp;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CountDownLatch;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.modelcontextprotocol.json.McpJsonMapper;
import io.modelcontextprotocol.json.jackson2.JacksonMcpJsonMapper;
import io.modelcontextprotocol.server.McpServer;
import io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification;
import io.modelcontextprotocol.server.McpSyncServer;
import io.modelcontextprotocol.server.transport.StdioServerTransportProvider;
import io.modelcontextprotocol.spec.McpSchema;
/**
* EIP4 MCP server(stdio):把 EIP4 的 AI / 元数据 REST 端点暴露为 MCP 工具,
* 供 Claude Code / Codex / OpenCode 通过标准协议驱动平台开发。
*
* <p>用法:{@code java -jar platform-mcp.jar [--base-url URL]},
* 或设环境变量 {@code EIP4_BASE_URL};默认 http://localhost:8084。
* stdout 被 MCP JSON-RPC 占用,日志只走 stderr。
*/
public final class Eip4McpServer {
private static final String DEFAULT_BASE_URL = "http://localhost:8084";
private Eip4McpServer() {
}
public static void main(String[] args) throws InterruptedException {
String baseUrl = resolveBaseUrl(args);
ObjectMapper objectMapper = new ObjectMapper();
McpJsonMapper jsonMapper = new JacksonMcpJsonMapper(objectMapper);
Eip4McpTools tools = new Eip4McpTools(new JdkEip4RestClient(baseUrl, objectMapper), objectMapper);
List<SyncToolSpecification> toolSpecs = new ArrayList<>();
for (Eip4McpTools.McpToolDef def : tools.toolDefs()) {
McpSchema.Tool tool = McpSchema.Tool.builder()
.name(def.name())
.description(def.description())
.inputSchema(jsonMapper, def.inputSchemaJson())
.build();
toolSpecs.add(SyncToolSpecification.builder()
.tool(tool)
.callHandler((exchange, request) -> {
Map<String, Object> arguments = request.arguments() == null ? Map.of() : request.arguments();
Eip4McpTools.ToolResult result = def.handler().apply(arguments);
return McpSchema.CallToolResult.builder()
.addTextContent(result.text())
.isError(result.isError())
.build();
})
.build());
}
McpSyncServer server = McpServer.sync(new StdioServerTransportProvider(jsonMapper))
.serverInfo("eip4", "0.1.0")
.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
.tools(toolSpecs)
.build();
System.err.println("EIP4 MCP server started (baseUrl=" + baseUrl + ", tools=" + toolSpecs.size() + ")");
Runtime.getRuntime().addShutdownHook(new Thread(server::close));
new CountDownLatch(1).await();
}
static String resolveBaseUrl(String[] args) {
for (int i = 0; i < args.length - 1; i++) {
if ("--base-url".equals(args[i])) {
return stripTrailingSlash(args[i + 1]);
}
}
String env = System.getenv("EIP4_BASE_URL");
if (env != null && !env.isBlank()) {
return stripTrailingSlash(env);
}
return DEFAULT_BASE_URL;
}
private static String stripTrailingSlash(String value) {
String out = value.trim();
while (out.endsWith("/")) {
out = out.substring(0, out.length() - 1);
}
return out;
}
}

View File

@@ -0,0 +1,178 @@
package com.eip4.platform.mcp;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
/**
* 把 EIP4 的 AI / 元数据 REST 端点封装成 MCP 工具的纯逻辑层(不依赖 MCP SDK,便于单测)。
*
* <p>红线复用:所有工具忠实转发到平台 REST,平台已有的人审门禁(产物恒 READY_FOR_HUMAN_REVIEW)、
* access-check 与安全门负责权限/生产写控制;本层不另开权限面。MCP server 应只配本地/开发 baseUrl。
*/
final class Eip4McpTools {
private static final String EMPTY_SCHEMA = "{\"type\":\"object\",\"properties\":{}}";
private final Eip4RestClient client;
private final ObjectMapper mapper;
Eip4McpTools(Eip4RestClient client, ObjectMapper mapper) {
this.client = client;
this.mapper = mapper;
}
record ToolResult(String text, boolean isError) {
}
record McpToolDef(String name, String description, String inputSchemaJson,
Function<Map<String, Object>, ToolResult> handler) {
}
List<McpToolDef> toolDefs() {
return List.of(
new McpToolDef("eip4_auto_develop",
"AI 辅助生成一个新功能(实体+页面+服务流+菜单)并在本地跑门禁,产出待人工复核的部署包(恒 READY_FOR_HUMAN_REVIEW,生产写由平台阻断)。",
"""
{"type":"object",
"required":["objective","featureName","tableName","entityName","templateId","menuName","fields"],
"properties":{
"objective":{"type":"string","description":"功能目标"},
"featureName":{"type":"string"},
"tableName":{"type":"string","description":"业务表名"},
"entityName":{"type":"string"},
"templateId":{"type":"string"},
"menuName":{"type":"string"},
"fields":{"type":"array","items":{"type":"object",
"required":["column","label","type"],
"properties":{"column":{"type":"string"},"label":{"type":"string"},
"type":{"type":"string"},"length":{"type":"integer"},"required":{"type":"boolean"}}}},
"pageRecipe":{"type":"string","enum":["maintenance-crud-v1","tree-crud-v1","master-detail-v1"],"default":"maintenance-crud-v1"},
"maxRepairAttempts":{"type":"integer","default":2},
"generateDeploymentPackage":{"type":"boolean","default":true}}}
""",
this::autoDevelop),
new McpToolDef("eip4_list_page_recipes",
"列出可用的页面 recipe(maintenance-crud-v1 / tree-crud-v1 / master-detail-v1)。",
EMPTY_SCHEMA, this::listPageRecipes),
new McpToolDef("eip4_list_components",
"列出 typed page schema 注册的组件能力表(AI 只能使用其中的组件/动作)。",
EMPTY_SCHEMA, this::listComponents),
new McpToolDef("eip4_validate_page_schema",
"对一个 amis 页面 schema 做 typed schema 离线校验(不写库)。",
"""
{"type":"object","required":["schema"],
"properties":{"schema":{"type":"object","description":"待校验的 amis 页面 schema"}}}
""",
this::validatePageSchema),
new McpToolDef("eip4_access_check",
"检查某 AI employee 对某工具/目标环境的权限(生产写默认阻断)。",
"""
{"type":"object","required":["employeeId","toolName","targetEnv"],
"properties":{"employeeId":{"type":"string"},"toolName":{"type":"string"},
"grantedScopes":{"type":"array","items":{"type":"string"}},
"targetEnv":{"type":"string"},"productionWrite":{"type":"boolean"}}}
""",
this::accessCheck),
new McpToolDef("eip4_list_entities",
"列出已登记的元数据实体。",
EMPTY_SCHEMA, this::listEntities),
new McpToolDef("eip4_entity_attributes",
"查询某业务表的字段(实体属性)。",
"""
{"type":"object","required":["table"],
"properties":{"table":{"type":"string","description":"业务表名"}}}
""",
this::entityAttributes));
}
ToolResult autoDevelop(Map<String, Object> args) {
ObjectNode feature = mapper.createObjectNode();
feature.put("objective", str(args, "objective"));
feature.put("featureName", str(args, "featureName"));
feature.put("tableName", str(args, "tableName"));
feature.put("entityName", str(args, "entityName"));
feature.put("templateId", str(args, "templateId"));
feature.put("menuName", str(args, "menuName"));
feature.put("pageRecipe", strOr(args, "pageRecipe", "maintenance-crud-v1"));
feature.set("fields", mapper.valueToTree(args.getOrDefault("fields", List.of())));
ObjectNode body = mapper.createObjectNode();
body.set("feature", feature);
body.put("generateDeploymentPackage", boolOr(args, "generateDeploymentPackage", true));
body.put("maxRepairAttempts", intOr(args, "maxRepairAttempts", 2));
return forward("POST", "/api/ai/features/auto-develop", body);
}
ToolResult listPageRecipes(Map<String, Object> args) {
return forward("GET", "/api/ai/page-recipes", null);
}
ToolResult listComponents(Map<String, Object> args) {
return forward("GET", "/api/page/schema/components", null);
}
ToolResult listEntities(Map<String, Object> args) {
return forward("GET", "/api/meta/entities", null);
}
ToolResult validatePageSchema(Map<String, Object> args) {
return forward("POST", "/api/page/schema/validate", mapper.valueToTree(args.get("schema")));
}
ToolResult accessCheck(Map<String, Object> args) {
return forward("POST", "/api/ai/tools/access-check", mapper.valueToTree(args));
}
ToolResult entityAttributes(Map<String, Object> args) {
return forward("GET", "/api/meta/entity/" + str(args, "table") + "/attributes", null);
}
private ToolResult forward(String method, String path, JsonNode body) {
Eip4RestClient.Response response = client.send(method, path, body);
boolean error = response.status() < 200 || response.status() >= 300;
String text = error
? "EIP4 " + method + " " + path + " 返回 HTTP " + response.status() + ":\n" + response.body()
: response.body();
return new ToolResult(text, error);
}
private static String str(Map<String, Object> args, String key) {
Object value = args.get(key);
if (value == null) {
throw new IllegalArgumentException("缺少参数: " + key);
}
return String.valueOf(value);
}
private static String strOr(Map<String, Object> args, String key, String fallback) {
Object value = args.get(key);
return value == null || String.valueOf(value).isBlank() ? fallback : String.valueOf(value);
}
private static boolean boolOr(Map<String, Object> args, String key, boolean fallback) {
Object value = args.get(key);
if (value instanceof Boolean b) {
return b;
}
return value == null ? fallback : Boolean.parseBoolean(String.valueOf(value));
}
private static int intOr(Map<String, Object> args, String key, int fallback) {
Object value = args.get(key);
if (value instanceof Number n) {
return n.intValue();
}
if (value == null) {
return fallback;
}
try {
return Integer.parseInt(String.valueOf(value));
} catch (NumberFormatException ex) {
return fallback;
}
}
}

View File

@@ -0,0 +1,15 @@
package com.eip4.platform.mcp;
import com.fasterxml.jackson.databind.JsonNode;
/**
* EIP4 REST 调用抽象,便于单测注入。path 是相对 baseUrl 的路径(以 / 开头)。
* body 为 null 表示无请求体(GET)。
*/
interface Eip4RestClient {
Response send(String method, String path, JsonNode body);
record Response(int status, String body) {
}
}

View File

@@ -0,0 +1,48 @@
package com.eip4.platform.mcp;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
/** 基于 JDK HttpClient 的 EIP4 REST 调用实现。 */
final class JdkEip4RestClient implements Eip4RestClient {
private final HttpClient http = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
private final ObjectMapper mapper;
private final String baseUrl;
JdkEip4RestClient(String baseUrl, ObjectMapper mapper) {
this.baseUrl = baseUrl;
this.mapper = mapper;
}
@Override
public Response send(String method, String path, JsonNode body) {
try {
HttpRequest.Builder builder = HttpRequest.newBuilder()
.uri(URI.create(baseUrl + path))
.timeout(Duration.ofSeconds(60))
.header("Accept", "application/json");
if (body == null) {
builder.method(method, HttpRequest.BodyPublishers.noBody());
} else {
builder.header("Content-Type", "application/json")
.method(method, HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body)));
}
HttpResponse<String> response = http.send(builder.build(), HttpResponse.BodyHandlers.ofString());
return new Response(response.statusCode(), response.body());
} catch (InterruptedException ex) {
Thread.currentThread().interrupt();
return new Response(599, "请求被中断: " + ex.getMessage());
} catch (Exception ex) {
return new Response(599, "请求失败(baseUrl=" + baseUrl + "): " + ex);
}
}
}

View File

@@ -0,0 +1,143 @@
package com.eip4.platform.mcp;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.List;
import java.util.Map;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
class Eip4McpToolsTest {
private final ObjectMapper mapper = new ObjectMapper();
private CapturingClient client;
private Eip4McpTools tools;
@BeforeEach
void setUp() {
client = new CapturingClient();
tools = new Eip4McpTools(client, mapper);
}
@Test
void autoDevelopPostsAssembledFeatureToEndpoint() {
client.response = new Eip4RestClient.Response(200, "{\"status\":\"READY_FOR_HUMAN_REVIEW\"}");
Eip4McpTools.ToolResult result = tools.autoDevelop(Map.of(
"objective", "新增客户等级维护",
"featureName", "客户等级维护",
"tableName", "EIP4AI_CUSTOMER_LEVEL",
"entityName", "客户等级",
"templateId", "eip4ai-customer-level",
"menuName", "客户等级维护",
"fields", List.of(Map.of("column", "NAME", "label", "名称", "type", "string"))));
assertEquals("POST", client.method);
assertEquals("/api/ai/features/auto-develop", client.path);
assertEquals("EIP4AI_CUSTOMER_LEVEL", client.body.path("feature").path("tableName").asText());
assertEquals(1, client.body.path("feature").path("fields").size());
assertEquals("NAME", client.body.path("feature").path("fields").get(0).path("column").asText());
assertTrue(client.body.path("generateDeploymentPackage").asBoolean(), "default: generate deployment package");
assertFalse(result.isError());
assertTrue(result.text().contains("READY_FOR_HUMAN_REVIEW"));
}
@Test
void autoDevelopDefaultsPageRecipeWhenMissing() {
tools.autoDevelop(Map.of(
"objective", "x", "featureName", "f", "tableName", "T",
"entityName", "E", "templateId", "t", "menuName", "M",
"fields", List.of(Map.of("column", "C", "label", "标签", "type", "string"))));
assertEquals("maintenance-crud-v1", client.body.path("feature").path("pageRecipe").asText());
}
@Test
void listPageRecipesGetsEndpoint() {
client.response = new Eip4RestClient.Response(200, "[\"maintenance-crud-v1\",\"tree-crud-v1\"]");
Eip4McpTools.ToolResult result = tools.listPageRecipes(Map.of());
assertEquals("GET", client.method);
assertEquals("/api/ai/page-recipes", client.path);
assertFalse(result.isError());
assertTrue(result.text().contains("tree-crud-v1"));
}
@Test
void listComponentsAndEntitiesUseReadEndpoints() {
tools.listComponents(Map.of());
assertEquals("GET", client.method);
assertEquals("/api/page/schema/components", client.path);
tools.listEntities(Map.of());
assertEquals("GET", client.method);
assertEquals("/api/meta/entities", client.path);
}
@Test
void entityAttributesBuildsPathFromTableArg() {
tools.entityAttributes(Map.of("table", "OA_NOTICE"));
assertEquals("GET", client.method);
assertEquals("/api/meta/entity/OA_NOTICE/attributes", client.path);
}
@Test
void validatePageSchemaPostsRawSchema() {
tools.validatePageSchema(Map.of("schema", Map.of("type", "page", "body", List.of())));
assertEquals("POST", client.method);
assertEquals("/api/page/schema/validate", client.path);
assertEquals("page", client.body.path("type").asText());
}
@Test
void accessCheckPostsToToolsAccessCheck() {
tools.accessCheck(Map.of(
"employeeId", "agent-developer",
"toolName", "local.apply",
"targetEnv", "local",
"productionWrite", false));
assertEquals("POST", client.method);
assertEquals("/api/ai/tools/access-check", client.path);
assertEquals("agent-developer", client.body.path("employeeId").asText());
}
@Test
void nonSuccessStatusMarksError() {
client.response = new Eip4RestClient.Response(500, "boom");
Eip4McpTools.ToolResult result = tools.listPageRecipes(Map.of());
assertTrue(result.isError());
assertTrue(result.text().contains("boom"));
}
@Test
void toolDefsCoverAllSevenToolsWithSchema() {
List<String> names = tools.toolDefs().stream().map(Eip4McpTools.McpToolDef::name).toList();
assertTrue(names.contains("eip4_auto_develop"));
assertTrue(names.contains("eip4_list_page_recipes"));
assertTrue(names.contains("eip4_list_components"));
assertTrue(names.contains("eip4_validate_page_schema"));
assertTrue(names.contains("eip4_access_check"));
assertTrue(names.contains("eip4_list_entities"));
assertTrue(names.contains("eip4_entity_attributes"));
tools.toolDefs().forEach(d -> assertFalse(d.inputSchemaJson().isBlank(), "schema required: " + d.name()));
}
private static final class CapturingClient implements Eip4RestClient {
private Response response = new Response(200, "{}");
private String method;
private String path;
private JsonNode body;
@Override
public Response send(String method, String path, JsonNode body) {
this.method = method;
this.path = path;
this.body = body;
return response;
}
}
}