Publish AgentForge's library modules to Maven Central as the official 1.0.0 release, so that users can import them directly through a Maven dependency.

When working on an open source project, we often run into a very concrete problem: the project runs fine on GitHub, but people who want to use it don't know how to import it. Either they git clone it and run mvn install themselves, or they pass the jar around, which is a terrible experience. The most elegant approach is to publish it to the official Maven Central repository, so that users only need to declare one dependency coordinate in pom.xml.

AgentForge's model layer and Agent Runtime were already ready for release, so we decided to formally push them to Maven Central. During the whole process, the first stumbling block was how to define the groupId namespace. This article records this complete practice.

1. Background and Problem​

1.1 Why Publish to Maven Central​

• Zero barrier to use: users only need to declare a dependency coordinate, with no need to clone or compile;
• Ecosystem recognition: it can be indexed by IDEs and dependency platforms (such as mvnrepository), which counts as the "official identity" of an open source project;
• Reuse across projects: combined with a BOM for unified version management, it facilitates future modular evolution.

1.2 The Problem We Encountered​

When publishing AgentForge, coordinate naming (groupId) is the first hurdle that cannot be avoided:

• Early on, the project used com.changlu.agentforge;
• But Maven Central requires that the groupId must be a namespace you can prove you "own / control". Reversing com.changlu gives the domain changlu.com, which we do not own, so verification would be rejected.

So the question becomes: for a personal open source project, how exactly should the groupId be chosen? This is the core concept that this article will clarify first.

2. Core Concepts​

2.1 Hard Requirements for Publishing to Maven Central​

Before getting started, you must first know what validations Central performs on uploaded artifacts. It is not a matter of "upload and you're done"; it requires satisfying all of the following at the same time:

1. sources jar + javadoc jar (required for modules not packaged as pom);
2. GPG/PGP signature: each file needs a .asc signature file;
3. Checksums: .md5 / .sha1 are required (.sha256 / .sha512 are optional), generated automatically by the publishing plugin;
4. Required POM metadata: name, description, url, licenses, developers, scm;
5. The version number must not end with -SNAPSHOT.

Key point: if any one of the above is not satisfied, the release will fail at the Portal validation stage. All subsequent configuration in this article is built around these 5 items.

2.2 Two Sources of groupId Namespace (Scheme Comparison)​

For personal / small-team projects, there are commonly two paths for a groupId namespace:

Scheme 1: Based on a GitHub Account — io.github.<username>​

• Rule: io.github.myusername, for example io.github.changluya;
• Verification method: no domain is needed. Sonatype requires you to create a public repository with the name specified by the Portal under the corresponding GitHub account to prove account ownership; once verified, you can delete it.

Scheme 2: Based on Your Own Domain — Reverse Domain​

• Rule: if you own example.com, use com.example; if you own changlu.cloud, use cloud.changlu, and you can further add a project subspace such as cloud.changlu.agentforge;
• Verification method: add a TXT record given by the Portal to that domain's DNS.

Comparison of the Two Schemes​

Drawbacks: although Scheme 1 is zero cost, the name carries the GitHub account name (such as changluya), which is neither attractive nor changeable; once the account is renamed, historical coordinates no longer match the name. Scheme 2 requires you to actually own and be able to operate the domain DNS, but the long-term benefit is greater.

2.3 The Choice of This Scheme​

This scheme adopts Scheme 2: the namespace is cloud.changlu, and the project subspace is cloud.changlu.agentforge.

Therefore, all the preparatory work below (DNS TXT for namespace verification, Token, GPG, settings) is written for the "own domain" path.

Note: if you want to switch to Scheme 1, you only need to change the namespace to io.github.changluya and replace "DNS TXT verification" with "create a public GitHub repository". All other steps (GPG / Token / settings.xml / project modification / publishing process) are completely identical.

3. Overall Scheme Design​

3.1 Which Modules to Publish​

AgentForge is a multi-module project, and not all modules need to be published externally. We publish the library modules and exclude the example modules:

3.2 The Publishing Pipeline​

本地构建
  → 各模块生成 sources / javadoc jar
  → 各模块 GPG 签名（.asc）
  → central-publishing-maven-plugin 打包成 bundle
  → 上传到 Sonatype Central Portal 校验
  → Portal 发布 → 同步到 Maven Central

Key point: Sonatype's central-publishing-maven-plugin packages the artifacts of the entire reactor into a single bundle for upload, so we only need to configure it once in the parent, and simply exclude the example modules using excludeArtifacts.

3.3 Is a Script Needed?​

Configuring a script is recommended. Encapsulating "version validation → local signing and packaging dry run → formal deploy" into a release.sh avoids typing long commands by hand and missing parameters every time. The script contents are in Section 7.

Day-to-day development still uses mvn install / test; only releases go through the script.

4. Prerequisites (Account / Domain / Keys)​

This section explains the "own domain" path. If you use the GitHub approach, see the explanation in 2.2.

4.1 Register for Sonatype Central Portal​

Open https://central.sonatype.com/, register and log in with your email / GitHub, and remember this account — namespaces, Tokens, and publishing are all managed here later.

On first entry, because you logged in with GitHub, the selected namespace is the following default namespace space:

4.2 Add and Verify the Namespace cloud.changlu (Own Domain Path)​

How do you complete namespace verification? The steps are as follows:

1. Log in to the Portal → top-right Account → Namespaces (or Add Namespace on the home page);
2. Enter cloud.changlu and submit;
   • Note: verification targets the domain itself, changlu.cloud; cloud.changlu is merely its reverse namespace;

3. The Portal gives a Verification Key; go to the DNS provider of changlu.cloud and add a TXT record:

   • Host record: @ (the root domain changlu.cloud)
   • Record type: TXT
   • Record value: the verification value given by the Portal (paste it in full)

   

4. How do you verify whether the TXT has taken effect? Run locally:

   dig -t txt changlu.cloud
   # 或
   host -t txt changlu.cloud
   

   Being able to see the TXT value you added is sufficient.

5. Return to the Portal and click Verify; the status changes to Verified.

Note: DNS has caching; right after adding it you may need to wait anywhere from a few minutes to tens of minutes; domestic DNS providers may take longer.

Key point: once a namespace is approved, its sub-namespaces (cloud.changlu.agentforge) do not need to be verified again and can be published directly.

4.3 Install GPG, Generate a Key, and Upload the Public Key (Including Common Failure Troubleshooting)​

This section is organized as "install → configure → generate → sign self-check → upload and reverse lookup → backup". Except for the name, public email, and Passphrase in the key wizard, which you must enter manually, the command blocks can all be copied and executed in order. The examples do not contain any real keys, passphrases, or Tokens.

Step 0: First confirm whether GPG already exists on this machine:

gpg --version

• If there is output and it is >= 2.2 → skip directly to 4.3.2;
• If it says command not found → install it as described below.

4.3.1 Choose the Installation Method by Operating System​

macOS​

Check the macOS version first, then choose the installation path:

sw_vers -productVersion
uname -m

Homebrew only continues to produce prebuilt bottles for currently supported macOS versions. Older macOS versions may be classified as Tier 3, in which case brew install gnupg will switch to compiling large dependencies such as OpenSSL from source, which is time-consuming and easily interrupted. Taking the official support matrix as of 2026-10 as an example, on Apple Silicon, macOS 15–27 can use bottles, while macOS 11–14 are Tier 3. Please refer to the real-time description in Homebrew Support Tiers.

Path A: Homebrew (currently supported macOS)​

brew --version
brew install gnupg pinentry-mac
command -v gpg
gpg --version

When a matching bottle exists, Homebrew downloads the prebuilt package automatically, with no need to add --force-bottle manually. If it reports has no bottle or spends a long time on build.rb / compiling openssl@3, it means the current system has no matching binary package; do not repeatedly launch brew install, and switch directly to Path B or C.

On Apple Silicon, Homebrew is under /opt/homebrew by default; if command -v gpg produces no output, run eval "$(/opt/homebrew/bin/brew shellenv)" and write that line into ~/.zprofile. On Intel Mac, the default prefix is /usr/local.

Path B: MacPorts (recommended for older macOS, binary packages available)​

1. Download the .pkg matching your macOS major version (for example Sonoma 14) from the MacPorts official installation page and install it;
2. Open a new terminal and run:

cd /tmp
sudo /opt/local/bin/port selfupdate
# 使用默认 +pinentry（终端口令输入器），不需要完整 Xcode
sudo /opt/local/bin/port install gnupg2

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
command -v gpg && gpg --version

MacPorts installs to /opt/local by default. If PATH does not take effect automatically:

echo 'export PATH="/opt/local/bin:/opt/local/sbin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Do not add +pinentry_mac on a machine that only has Command Line Tools installed. MacPorts' pinentry-mac port requires a full Xcode, otherwise it reports requires a full Xcode installation. Maven Central signing only needs the default terminal-based pinentry. If you have already started a build with the wrong variant, clean the port's temporary build directory first, then install the default variant:

cd /tmp
sudo /opt/local/bin/port clean gnupg2
sudo /opt/local/bin/port install gnupg2

port clean gnupg2 only cleans the port's temporary build artifacts; it does not delete project files or uninstall other already-installed dependencies.

Path C: GPG Suite (a fast GUI option)​

Download an installer compatible with your current macOS from the GPG Suite website. It bundles MacGPG, GPG Keychain, and pinentry, and does not require compiling OpenSSL with Homebrew. GPG Mail is an optional email plugin, and publishing to Maven Central does not need it.

/usr/local/MacGPG2/bin/gpg --version
echo 'export PATH="/usr/local/MacGPG2/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Linux / WSL​

GnuPG is usually already provided in Linux distributions. For WSL, run the same commands according to its Linux distribution:

# Debian / Ubuntu / WSL Ubuntu
sudo apt update
sudo apt install -y gnupg2 pinentry-curses

# Fedora / RHEL
sudo dnf install -y gnupg2 pinentry

gpg --version

For SSH, CI, or pure terminal environments, it is recommended to use pinentry-curses and set it in the current shell:

export GPG_TTY="$(tty)"

Windows 10/11​

Download the installer from the Gpg4win website. Publishing to Maven Central only needs GnuPG and pinentry; Kleopatra can be used for GUI key management. After installation, reopen PowerShell and verify:

gpg --version
where.exe gpg

If gpg is not on PATH, add Gpg4win's bin directory to the user PATH, then reopen PowerShell.

When Are Command Line Tools Actually Needed​

If installing gnupg via Homebrew reports the following error:

Error: No developer tools installed.
Install the Command Line Tools:
  xcode-select --install

It means the system lacks Command Line Tools — even if /usr/bin/clang exists, as long as there is no "active developer directory" it will report this. First run:

xcode-select --install

An installation window pops up; click Install / 安装 and wait for the download and installation to finish (a few minutes). After completion, confirm:

xcode-select -p
# 期望输出：/Library/Developer/CommandLineTools

Note: when installing a bottle, Apple Silicon usually does not need CLT; it is only required when compiling from source. If you already have full Xcode installed, you can also use sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.

4.3.2 Verify PATH and Configure pinentry​

First confirm that Maven can later find the same gpg through PATH:

command -v gpg
gpg --version
command -v pinentry || true

command -v gpg must output a real path; then run the corresponding environment command below.

On macOS/Linux it is recommended to write GPG_TTY into the shell config to prevent the passphrase prompt from binding to the wrong terminal:

# zsh（macOS 默认）
grep -qxF 'export GPG_TTY="$(tty)"' ~/.zshrc 2>/dev/null || \
  echo 'export GPG_TTY="$(tty)"' >> ~/.zshrc
export GPG_TTY="$(tty)"

bash users run:

grep -qxF 'export GPG_TTY="$(tty)"' ~/.bashrc 2>/dev/null || \
  echo 'export GPG_TTY="$(tty)"' >> ~/.bashrc
export GPG_TTY="$(tty)"

On macOS, the most common errors from gpg --full-generate-key are No pinentry or Inappropriate ioctl for device, caused by not finding the passphrase input program:

Homebrew users can copy directly:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
PINENTRY="$(brew --prefix)/bin/pinentry-mac"
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo "pinentry-program $PINENTRY" >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

MacPorts users can copy directly:

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo 'pinentry-program /opt/local/bin/pinentry' >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

For Linux pure-terminal users who need to explicitly configure pinentry-curses:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo "pinentry-program $(command -v pinentry-curses)" >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

GPG Suite and Gpg4win already bundle and configure pinentry, so you usually do not need to write gpg-agent.conf manually. MacPorts' default /opt/local/bin/pinentry is the terminal version and can be used directly for Maven signing.

4.3.3 Generate a Key Pair​

On a personal local machine, interactive mode is recommended, letting pinentry read the Passphrase securely and avoiding writing the passphrase into shell history or a config file:

export GPG_TTY="$(tty)" 2>/dev/null || true
gpg --full-generate-key
# RSA and RSA → 4096 → 有效期（例如 2y）→ 姓名/邮箱 → 设置强 Passphrase

Recommended values:

• Type: RSA and RSA;
• Length: 4096;
• Validity: 2y is recommended; it can be renewed before expiry, which makes risk easier to manage than a permanent key;
• Name/email: use the publisher identity that will maintain Maven Central artifacts over the long term;
• Passphrase: use a strong passphrase; do not write it into the repository, scripts, or shell history.

For CI scenarios, you can use --batch to generate a dedicated key, but it is not recommended to use %no-protection as the default option for a personal publishing key. If you must use a passphrase-less CI key, limit its purpose, set an expiry, and store the private key only in a CI Secret.

4.3.4 View and Record the KEY_ID​

gpg --list-secret-keys --keyid-format=long
# sec   rsa4096/ABCDEF1234567890 2026-10-04 ...
#              ^^^^^^^^^^^^^^^^ 即 KEY_ID

Also record the full 40-character fingerprint; when verifying keys externally you should prefer the fingerprint rather than only comparing the short KEY_ID:

# 自动取当前密钥环中的第一把私钥
KEY_ID="$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')"
FULL_FINGERPRINT="$(gpg --batch --with-colons --fingerprint "$KEY_ID" | awk -F: '$1 == "fpr" { print $10; exit }')"

test -n "$KEY_ID" && test -n "$FULL_FINGERPRINT" || {
  echo 'ERROR: 未找到私钥或指纹'
  exit 1
}
echo "KEY_ID=$KEY_ID"
echo "FULL_FINGERPRINT=$FULL_FINGERPRINT"
gpg --fingerprint "$KEY_ID"

If there are already multiple private keys in the keyring, first find the key created this time via gpg --list-secret-keys --keyid-format=long, then manually run KEY_ID="16位长KEY_ID". Subsequent commands are executed in the same terminal by default and reuse these two variables.

4.3.5 Local Signing and Signature Verification (Must Do Before Release)​

This step simultaneously verifies the private key, pinentry, Passphrase, and GPG agent, making it easier to locate problems than running Maven directly:

# 即使换了新终端，也能自动恢复变量
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"

echo 'AgentForge Maven Central GPG signing test' > /tmp/agentforge-gpg-test.txt

gpg --local-user "$KEY_ID" \
  --armor \
  --detach-sign /tmp/agentforge-gpg-test.txt

gpg --verify \
  /tmp/agentforge-gpg-test.txt.asc \
  /tmp/agentforge-gpg-test.txt

Seeing Good signature / 完好的签名 means the local signing pipeline is working. The test file is located in /tmp; do not commit it to the project.

4.3.6 Upload the Public Key and Reverse-Look It Up from the Server​

# 自动恢复 KEY_ID 与完整指纹
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
FULL_FINGERPRINT="${FULL_FINGERPRINT:-$(gpg --batch --with-colons --fingerprint "$KEY_ID" | awk -F: '$1 == "fpr" { print $10; exit }')}"

# 主用：Ubuntu 服务器（较稳定）
gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "$KEY_ID"

# 备用：主用超时时改用它
gpg --keyserver hkps://keys.openpgp.org --send-keys "$KEY_ID"

# 上传后请使用完整指纹反查，不要只用短 KEY_ID
curl -fsSL \
  "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x${FULL_FINGERPRINT}" \
  | grep 'BEGIN PGP PUBLIC KEY BLOCK'

Outputting BEGIN PGP PUBLIC KEY BLOCK means the keyserver can already return that public key. There may be a brief indexing delay right after upload; just wait a few tens of seconds and check again.

Note: keys.openpgp.org strips user identity, and requires you to confirm via an email link before the upload actually counts as successful; Maven Central more often pulls from keyserver.ubuntu.com, so prefer ubuntu.

4.3.7 Back Up the Private Key and ownertrust​

The public key can be public, but the private key must be stored encrypted. When backing up, first restrict the file permissions of the current shell:

umask 077
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
GPG_BACKUP_DIR="$HOME/agentforge-gpg-backup"
mkdir -p "$GPG_BACKUP_DIR"
chmod 700 "$GPG_BACKUP_DIR"

gpg --armor --export-secret-keys "$KEY_ID" \
  > "$GPG_BACKUP_DIR/agentforge-private-key.asc"
gpg --export-ownertrust \
  > "$GPG_BACKUP_DIR/agentforge-ownertrust.txt"
chmod 600 "$GPG_BACKUP_DIR"/*

$HOME/agentforge-gpg-backup is only a temporary export location. Encrypted disks, offline media, or password managers that support secure attachments are the appropriate long-term backup locations. Delete the temporary directory after the transfer is complete; do not commit it to Git, do not upload plaintext to cloud storage, and do not send the private key or Passphrase to anyone else.

4.3.8 Complete Acceptance Checklist​

command -v gpg
gpg --version
gpg --list-secret-keys --keyid-format=long
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
gpg --fingerprint "$KEY_ID"
gpg --verify /tmp/agentforge-gpg-test.txt.asc /tmp/agentforge-gpg-test.txt

Section 4.3 is only considered complete after all of the following conditions are met:

• gpg can be found through PATH;
• The private key, long KEY_ID, and full fingerprint are visible;
• The detached signature verifies successfully locally;
• The Ubuntu keyserver can return the public key by full fingerprint;
• The private key and ownertrust have been safely backed up outside the repository;
• The KEY_ID has been recorded for use by the Maven GPG plugin.

4.3.9 Common Failures and Troubleshooting​

Note: the private key and Passphrase are only used locally / in CI; do not commit them to the repository. Only the public key, KEY_ID, and fingerprint are public.

4.4 Generate a Portal User Token​

1. Log in to https://central.sonatype.com/;

2. Open the user menu at the top right and click View User Tokens (or go to https://central.sonatype.com/account);

   

   

3. Generate a Token on the User Tokens page to get a username / password pair (this is a Token, not the login password); it is shown only once, so save it immediately.

4.5 Configure Maven settings.xml​

You can use Maven's default location ~/.m2/settings.xml, or place it in a separate directory outside the repository and specify it at release time via mvn -s /absolute/path/settings.xml. The configuration below does not write the GPG Passphrase in plaintext into the XML:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <!-- Central Portal 的 User Token -->
        <server>
            <id>central</id>
            <username>YOUR_CENTRAL_TOKEN_USERNAME</username>
            <password>YOUR_CENTRAL_TOKEN_PASSWORD</password>
        </server>

    </servers>
</settings>

Restrict the file permissions:

chmod 600 /absolute/path/settings.xml

Before releasing, securely read the GPG Passphrase in the current terminal; the input is not echoed and does not enter shell history:

printf 'GPG Passphrase: '
IFS= read -r -s MAVEN_GPG_PASSPHRASE
printf '\n'
export MAVEN_GPG_PASSPHRASE

When using a custom configuration file, the Maven command must include -s:

mvn -s /absolute/path/settings.xml help:effective-settings

Key point: <server id="central"> corresponds to the publishing plugin's publishingServerId; do not write it as ${server}. Maven GPG Plugin 3.2.x reads the passphrase from MAVEN_GPG_PASSPHRASE by default, so there is no longer any need to add a gpg server in settings.xml.

settings.xml contains the Central Token and must not be committed to Git. This article only uses placeholders and does not show any real Token or Passphrase.

5. Project Build Modifications (POM)​

Why are only two files changed for the core release configuration? Because the parent of this repository's modules is agentforge-ai-parent, and the root agentforge-aggregator is not the parent of the modules, therefore:

• Plugins needed by all modules (source/javadoc/gpg/central) → put in agentforge-ai-parent;
• The root aggregator itself is not published → add maven.deploy.skip=true to the root POM.

Central also requires every published POM to have a complete description; if a sub-aggregator module originally lacks a <description>, it must be added in that module's POM. In this project these correspond to agentforge-model/pom.xml and agentforge-framework/pom.xml.

All modifications go into the release profile, so day-to-day mvn install / test does not trigger them and the behavior is unchanged.

5.1 Root pom.xml​

Add to <properties> (only affects the root aggregator itself):

<properties>
    <revision>1.0.0-SNAPSHOT</revision>
    <!-- 根聚合器不发布到 Central -->
    <maven.deploy.skip>true</maven.deploy.skip>
    ...
</properties>

5.2 Complete the Metadata in agentforge-ai-parent/pom.xml​

Add after <licenses>...</licenses>:

<developers>
    <developer>
        <id>changlu</id>
        <name>changlu</name>
        <email>YOUR_PUBLIC_EMAIL_OR_NOREPLY_EMAIL</email>
        <url>https://changlu.cloud</url>
        <organization>AgentForge</organization>
        <organizationUrl>https://github.com/changluya/AgentForge</organizationUrl>
    </developer>
</developers>

<scm>
    <connection>scm:git:https://github.com/changluya/AgentForge.git</connection>
    <developerConnection>scm:git:ssh://git@github.com/changluya/AgentForge.git</developerConnection>
    <tag>HEAD</tag>
    <url>https://github.com/changluya/AgentForge</url>
</scm>

licenses / developers / scm are inherited by submodules and can be read during Central validation; name / description already exist in the current modules. If validation reports a missing url, add <url> in the parent or complete it module by module.

5.3 Add a release Profile to agentforge-ai-parent/pom.xml​

First declare the plugin versions collectively in the existing <properties>:

<gpg.executable>gpg</gpg.executable>
<!-- 公开指纹：固定发布密钥，避免多私钥环境误签 -->
<gpg.keyname>YOUR_FULL_GPG_FINGERPRINT</gpg.keyname>
<maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
<maven.javadoc.plugin.version>3.11.2</maven.javadoc.plugin.version>
<maven.source.plugin.version>3.3.1</maven.source.plugin.version>
<central.publishing.maven.plugin.version>0.11.0</central.publishing.maven.plugin.version>

Then add before </project>:

<profiles>
    <profile>
        <id>release</id>
        <build>
            <plugins>
                <!-- 1) 为每个待发布 JAR 附加 Central 必需的 sources JAR -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-source-plugin</artifactId>
                    <version>${maven.source.plugin.version}</version>
                    <executions>
                        <execution>
                            <id>attach-sources</id>
                            <goals><goal>jar-no-fork</goal></goals>
                        </execution>
                    </executions>
                </plugin>

                <!-- 2) 附加 Central 必需的 Javadoc JAR；放宽 doclint，避免文档告警阻断发布 -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>${maven.javadoc.plugin.version}</version>
                    <configuration>
                        <doclint>none</doclint>
                        <quiet>true</quiet>
                    </configuration>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals><goal>jar</goal></goals>
                        </execution>
                    </executions>
                </plugin>

                <!-- 3) verify 阶段签名 POM 及全部附件；口令来自 gpg-agent 或 MAVEN_GPG_PASSPHRASE -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-gpg-plugin</artifactId>
                    <version>${maven.gpg.plugin.version}</version>
                    <configuration>
                        <!-- 脚本会用 -Dgpg.executable 覆盖为 MacPorts / Homebrew 绝对路径 -->
                        <executable>${gpg.executable}</executable>
                        <keyname>${gpg.keyname}</keyname>
                        <bestPractices>true</bestPractices>
                    </configuration>
                    <executions>
                        <execution>
                            <id>sign-artifacts</id>
                            <goals><goal>sign</goal></goals>
                            <phase>verify</phase>
                        </execution>
                    </executions>
                </plugin>

                <!-- 4) 将 reactor 构件汇总为一个 Central Portal deployment；首发保留手动 Publish -->
                <plugin>
                    <groupId>org.sonatype.central</groupId>
                    <artifactId>central-publishing-maven-plugin</artifactId>
                    <version>${central.publishing.maven.plugin.version}</version>
                    <extensions>true</extensions>
                    <configuration>
                        <publishingServerId>central</publishingServerId>
                        <!-- 首次建议 false：上传后到 Portal 手工检查再发布 -->
                        <autoPublish>false</autoPublish>
                        <!-- 排除示例模块，避免被打进上传 bundle -->
                        <excludeArtifacts>
                            <excludeArtifact>agentforge-examples</excludeArtifact>
                            <excludeArtifact>agentforge-service</excludeArtifact>
                            <excludeArtifact>agentforge-service-ui</excludeArtifact>
                            <excludeArtifact>agentforge-service-web</excludeArtifact>
                        </excludeArtifacts>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

Key points:

• extensions=true lets the plugin take over deploy and upload the entire reactor as one bundle;
• excludeArtifacts excludes by artifactId, ensuring the service applications do not enter the bundle;
• bestPractices=true forbids passing a plaintext GPG passphrase in the POM / XML; use MAVEN_GPG_PASSPHRASE before releasing;
• autoPublish=false (first time) requires manually clicking Publish in the Portal after upload; once stable, you can change it to true and add <waitUntil>published</waitUntil>.

5.4 Version Number Strategy​

• The project uses ${revision} to manage the version; flatten-maven-plugin is already configured with resolveCiFriendliesOnly, so ${revision} is resolved to the actual version before deployment;

• Do not modify files at release time; just override on the command line:

  -Drevision=1.0.0
  

Drawbacks: an official release cannot be 1.0.0-SNAPSHOT; and a Central version cannot be overwritten once published, so please increment the version number on every release.

5.5 Local Verification Step 5 (No Signing, No Upload)​

Run in the repository root directory. Here we select only the 11 modules that will actually be published, to avoid the service application project downloading a large number of irrelevant dependencies:

SETTINGS_FILE="/absolute/path/settings.xml"
RELEASE_MODULES='agentforge-ai-parent,agentforge-ai-bom,agentforge-model,agentforge-model/agentforge-model-api,agentforge-model/agentforge-model-core,agentforge-model/agentforge-model-openai,agentforge-model/agentforge-model-anthropic,agentforge-model/agentforge-model-registry,agentforge-framework,agentforge-framework/agentforge-agent-core,agentforge-framework/agentforge-harness-agent'

mvn -s "$SETTINGS_FILE" \
  -P release \
  -Drevision=1.0.0 \
  -DskipTests \
  -Dgpg.skip=true \
  -pl "$RELEASE_MODULES" \
  verify

Expected result: the log shows Inspecting build with total of 10 modules, Installing Central Publishing features, and finally BUILD SUCCESS. In the target/ of each JAR module there should also be:

<artifactId>-1.0.0.jar
<artifactId>-1.0.0-sources.jar
<artifactId>-1.0.0-javadoc.jar

-Dgpg.skip=true is only used for the POM / artifact structure verification in step 5; step 6's dry run and the formal release must remove it to ensure Central receives the .asc signatures.

6. Real-World Publishing and One-Click Deployment​

This section is the linear runbook compiled after AgentForge 1.0.0 was actually run through successfully. Subsequent release personnel do not need to piece together Maven parameters by hand; start from 6.1 and execute in order, and do not proceed to the next step if any step fails.

The one-click script is located at bin/local/release.sh, with documentation at bin/local/README.md. The script automatically limits to the 11 public library modules, excludes examples / service, probes the absolute path of GPG, and performs an independent signing precheck before Maven.

6.1 Step 0: Create the One-Click Release Script​

Create bin/local/release.sh in the repository root; the complete contents are as follows:

#!/usr/bin/env bash
set -euo pipefail

readonly RELEASE_MODULES='agentforge-ai-parent,agentforge-ai-bom,agentforge-model,agentforge-model/agentforge-model-api,agentforge-model/agentforge-model-core,agentforge-model/agentforge-model-openai,agentforge-model/agentforge-model-anthropic,agentforge-model/agentforge-model-registry,agentforge-framework,agentforge-framework/agentforge-agent-core,agentforge-framework/agentforge-harness-agent'

usage() {
    cat <<'EOF'
Usage: bin/local/release.sh <version> [options]

Options:
  --settings <file>  Maven settings.xml (default: $MAVEN_SETTINGS or ~/.m2/settings.xml)
  --dry-run          Build and sign the release artifacts without uploading
  --auto-publish     Upload and publish automatically instead of waiting in Portal
  --skip-tests       Skip tests (not recommended for a formal release)
  -h, --help         Show this help
EOF
}

[[ $# -gt 0 ]] || { usage; exit 1; }
if [[ "$1" == '-h' || "$1" == '--help' ]]; then
    usage
    exit 0
fi

VERSION="$1"
shift
SETTINGS_FILE="${MAVEN_SETTINGS:-${HOME}/.m2/settings.xml}"
DRY_RUN=0
AUTO_PUBLISH=0
SKIP_TESTS=0

while [[ $# -gt 0 ]]; do
    case "$1" in
        --settings)
            [[ $# -ge 2 ]] || { echo 'Error: --settings requires a file path.' >&2; exit 1; }
            SETTINGS_FILE="$2"
            shift 2
            ;;
        --dry-run) DRY_RUN=1; shift ;;
        --auto-publish) AUTO_PUBLISH=1; shift ;;
        --skip-tests) SKIP_TESTS=1; shift ;;
        -h|--help) usage; exit 0 ;;
        *) echo "Error: unknown option: $1" >&2; usage; exit 1 ;;
    esac
done

[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9]+)*$ ]] || {
    echo "Error: invalid release version: $VERSION" >&2
    exit 1
}
[[ "$VERSION" != *-SNAPSHOT ]] || { echo 'Error: a Central release cannot use -SNAPSHOT.' >&2; exit 1; }
[[ -f "$SETTINGS_FILE" ]] || { echo "Error: settings.xml not found: $SETTINGS_FILE" >&2; exit 1; }
command -v mvn >/dev/null || { echo 'Error: mvn was not found in PATH.' >&2; exit 1; }

# GUI Terminal 的 PATH 可能没有 MacPorts / Homebrew，因此显式探测 GPG。
GPG_EXECUTABLE="${GPG_EXECUTABLE:-}"
if [[ -z "$GPG_EXECUTABLE" ]]; then
    for candidate in "$(command -v gpg 2>/dev/null || true)" /opt/local/bin/gpg /opt/homebrew/bin/gpg /usr/local/bin/gpg; do
        if [[ -n "$candidate" && -x "$candidate" ]]; then
            GPG_EXECUTABLE="$candidate"
            break
        fi
    done
fi
[[ -n "$GPG_EXECUTABLE" ]] || { echo 'Error: gpg was not found.' >&2; exit 1; }
export GPG_TTY="${GPG_TTY:-$(tty)}"

# 口令隐藏输入，不放入命令行、POM 或 settings.xml。
if [[ -z "${MAVEN_GPG_PASSPHRASE:-}" ]]; then
    printf 'GPG Passphrase (input hidden): '
    IFS= read -r -s MAVEN_GPG_PASSPHRASE
    printf '\n'
    [[ -n "$MAVEN_GPG_PASSPHRASE" ]] || { echo 'Error: GPG Passphrase cannot be empty.' >&2; exit 1; }
    export MAVEN_GPG_PASSPHRASE
fi

# Maven 前先对临时文件签名和验签，尽早发现错误口令或 GPG 配置。
SIGN_CHECK_FILE="$(mktemp /tmp/agentforge-gpg-check.XXXXXX)"
cleanup_sign_check() {
    rm -f "$SIGN_CHECK_FILE" "${SIGN_CHECK_FILE}.asc"
}
trap cleanup_sign_check EXIT
printf 'AgentForge Maven Central signing check\n' > "$SIGN_CHECK_FILE"
if ! printf '%s\n' "$MAVEN_GPG_PASSPHRASE" | "$GPG_EXECUTABLE" \
    --batch --yes --no-tty --pinentry-mode loopback --passphrase-fd 0 \
    --armor --detach-sign "$SIGN_CHECK_FILE"; then
    echo 'Error: GPG preflight signing failed. Enter the private-key Passphrase created with this GPG key.' >&2
    echo '       Do not enter the Central Token, KEY_ID, fingerprint, or macOS login password.' >&2
    exit 1
fi
"$GPG_EXECUTABLE" --batch --verify "${SIGN_CHECK_FILE}.asc" "$SIGN_CHECK_FILE"
cleanup_sign_check
trap - EXIT

MVN_ARGS=(
    -s "$SETTINGS_FILE"
    -P release
    "-Drevision=${VERSION}"
    "-Dgpg.executable=${GPG_EXECUTABLE}"
    -pl "$RELEASE_MODULES"
)
[[ "$SKIP_TESTS" -eq 1 ]] && MVN_ARGS+=(-DskipTests)

echo ">> version=$VERSION dryRun=$DRY_RUN autoPublish=$AUTO_PUBLISH"
echo ">> settings=$SETTINGS_FILE"
echo ">> gpg=$GPG_EXECUTABLE"

if [[ "$DRY_RUN" -eq 1 ]]; then
    mvn "${MVN_ARGS[@]}" clean verify
    echo '>> Dry run succeeded: artifacts were built and signed; nothing was uploaded.'
    exit 0
fi

if [[ "$AUTO_PUBLISH" -eq 1 ]]; then
    MVN_ARGS+=(-Dcentral.publishing.autoPublish=true -Dcentral.publishing.waitUntil=published)
fi

mvn "${MVN_ARGS[@]}" clean deploy

if [[ "$AUTO_PUBLISH" -eq 1 ]]; then
    echo '>> Central deployment was uploaded and automatic publishing was requested.'
else
    echo '>> Central deployment was uploaded. Review and publish it in the Portal:'
    echo '   https://central.sonatype.com/publishing/deployments'
fi

Do not fill in any Token, Passphrase, or private key contents in the script.

6.2 Step 1: Enter the Repository and Set the Release Parameters​

cd "/absolute/path/AgentForge"

VERSION="1.0.0"
SETTINGS_FILE="/absolute/path/settings.xml"

VERSION must be a non-SNAPSHOT version that has never been published to Central before. SETTINGS_FILE must be located outside the Git repository.

6.3 Step 2: Pre-Release Self-Check​

First run the following in order:

chmod +x bin/local/release.sh
chmod 600 "$SETTINGS_FILE"

# 脚本语法与用法
bash -n bin/local/release.sh
bin/local/release.sh --help

# settings.xml 必须存在；macOS 可额外用 xmllint 检查 XML
test -f "$SETTINGS_FILE"
xmllint --noout "$SETTINGS_FILE"

# 必须能看到至少一把 sec 私钥
GPG_BIN="$(command -v gpg || true)"
[[ -x /opt/local/bin/gpg ]] && GPG_BIN="/opt/local/bin/gpg"
[[ -x /opt/homebrew/bin/gpg ]] && GPG_BIN="/opt/homebrew/bin/gpg"
"$GPG_BIN" --list-secret-keys --keyid-format LONG

# 检查工作树；正式发布建议使用可追溯的 commit/tag
git status --short

# 404 表示该版本尚未出现在 Central；200 时必须换新版本
curl -sS -o /dev/null -w '%{http_code}\n' \
  "https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-ai-parent/${VERSION}/agentforge-ai-parent-${VERSION}.pom"

At the same time, confirm in the Central Portal that the namespace is Verified, that <server id="central"> exists in settings.xml, and that the GPG public key has been uploaded to the keyserver.

6.4 Step 3: One-Click Dry Run (No Upload)​

bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE" \
  --dry-run

When it runs, the script prompts:

GPG Passphrase (input hidden):

Enter the Passphrase you set when creating the current GPG private key. The input is not echoed and does not enter shell history. On success you should see:

[INFO] BUILD SUCCESS
>> Dry run succeeded: artifacts were built and signed; nothing was uploaded.

The result of this actual run: all 10 modules were SUCCESS, and all 28 actually generated .asc files passed local signature verification.

Experience: do not use -Dgpg.skip=true for the final dry run; that can only verify the POM and artifact structure and cannot prove that the real signing pipeline is working.

6.5 Step 4: One-Click Upload (Recommended for the First Time)​

bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE"

This mode runs clean deploy, but the POM has autoPublish=false, so it is only uploaded to the Central Portal and is not made public immediately. Success indicators:

[INFO] BUILD SUCCESS
>> Central deployment was uploaded. Review and publish it in the Portal:
   https://central.sonatype.com/publishing/deployments

The Bundle check results before this actual upload:

• Bundle size about 1.8 MB;
• 168 entries in total;
• Exactly 10 public artifacts;
• Does not include examples / studio;
• POM, main JAR, sources JAR, Javadoc JAR, and the corresponding .asc files are all present.

Demonstration example:

# 打开AgentForge
cd "/Users/edy/changlu_workspace/mymd/我的开源项目/AgentForge"

# 执行一键推送
bin/local/release.sh 1.0.0 \
    --settings "/Users/edy/changlu_workspace/mymd/我的开源项目/maven/settings.xml" \
    --dry-run

The Passphrase entered is the key you set when installing GPG yourself ~

6.6 Step 5: Portal Review and Publish​

Open https://central.sonatype.com/publishing/deployments:

1. Confirm that the deployment's version and artifact count are correct;

2. Wait for the status to become VALIDATED;

3. For the first release, it is recommended to review manually and then click Publish;

   

   At this point it enters the publishing process:

   

4. Wait for the status to become PUBLISHED.

Publish is an irreversible operation. A published GAV version on Central cannot be overwritten, so it is not recommended to use automatic Publish directly for the first time.

Waiting time after Publish:

• After clicking Publish, VALIDATED usually moves to PUBLISHING immediately;
• PUBLISHING → PUBLISHED generally takes a few minutes, commonly about 1～10 minutes;
• After PUBLISHED, syncing to repo1.maven.org usually takes another few minutes;
• The Central Search index usually updates within a few minutes after publishing, but may be later than the public repository.

It is recommended to refresh the Deployments page every 1～2 minutes; do not upload repeatedly. After the status becomes PUBLISHED, you can check the public repository directly:

curl -sS -L -o /dev/null -w '%{http_code}\n' \
  'https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-agent-core/1.0.0/agentforge-agent-core-1.0.0.pom'

A return of 200 means it is publicly available; a return of 404 means to keep waiting for synchronization. If it remains at PUBLISHING for more than 30 minutes, first check https://status.maven.org/; if it is still not complete after more than 1 hour, record the deployment ID and contact central-support@sonatype.com.

6.7 Step 6 (Optional for Later Versions): One-Click Automatic Publish​

VERSION="1.0.1"
bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE" \
  --auto-publish

--auto-publish dynamically overrides the POM's autoPublish=false and uses waitUntil=published to wait for Central to finish publishing. It should only be used after the first manual release has been verified successfully.

6.8 Step 7: Post-Release Verification​

• The Portal Deployments status is PUBLISHED;

• Search for the full groupId cloud.changlu.agentforge or the artifactId agentforge-agent-core at https://central.sonatype.com/;

• Directly check repo1.maven.org/maven2/<groupId 路径>/<artifactId>/<version>/;

• Actually reference it in a blank Maven project:

  <dependency>
      <groupId>cloud.changlu.agentforge</groupId>
      <artifactId>agentforge-agent-core</artifactId>
      <version>1.0.0</version>
  </dependency>
  

You can first use the HTTP status for a cache-free core verification:

curl -sS -L -o /dev/null -w '%{http_code}\n' \
  'https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-agent-core/1.0.0/agentforge-agent-core-1.0.0.pom'

• 200: the artifact has entered the Maven Central public repository;
• 404 and the Portal is VALIDATED: only the upload is complete; you still need to click Publish on the Deployments page;
• The Portal is PUBLISHING: keep waiting; do not upload repeatedly;
• The Portal is PUBLISHED but it is still 404: the public repository is syncing; retry later;
• repo1.maven.org already returns 200 but Central Search cannot find it: this is just a search index delay.

After the Portal shows PUBLISHED, syncing to Central Search and mirror repositories may still take tens of minutes; the Portal status and repo1.maven.org are authoritative. The script does not contain any credentials: the Central Token is read only from settings.xml, and the GPG Passphrase exists only in the current release process.

7. FAQ and Notes​

8. Summary​

The complete path to publishing to Maven Central can be summarized as:

1. Choose a namespace: without a domain use io.github.<username>; with a domain use the reverse domain (this scheme chooses cloud.changlu);
2. Pass verification: for the domain approach add a DNS TXT; for the GitHub approach create a public repository;
3. Prepare keys and passphrase: GPG key pair + Portal User Token + settings.xml;
4. Modify the build: add metadata and a release profile (sources / javadoc / gpg / central) in the parent;
5. Run the release: --dry-run dry run → formal deploy → Portal Publish → verify the dependency;
6. Stay sustainable: use release.sh to solidify the process, increment the version number, and never overwrite.

At this point, AgentForge's library modules can be imported directly by Java developers all over the world through a single dependency coordinate.

References​

[1]. Sonatype Central Portal Official Documentation

[2]. Choosing your Coordinates (groupId namespace)

[3]. Requirements (sources/javadoc, GPG, POM metadata)

[4]. Publishing By Using the Maven Plugin

[5]. Generating a Portal Token for Publishing

[6]. How do I set the TXT record needed to prove ownership of my Web Domain?

[7]. GPG Requirements

[8]. central-publishing-maven-plugin (Maven Central Artifact)

Compiled by: Changlu　Created: 2026.10.4　Updated: 2026.10.5

This article unfolds progressively along the line of "background/problem introduction → core concepts → mainstream framework research → implementation approach → hands-on code → verification testing → summary", in seven parts.

One-sentence conclusion: Among the three parties, only LangChain4j has its own in-house protocol stack; both Spring AI and AgentScope Java are based on the official MCP Java SDK; while AgentForge chooses "in-house core protocol stack + optional official SDK bridge". Let's clarify the full story behind this conclusion below.

1. Background and Problem Introduction​

1.1 Scenario Drive: A Real Integration Challenge​

When planning MCP ecosystem integration for AgentForge, we ran into this concrete problem:

The team hoped AgentForge's ReActAgent could directly consume the ready-made tools in the MCP ecosystem (filesystem, git, fetch, database…). But AgentForge has a hard constraint—Java 8 compatibility, zero third-party dependencies in the core. And looking across the Java ecosystem, both Spring AI and AgentScope chose the official MCP Java SDK, yet that SDK requires JDK 17+ and also pulls in Jackson, Reactor, and SLF4J.
So the question arose: Should we follow the official SDK or not?

This is not a confusion unique to AgentForge. Any framework oriented toward "low JDK / zero dependencies" will hit the same wall when integrating MCP.

1.2 Problem Guidance: What Do We Need to Answer?​

1. For the three mainstream Java frameworks, do they support stdio and HTTP? To what extent?
   
2. Is their protocol "hand-written by themselves" or "based on the official MCP Java SDK"?
   
3. How should AgentForge choose? In-house or official? To what extent should it support?
   
4. After implementation, how do we unify it with AgentForge's existing http / local tool modes?

1.3 Research Scope and Comparison Baseline​

Research targets: LangChain4j, Spring AI, AgentScope Java. The comparison baseline is the official MCP Java SDK.

2. Core Concepts​

2.1 Two Technical Routes: Official SDK vs In-House​

2.1.1 Route One: Based on the Official Java SDK​

Protocol details (JSON-RPC, version negotiation, transport framing) are maintained by the official team, and the framework only does thin wrapping + ecosystem integration.

• Pros: Worry-free, easy to pass conformance tests, full-featured, fast to follow the spec.
• Downside explanation: JDK 17+, pulls in Jackson / Reactor / SLF4J, hard to embed into low-JDK / zero-dependency projects.

2.1.2 Route Two: In-House Protocol Stack​

The framework implements McpTransport / McpClient / JSON-RPC routing itself.

• Pros: Full control over dependencies and API, can be compatible with lower JDKs, zero extra dependencies.
• Downside explanation: Must follow spec revisions on your own, and do dual-era compatibility and conformance verification.

Key point: These two routes have no absolute superiority; it only depends on the framework's own constraint orientation—which is exactly the root cause of the three-way divergence and also the root cause of AgentForge's decision.

2.2 The Official SDK's Three-Layer Architecture (for Reference)​

Client/Server layer   Protocol operations (listTools / callTool / initialize)
        ↓
Session layer         Communication mode and connection state
        ↓
Transport layer       JSON-RPC send/receive and serialization (STDIO / HTTP / SSE)

2.3 Three-Way Overview​

3. Mainstream Framework Research​

3.1 LangChain4j: In-House Protocol Stack​

3.1.1 Did It Actually Use the Official SDK?​

MCP capabilities are in the dev.langchain4j:langchain4j-mcp module. Checking its pom.xml dependencies: langchain4j, langchain4j-core, jackson-databind, langchain4j-http-client(-jdk), langchain4j-open-ai. There is no io.modelcontextprotocol.sdk—meaning the protocol is self-implemented.

Key point: It is the only self-developed one among the three (its own McpTransport / DefaultMcpClient / McpOperationHandler).

3.1.2 stdio Support​

• StdioMcpTransport: ProcessBuilder spawns a child process, reading and writing JSON-RPC line by line.
• A separate module langchain4j-mcp-docker provides DockerMcpTransport (containerized stdio server).
• The server side (building a stdio server) is placed in LangChain4j Community.

3.1.3 HTTP Support​

• StreamableHttpMcpTransport: based on the JDK HttpClient, POST to a single endpoint; optional subsidiaryChannel(true) opens a GET SSE subsidiary channel (legacy).
• HttpMcpTransport: old HTTP+SSE, already @Deprecated(forRemoval).
• WebSocketMcpTransport: non-standard extra transport, compatible with the Quarkus MCP Server extension.

3.1.4 Protocol Versions and Tool Governance​

• Supports both legacy (2025-11-25) and modern (2026-07-28), with automatic detection by default (server/discover → fall back to initialize on failure).
• Tool capabilities: McpToolProvider supports filtering by name, toolNameMapper, toolSpecificationMapper, multi-client aggregation; DefaultMcpClient has a built-in tool list cache; supports x-mcp-header, _meta injection, resource subscription.
• Also has a MCP Registry read-only client.

3.2 Spring AI: Based on the Official Java SDK​

3.2.1 Did It Actually Use the Official SDK?​

Spring AI MCP explicitly adopts the official MCP Java SDK, and its documentation directly presents the SDK's three-layer architecture. Since Spring AI 2.0, the official SDK 1.0.0+ is required.

Note (migration point): mcp-spring-webflux / mcp-spring-webmvc migrated from io.modelcontextprotocol.sdk to org.springframework.ai; the relevant transport class package names also changed from io.modelcontextprotocol.* to org.springframework.ai.mcp.*.

3.2.2 stdio Support​

• Client: spring-ai-starter-mcp-client provides STDIO.
• Server: spring-ai-starter-mcp-server (spring.ai.mcp.server.stdio=true).

3.2.3 HTTP Support​

• Client: spring-ai-starter-mcp-client (Servlet version Streamable-HTTP / Stateless / SSE), spring-ai-starter-mcp-client-webflux (WebFlux version).
• Server: spring-ai-starter-mcp-server-webmvc / -webflux, switched with spring.ai.mcp.server.protocol = SSE | STREAMABLE | STATELESS.

3.2.4 Annotations and Governance​

• Server annotations: @McpTool, @McpResource, @McpPrompt, @McpComplete.
• Client annotations: @McpLogging, @McpSampling, @McpElicitation, @McpProgress.
• Tool adaptation: SyncMcpToolCallback / AsyncMcpToolCallback, SyncMcpToolCallbackProvider, McpToolUtils.

Key point: Spring AI does not implement the protocol itself, but rather thin-wraps the official SDK + fills out the Spring Boot experience (Starter / annotations / WebMVC·WebFlux transports).

3.3 AgentScope Java: Based on the Official Java SDK​

3.3.1 Did It Actually Use the Official SDK?​

AgentScope Java's McpClientBuilder internally reuses the transport and client classes of the official io.modelcontextprotocol SDK, ultimately wrapping them into McpAsyncClient / McpSyncClient, and injects AgentScope's version and User-Agent.

3.3.2 stdio Support​

McpClientWrapper client = McpClientBuilder.create("filesystem-mcp")
        .stdioTransport("npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
        .buildAsync().block();

3.3.3 HTTP Support​

• sseTransport(url): SSE (stateful streaming).
• streamableHttpTransport(url): Streamable HTTP (stateless streaming).
• Supports .header(...) / .queryParam(...), .timeout(...), .initializationTimeout(...), .protocolVersions(...), elicitation callback.

3.3.4 Tool Governance​

• Toolkit.registerMcpClient(...) for unified registration; enableTools / disableTools whitelist and blacklist; group(...) tool grouping; removeMcpClient(...) dynamic removal.
• Namespace convention: mcp__{server}__{tool}.
• Also has the Higress AI gateway extension (semantic tool retrieval).

Note: By default it only declares 2024-11-05; connecting to newer servers requires explicitly protocolVersions(...), otherwise it reports "Unsupported protocol version".

3.4 Horizontal Comparison​

3.4.1 stdio / HTTP Support Matrix​

3.4.2 Implementation and Constraints​

3.5 Comparative Analysis and Selection Recommendations​

3.5.1 Three Selection Scenarios​

• Option One: Already a Spring Boot application → Spring AI. Official SDK + Starter is the least hassle, but you're bound to the Spring ecosystem.
• Option Two: Multi-Agent orchestration / need tool governance and gateway → AgentScope Java. Tool grouping, namespaces, and Higress gateway retrieval are the most complete.
• Option Three: Already using LangChain4j or need to escape official SDK constraints → LangChain4j. In-house protocol stack, controllable dependencies.

Downside explanation: All three directly or indirectly require JDK 17+ and pull in third-party libraries. Any project that is "low JDK / zero dependencies" satisfies none of the three—the only option is in-house.

3.5.2 Summary​

• At the transport level: All three support stdio and HTTP (Streamable HTTP).
• At the implementation level: LangChain4j is in-house, Spring AI and AgentScope are based on the official SDK.
• Inference: The official SDK is the de facto standard, but it raises the JDK bar to 17—which is exactly where AgentForge needs to make a separate decision.

4. AgentForge Implementation Approach​

4.1 AgentForge Current State and Constraints​

4.1.1 Hard Constraints​

Key point: The official MCP Java SDK requires JDK 17+ and pulls in Jackson + Reactor + SLF4J, which directly conflicts with AgentForge's core constraints.

4.1.2 Reusable Tool Abstractions​

Key point: MCP and AgentForge's tool abstractions are naturally isomorphic, and the integration point is the implementation of ToolExecutor.

4.1.3 Existing Mode Conventions​

agent-core already has two tool modes, following the same "factory + executor + subpackage" pattern:

tool/local/   LocalToolFactory + LocalToolExecutor + support/
tool/http/    HttpToolFactory  + HttpToolExecutor  + domain/ enums/ support/ parser/
tool/mcp/     (newly added in this article, aligned with the above conventions)

4.2 Implementation Approach: Official SDK vs In-House​

4.2.1 Option Comparison​

Option One: Based on the official MCP Java SDK

• Pros: Protocol maintained officially, easy to pass conformance tests, full-featured.
• Downside explanation: JDK 17+, pulls in Jackson / Reactor / SLF4J, breaking the core's zero dependencies; requires an extra bridge layer to adapt ToolExecutor.

Option Two: In-house protocol stack

• Pros: Java 8 compatible, zero extra dependencies, seamless with ToolExecutor, reuses the built-in Json and HttpTransport.
• Downside explanation: Must follow spec revisions on your own, and do dual-era compatibility and conformance verification.

Option Three: Hybrid (in-house core + official bridge)

• The core (agentforge-agent-core) uses an in-house protocol stack, maintaining zero dependencies (already delivered);
• Additionally, an optional module agentforge-mcp-sdk-bridge (JDK 17), wrapping the official SDK's McpClient into AgentForge's ToolExecutor (P3 planned, not yet implemented).

Conclusion: The target form adopts Option Three—the main path is delivered in-house first, and the official SDK serves as an optional bridge to be filled in later, both safeguarding the core constraints and not locking users into the in-house protocol stack.

4.2.2 Decision Basis​

4.2.3 How Bridging Resolves the JDK 17 Conflict​

Question: The official SDK requires JDK 17, so doesn't setting up an "official bridge" module bring JDK 17 back again? Can JDK 8 still use MCP at all?

First, let's clarify: MCP is a JSON-RPC protocol, independent of the JDK; JDK 17 is the bar for "the official Java SDK implementation", not the bar for MCP. JDK 8 can fully implement MCP—ProcessBuilder (stdio) + HttpURLConnection (HTTP) + the built-in Json is enough, no Jackson / Reactor needed.

Key principle: one-way dependencies, upward bytecode compatibility. A module compiled with JDK 17 can depend on a module compiled with Java 8, but not the reverse. So let bridge depend on core, not core depend on bridge:

agentforge-agent-core (release 8 / zero dependencies)
   ▲  defines ToolExecutor / McpClient / ToolSpecification
   │  ← only depended upon, contains no MCP implementation
agentforge-mcp-sdk-bridge (release 17)
    depends on core + official SDK + Jackson / Reactor / SLF4J
    wraps the official McpClient into core's ToolExecutor

Thus JDK 17 types, Jackson, Reactor, and SLF4J are all locked inside the bridge, and will never appear on core's compile or runtime path.

JDK Version × Implementation Path

Key point: The in-house stack is not JDK 8-exclusive; it also runs on JDK 17 / 21; the official bridge is "opt-in", not switched automatically by JDK version. The two paths are a deployment-time either/or choice, decided by the user.

Isolation Techniques

• Build isolation: Multi-module project, core uses maven.compiler.release=8, bridge uses 17; core's POM never declares bridge, so Jackson / Reactor / SLF4J cannot enter core's dependency tree.
• Runtime isolation: The bridge is a separate artifact; JDK 8 users never load it unless they include it, avoiding UnsupportedClassVersionError.
• Interface isolation: Core only exposes Java 8's ToolExecutor / McpClient, the bridge internally is compatible with official types, and only implements core interfaces upward.
• Optional lazy loading: Use Java 8's built-in java.util.ServiceLoader to define the McpClientFactory SPI—if a bridge is present it is discovered, otherwise it falls back to the in-house DefaultMcpClient, keeping core zero-dependency throughout.

Conclusion: Bridging is not "running the JDK 17 SDK on Java 8", but rather opening an optional, isolated door for users who "are willing to upgrade to JDK 17 and want official capabilities"; users who don't upgrade to JDK 17 go entirely with the in-house stack, and the two paths are each clean.

Current progress: The in-house protocol stack is implemented; agentforge-mcp-sdk-bridge and the McpClientFactory SPI are both P3 planned, not yet delivered.

4.3 Overall Architecture and Packaging​

4.3.1 Directory Structure​

agentforge-agent-core/src/main/java/cloud/changlu/agentforge/agent/tool/
├── mcp/
│   ├── McpToolFactory.java         # Build entry: listTools → Map<ToolSpecification, ToolExecutor>
│   ├── McpToolExecutor.java        # implements ToolExecutor: tools/call
│   ├── McpClient.java              # Client interface: serverAlias / listTools / callTool / close
│   ├── DefaultMcpClient.java       # JSON-RPC lifecycle (initialize handshake, lazy initialization)
│   ├── McpProtocolException.java   # JSON-RPC error → exception
│   ├── McpTransportException.java  # Transport failure exception
│   ├── domain/
│   │   ├── McpTool.java
│   │   ├── McpCallToolResult.java
│   │   ├── McpContent.java
│   │   ├── McpServerInfo.java
│   │   └── McpCapabilities.java
│   ├── transport/
│   │   ├── McpTransport.java       # SPI for send / request / close
│   │   ├── StdioMcpTransport.java
│   │   └── StreamableHttpMcpTransport.java
│   └── support/
│       ├── JsonRpcCodec.java
│       ├── McpJson.java
│       ├── McpToolSpecificationMapper.java
│       └── McpResultConverter.java

4.3.2 Layered Responsibilities​

┌──────────────────────────────────────────────┐
│ McpToolFactory / McpToolExecutor              │  Connects to Agent tool table
├──────────────────────────────────────────────┤
│ DefaultMcpClient (id increment, handshake, lazy init) │  Protocol layer
├──────────────────────────────────────────────┤
│ McpTransport (stdio / Streamable HTTP)        │  Transport layer
└──────────────────────────────────────────────┘

4.4 Core Design and Mapping​

4.4.1 McpToolExecutor implements ToolExecutor​

public class McpToolExecutor implements ToolExecutor {

    private final McpClient client;        // Bound at construction: which MCP Server this tool belongs to
    private final String remoteToolName;   // Bound at construction: the original tool name on the Server (without alias prefix)

    public McpToolExecutor(McpClient client, String remoteToolName) {
        this.client = client;
        this.remoteToolName = remoteToolName;
    }

    /** Simplified interface: returns text only. */
    @Override
    public String execute(ToolExecutionRequest request, Object memoryId) {
        // Step ①: the arguments given by the model are a JSON string → restore to a Map
        Map<String, Object> args = McpJson.argumentsAsMap(request.arguments());
        // Step ②: use the bound original remote name to send tools/call, and flatten content into text
        return McpResultConverter.toText(client.callTool(remoteToolName, args));
    }

    /** Structured interface: additionally carries structuredContent and isError. */
    @Override
    public ToolExecutionResult executeWithResult(ToolExecutionRequest request, Object memoryId) {
        try {
            // Step ①: JSON string → Map (nested objects/arrays kept as-is)
            Map<String, Object> args = McpJson.argumentsAsMap(request.arguments());
            // Step ②: determine "which Server to send to, which tool to call"—decided by the two fields bound at construction
            McpCallToolResult result = client.callTool(remoteToolName, args);
            // Step ③: lossless mapping back to AgentForge result
            return ToolExecutionResult.builder()
                    .isError(result.isError())                    // isError passed through as-is
                    .result(result.structuredContent())           // structuredContent → result
                    .text(McpResultConverter.toText(result))      // content text → text (fed back to model)
                    .build();
        } catch (McpProtocolException e) {                        // JSON-RPC error (e.g. -32601)
            return ToolExecutionResult.failure("MCP protocol error: " + e.getMessage(), e);
        } catch (McpTransportException e) {                       // transport failure / timeout
            return ToolExecutionResult.failure("MCP transport error: " + e.getMessage(), e);
        }
    }
}

4.4.2 McpToolFactory: List → Spec + Executor​

Core steps: ① Parse the alias (explicit takes priority, otherwise client.serverAlias()) → ② Fetch native tools (tools/list) → ③ White/blacklist filtering → ④ Concatenate alias to generate the model-visible name → ⑤ Bind McpToolExecutor(client, original name) → ⑥ Hand to ToolService to build the table by spec.name().

public final class McpToolFactory {

    private McpToolFactory() {}

    /** Use the client's own serverAlias as the prefix. */
    public static Map<ToolSpecification, ToolExecutor> buildTools(McpClient client) {
        return buildTools(client, null, null, null);
    }

    /** Explicit alias takes priority, falling back to client.serverAlias() when blank. */
    public static Map<ToolSpecification, ToolExecutor> buildTools(
            McpClient client, String serverAlias) {
        return buildTools(client, serverAlias, null, null);
    }

    /** When enabledTools is non-empty, only the remote tool names within it are exposed; those matched by disabledTools are hidden. */
    public static Map<ToolSpecification, ToolExecutor> buildTools(
            McpClient client, String serverAlias,
            Set<String> enabledTools, Set<String> disabledTools) {
        // Step ①: determine the prefix—explicit alias takes priority, otherwise read client.serverAlias()
        String alias = (serverAlias != null && !serverAlias.trim().isEmpty())
                ? serverAlias : client.serverAlias();

        Map<ToolSpecification, ToolExecutor> result = new LinkedHashMap<>();

        // Step ②: fetch the Server's native tools (the first call triggers initialize → initialized → tools/list)
        for (McpTool tool : client.listTools()) {

            // Step ③: white/blacklist filtering (determined by "original tool name")
            if (enabledTools != null && !enabledTools.isEmpty()
                    && !enabledTools.contains(tool.name())) {
                continue;
            }
            if (disabledTools != null && disabledTools.contains(tool.name())) {
                continue;
            }

            // Step ④: concatenate alias to generate the model-visible name; inputSchema passed through as-is; write ownership metadata
            ToolSpecification spec = ToolSpecification.builder()
                    .name(qualify(alias, tool.name()))          // fs__read_file
                    .description(tool.description())
                    .parameters(McpToolSpecificationMapper.toToolParameters(tool.inputSchema()))
                    .addMetadata("mcp.server", alias == null ? "" : alias)
                    .addMetadata("mcp.tool", tool.name())
                    .build();

            // Step ⑤: bind (client + original remote name)—used at runtime to route back to the corresponding Server
            result.put(spec, new McpToolExecutor(client, tool.name()));
        }
        // Step ⑥: return the spec→executor mapping, handed to ToolService.tools(...) to build the table by spec.name()
        return result;
    }

    private static String qualify(String alias, String toolName) {
        return (alias == null || alias.trim().isEmpty()) ? toolName : alias + "__" + toolName;
    }
}

4.4.3 Schema Mapping (Zero Loss)​

public static ToolParameters toToolParameters(Map<String, Object> inputSchema) {
    if (inputSchema == null || inputSchema.isEmpty()) {
        return ToolParameters.empty();      // {"type":"object","properties":{}}
    }
    return ToolParameters.from(inputSchema); // pass through JSON Schema as-is
}

4.4.4 Error Mapping​

5. AgentForge Hands-On Code​

5.1 Minimal Integration: Two Transports​

5.1.1 Integrating a Local stdio Server​

// 1) Start a stdio MCP Server (local child process, newline-framed JSON-RPC)
McpClient fs = DefaultMcpClient.builder()
        .serverAlias("fs")
        .transport(StdioMcpTransport.builder()
                .command("npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
                .build())
        .build();

// 2) Fetch tools and register into ToolService (reads the client's serverAlias, auto-prefixes: fs__read_file)
ToolService toolService = new ToolService();
toolService.tools(McpToolFactory.buildTools(fs));

// 3) Coexist with local @Tool (same tool table)
toolService.tools(new WeatherTools());

// 4) Assemble the ReActAgent
ReActAgent agent = ReActAgent.builder()
        .chatModel(chatModel)
        .toolService(toolService)
        .build();

Key point: DefaultMcpClient is lazy—the initialize handshake and notifications/initialized are sent only on the first listTools() / callTool(), and tools/list is sent afterward. StdioMcpTransport.of("npx", "-y", ...) is an equivalent shorthand.

5.1.2 Integrating a Remote Streamable HTTP Server​

McpClient remote = DefaultMcpClient.builder()
        .serverAlias("github")
        .transport(StreamableHttpMcpTransport.builder()
                .endpoint("https://mcp.example.com/mcp")
                .header("Authorization", "Bearer " + token) // custom headers passed through with the request
                .build())
        .build();

toolService.tools(McpToolFactory.buildTools(remote)); // reads the client's serverAlias, tool names look like github__search_repos

The difference from stdio is only at the transport layer: serverAlias="github" → model-visible name github__search_repos; the positioning and parameter conversion of buildTools / ToolService / ToolExecutor are completely identical. On the HTTP side, each tools/call is a POST:

• Request body = the aforementioned JSON-RPC ({"jsonrpc","id","method":"tools/call","params":{...}});
• After the handshake, MCP-Protocol-Version is automatically included, and custom headers (Authorization) are passed through as-is;
• The response is extracted by id (application/json or SSE data:), then goes through the same content / isError mapping.

5.1.3 On-Demand Filtering and Closing​

// Only expose read_file, hide the rest of the tools (empty/null whitelist means all)
Map<ToolSpecification, ToolExecutor> tools =
        McpToolFactory.buildTools(
                client, "fs",
                Collections.singleton("read_file"), // whitelist
                null);                              // blacklist

client.close(); // stdio: close and reclaim the child process; HTTP: release the transport

5.1.4 Underlying Core Principle: How a Single Query Is Closed Loop (Real function call Sequence)​

Scenario: MCP fs (filesystem) and MCP weather are registered at the same time, and the user asks "read out the contents of /tmp/a.txt, and check the weather in Hangzhou". The following unfolds in the order actually occurring.

① The MCP Server first returns the native tools/list (without prefix)

AgentForge first calls tools/list on each Server and gets the tool's own name (at this point there is no fs__ prefix yet):

// ← fs server's tools/list response
{"jsonrpc":"2.0","id":1,"result":{"tools":[
  {"name":"read_file","description":"Read a file","inputSchema":
    {"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}}
]}}

// ← weather server's tools/list response
{"jsonrpc":"2.0","id":2,"result":{"tools":[
  {"name":"get_weather","description":"Query weather","inputSchema":
    {"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}
]}}

② The middleware assembles the alias (McpToolFactory)

buildTools(client) transforms the above original tools: alias__original name, and at the same time binds the executor and writes it into ToolService:

fs      + read_file    → spec.name = "fs__read_file"        + McpToolExecutor(fsClient,      "read_file")
weather + get_weather  → spec.name = "weather__get_weather" + McpToolExecutor(weatherClient, "get_weather")

Note: The original name is always retained in the executor (read_file / get_weather), and the prefix is only added to the model-visible name—this is the basis for the subsequent "strip prefix, send original name".

③ The tools[] seen by the large model (alias form)

[
  {"type": "function", "function": {"name": "fs__read_file",
    "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}}},
  {"type": "function", "function": {"name": "weather__get_weather",
    "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}}
]

④ The combined function call returned by the model (OpenAI form, two at a time)

{
  "role": "assistant",
  "tool_calls": [
    {
      "id": "call_a1b2",
      "type": "function",
      "function": {
        "name": "fs__read_file",
        "arguments": "{\"path\":\"/tmp/a.txt\"}"
      }
    },
    {
      "id": "call_c3d4",
      "type": "function",
      "function": {
        "name": "weather__get_weather",
        "arguments": "{\"location\":\"杭州\"}"
      }
    }
  ]
}