Astrsomn 文档

中文

English

中文

English

Appearance

MCP 开发 ​

本章节介绍如何开发自定义 MCP（Model Context Protocol）协议插件，扩展 Astrsomn 的上下文管理能力。

概述 ​

MCP（Model Context Protocol）插件负责管理 AI 模型与外部 MCP 服务之间的传输协议。Astrsomn 通过 McpProtocolHandler 接口支持多种传输方式。

注意

旧版文档中的 McpHandler 接口并 不存在。实际的接口是 McpProtocolHandler，位于 com.astrsomn.starter.runtime.langchain.tool.mcp.protocol。

已内置的协议实现 ​

实现类协议类型说明
SseProtocolHandlerSSE基于 HTTP SSE（Server-Sent Events）的 MCP 传输
StdioProtocolHandlerSTDIO基于子进程标准输入输出的 MCP 传输

开发步骤 ​

1. 创建 Maven 模块 ​

xml
<project>
    <groupId>com.astrsomn</groupId>
    <artifactId>astrsomn-mcp-custom</artifactId>
    <version>0.2.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.astrsomn</groupId>
            <artifactId>astrsomn-api-runtime</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>

        <!-- LangChain4j MCP 支持 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-mcp</artifactId>
        </dependency>
    </dependencies>
</project>

2. 实现 McpProtocolHandler ​

McpProtocolHandler 只有两个方法：supports() 判断是否支持该传输类型，createTransport() 构建传输实例：

java
package com.astrsomn.mcp.custom;

import com.astrsomn.api.runtime.common.entity.AiMcpEntity;
import com.astrsomn.starter.runtime.langchain.tool.mcp.protocol.McpProtocolHandler;
import dev.langchain4j.mcp.client.transport.McpTransport;

import java.io.IOException;

public class CustomMcpProtocolHandler implements McpProtocolHandler {

    @Override
    public boolean supports(String type) {
        // 判断是否支持该传输类型
        // type 来自 AiMcpEnum.TypeEnum
        return "CUSTOM".equalsIgnoreCase(type);
    }

    @Override
    public McpTransport createTransport(AiMcpEntity config) throws IOException {
        // 根据配置构建 McpTransport 实例
        // config 包含 MCP 服务器的连接参数（地址、端口、认证信息等）

        // 示例：构建一个自定义的 WebSocket 传输
        String address = config.getAddress();
        int port = config.getPort();

        return new CustomWebSocketMcpTransport(address, port);
    }
}

McpTransport

McpTransport 是 LangChain4j 的 MCP 客户端传输接口。你需要实现该接口来定义具体的通信方式（HTTP、WebSocket、gRPC 等）。参考 LangChain4j 的 HttpMcpTransport 和 StdioMcpTransport 实现。

3. 注册 SPI ​

在 src/main/resources/META-INF/services/ 下创建文件：

文件： com.astrsomn.starter.runtime.langchain.tool.mcp.protocol.McpProtocolHandler

com.astrsomn.mcp.custom.CustomMcpProtocolHandler

4. 创建扩展属性（可选） ​

properties
# src/main/resources/extension-mcp-custom.properties
name=Custom MCP Protocol
version=0.2.0-SNAPSHOT
description=基于 WebSocket 的自定义 MCP 协议实现

接口规范 ​

McpProtocolHandler ​

包路径： com.astrsomn.starter.runtime.langchain.tool.mcp.protocol

方法返回值说明
supports(String type)boolean判断是否支持指定的传输类型
createTransport(AiMcpEntity config)McpTransport根据配置创建 MCP 传输实例

传输类型枚举 ​

AiMcpEnum.TypeEnum：

类型说明
SSEServer-Sent Events（已内置）
STDIO标准输入输出子进程（已内置）

扩展新类型

如需支持新的传输类型（如 WebSocket），需要先在 AiMcpEnum.TypeEnum 中添加枚举值，然后实现对应的 McpProtocolHandler。

打包部署 ​

bash
# 打包插件
mvn clean package -DskipTests

# 复制 JAR 到 plugins 目录
cp target/astrsomn-mcp-custom-0.2.0-SNAPSHOT.jar /path/to/astrsomn/plugins/

参考实现 ​

查看现有实现源码作为参考：

  • SSE — astrsomn-runtime-starter/.../mcp/protocol/SseProtocolHandler.java — 基于 HttpMcpTransport
  • STDIO — astrsomn-runtime-starter/.../mcp/protocol/StdioProtocolHandler.java — 基于 StdioMcpTransport

相关文档 ​