场景一：扩展现有 MCP 服务的工具

示例：在 iServer MCP Server 已有的“地图服务”上，新增一个名为getMapParameter的新工具，用于获取地图详细参数。因为只涉及扩展现有的MCP工具，所以在此只需实现MCP 工具层，按以下步骤操作。开始前请先完成开发准备中的示例工程获取与 Maven 项目配置。

步骤 1：添加 MCP 工具类代码

创建ExtendedMapTools.java类，实现McpToolMaterial接口，核心是封装getMapParameter方法（用于获取地图参数）

代码示例：

```java
package com.supermap.mcp.extension.tool;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.supermap.services.components.MapException;
import com.supermap.services.components.commontypes.MapParameter;
import com.supermap.services.components.impl.MapImpl;
import com.supermap.services.mcp.McpContext;
import com.supermap.services.mcp.material.McpToolMaterial;
import com.supermap.services.rest.util.JsonConverter;
import org.apache.commons.collections4.CollectionUtils;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

import java.util.List;

/**
* 这是一个针对现有地图服务的工具扩展。
* 它实现了 McpToolMaterial 接口。
*/
public class ExtendedMapTools implements McpToolMaterial {
private MapImpl mapImpl;

/**
* 在 init 方法中，从 McpContext 获取正在运行的地图服务组件（MapImpl）实例。
* 框架会自动将当前MCP服务实例的组件注入到上下文中。
*/
@Override
public boolean init(McpContext context) {
List<?> bizComponents = context.getBizComponents();
if (CollectionUtils.isNotEmpty(bizComponents)) {
for (Object bizComponent : bizComponents) {
// 找到 MapImpl 类型的组件并持有它
if (bizComponent instanceof MapImpl) {
this.mapImpl = (MapImpl) bizComponent;
return true; // 初始化成功
}
}
}
return false; // 如果没有找到，则初始化失败
}

/**
* 定义模块名称。此名称将用于关联国际化资源文件。
*/
@Override
public String mcpModuleName() {
return "extended-map";
}

/**
* 使用 @Tool 注解定义一个新的MCP工具。
* 'description' 属性的值是一个key，框架会用它去资源文件中查找对应的多语言描述。
*/
@Tool(description = "getMapParameter.description")
public JSONObject getMapParameter(@ToolParam(description = "getMapParameter.params.mapName") String mapName) throws MapException {
// 调用持有的 mapImpl 实例的业务方法
MapParameter mapParameter = mapImpl.getMapParameter(mapName);
return JSON.parseObject(JsonConverter.toJson(mapParameter));
}
}
```

步骤 2：声明扩展模块

在 src/main/resources/META-INF/services/mcp/ 目录下创建一个 .properties 文件（例如 extended-map.properties）来声明扩展模块

# 模块的唯一名称，与工具类中的 mcpModuleName() 返回值保持一致
mcp.moduleName=extended-map

# 关键！使用 mcp.bizComponentType 指明这个扩展是针对哪个已有的服务组件。
# 这里我们指向 iServer 内置的地图服务组件 MapImpl。
# 注意：在场景一中，此属性名应为 mcp.bizComponentType
mcp.bizComponentType=com.supermap.services.components.impl.MapImpl

# 声明此模块包含的工具实现类
mcp.tool.impls=com.supermap.mcp.extension.tool.ExtendedMapTools

此处附上扩展当前已有 MCP 服务与所需组件的映射关系表

MCP 服务	所需组件
地图服务	com.supermap.services.components.impl.MapImpl
数据服务	com.supermap.services.components.impl.DataImpl
空间分析服务	com.supermap.services.components.impl.SpatialAnalystImpl
交通换乘分析服务	com.supermap.services.components.impl.TrafficTransferAnalystImpl
交通网络分析服务	com.supermap.services.components.impl.TransportationAnalystImpl
地址匹配服务	com.supermap.services.components.impl.AddressMatchImpl
三维网络分析服务	com.supermap.services.components.impl.NetworkAnalyst3DImpl

步骤 3：添加国际化描述

为了让 AI 理解工具功能，需要提供中英文描述的YAML文件，该文件名称必须遵循特定格式：{模块名}_{语言}.yaml。

{模块名}：即您在 .properties 文件中定义的 mcp.moduleName。

{语言}：zh 代表中文，en 代表英文。

例如，对于 mcp.moduleName=extended-map，对应的文件就是 extended-map_zh.yaml 和 extended-map_en.yaml。
在src/main/resources/META-INF/services/mcp/tools/目录下，创建extended-map_zh.yaml（中文描述）

getMapParameter:
description: 获取指定地图的详细参数信息
params:
mapName: 地图名称

同理创建extended-map_en.yaml（英文描述），替换对应文字即可。

步骤 4：打包扩展成果

在项目根目录下执行 mvn clean install，这将在 target/ 目录下生成扩展的核心JAR包（例如 mcp-service-tool-extension-1.0-SNAPSHOT.jar）。
如果您的项目引入了 third-party-dependencies.txt 中不存在的第三方依赖，请执行 mvn dependency:copy-dependencies -DincludeScope=runtime，这会将这些依赖JAR包复制到 target/dependency/ 目录下。

至此，已完成了新增getMapParameter工具的JAR包制作，还需继续部署、集成与测试。

步骤 5：部署、集成与测试

1、部署扩展包：

将上一步打包生成的核心JAR包 (mcp-service-tool-extension-1.0-SNAPSHOT.jar) 复制到 AgentX Server 的 cfg/iserver_mcp/extensions 目录下。
如果存在 target/dependency/ 目录，请将其中的所有第三方依赖JAR包也复制到 cfg/iserver_mcp/extensions 目录。

2、重启服务节点：

重启 iserver-mcp-server Docker 节点以加载新的扩展。

3、完成与验证：

此场景无需任何XML配置。重启后，所有已发布的地图MCP服务都将自动包含您新添加的 getMapParameter 工具。

如需从零发布一个全新的 MCP 服务（而不是在现有服务上追加工具），请参考场景二：开发全新的领域 MCP 服务。